Omise.js

Omise.jsは、カード保有者のブラウザから機密情報を直接Omiseサーバーに送信することで、カード情報を安全に管理するJavaScriptライブラリです。カード情報は、一度限りしか利用できないトークンに変換されます。トークンは課金の作成に利用できるほか、顧客オブジェクトに紐付けて保存することができます。

このドキュメントでは、Omise.jsを使用して、アプリ内の購入ページ、および入力フォームの作成手順について説明します。

Omise.jsの使用推奨の詳細については、セキュリティ対策をご参照ください。

Country support

Country Payment methods
Thailand credit_card, internet_banking, alipay, bill_payment_tesco_lotus
Japan credit_card, pay_easy, net_banking, convenience_store

お客様で用意された決済フォームにOmise.jsを実装する

パブリックメソッド

以下は、ご利用の決済フォームからカード情報をOmiseサーバーに送信し、一度限りしか利用できないトークンを作成するために必要な手順です。

パブリックキーの設定

scriptタグを使って、Omise APIを呼び出す際の認証に使用されるパブリックキーの設定を行ないます。 認証に関する詳細については、認証をご参照ください。

Argument Value
キー (必須) key とはサインイン後に dashboard 上で確認できるパブリックキーを指しています。

<script>
  Omise.setPublicKey("pkey_test_4xpip92iqmehclz4a4d");
</script>

ソースの作成 (type, object, callback)

ソースオブジェクトをOmiseサーバー送信し、一度だけ利用可能な課金を作成します。

Argument
type (必須) 作成したいトークンのタイプです。 現時点でこの値(type)は常に card と設定してください。
object (必須) ソースに必要な2つの値を含むJavaScriptオブジェクト: currencyamount。パラメータの詳細は こちらをご参照ください。
callback (必須) Omiseサーバーへのリクエストが完了する際に(正常時もエラー時も)呼び出されるコールバック関数です。2つの引数がコールバック関数に戻されます。最初の引数はHTTPステータスコードで、正常時は200、エラー時は400などが返されます。2つ目の引数は Omise API からのレスポンスとなります。

<script>
  Omise.createSource(type, object, function(statusCode, response) { /* callback */ });
</script>

トークンの作成(type, object, callback)

カードオブジェクトをOmiseサーバー送信し、一度限りしか利用できないトークンを作成します。トークン化されたカード情報は、顧客オブジェクトに紐付けるため、また、課金要求をAPIで作成するために使用されます。 

Argument
type (必須) 作成したいトークンのタイプです。 現時点でこの値(type)は常に cardと設定してください。
object (必須) カードに必要な5つの値。name, number, expiration_month, expiration_year, security_codeを含むjavascriptオブジェクトです。パラメータの詳細はこちらをご参照ください。
callback (必須) Omiseサーバーへのリクエストが完了する際に(正常時もエラー時も)呼び出されるコールバック関数です。2つの引数がコールバック関数に戻されます。最初の引数はHTTPステータスコードで、正常時は 200 、エラー時は 400 などが返されます。2つ目の引数は Omise API からのレスポンスとなります。

<script>
  Omise.createToken('card', cardObject, function(statusCode, response) { /* callback */ });
</script>

使用例

ここではOmise.jsをお客様で用意された決済入力フォームに実装する手順をご説明します。

  1. Omise.jsをご利用のHTMLページに挿入する
  2. 決済フォームを実装する
  3. 決済フォームのイベントを処理し、Omise.jsにデータを送信するためのJavaScriptファイルを実装する

ステップ1 Omise.jsをご利用のHTMLページに挿入する

checkout.htmlという名前の購入ページをすでに作成していると仮定します。 Omise.jsをお客様の購入ページに挿入してください。

Omiseがホストしている2つのCDNからお選びいただけます。

  • プライマリCDN (シンガポール) : https://cdn.omise.co/omise.js
  • セコンダリーCDN (日本) : https://cdn2.omise.co/omise.js

<body>
  <!-- .. ここにコードを記入します .. -->

  <script src="https://cdn.omise.co/omise.js"></script>
</body>

ステップ2 決済フォームを実装する

HTMLを使用してご自分の決済フォームを作成します。こちらの決済フォームに非表示の入力フォーム欄を追加してください。この欄はOmise.jsから返されるOmiseトークン情報を送信するために使用されます。  

実際のフォーム送信アクションを実行する前に、Omise.jsにカード情報を送信するための、フォーム送信イベントを処理するJavaScriptファイルを実装する必要があります。この例では、「app.js」という名前が使用されます。購入ページにこのファイルを含めてください。

HTMLの例(checkout.html)

<body>
  <!--
  こちらが チェックアウト・フォームとなります。

  注:ここでは、 `data-name` を使用して、クレジットカード情報欄をHTTP POST経由でバックエンドサーバに送信しないようにしています。
  (セキュリティ対策の参照先: https://www.omise.co/ja/security-best-practices#never-send-card-data-through-your-servers).
  -->
  <form id="checkout-form" action="/checkout.php" method="POST">

    <!-- こちらはomiseトークンを入力するために追加すべき非表示入力欄です -->
    <input type="hidden" name="omiseToken" />

    <!-- こちらはトークン化に必要なカード情報欄です -->
    <div>
      <label>Card Number</label>
      <input type="text" data-name="cardNumber" placeholder="••••••••••••••••" />
    </div>

    <div>
      <label>Name on card</label>
      <input type="text" data-name="nameOnCard" placeholder="Full Name" />
    </div>

    <div>
      <label>Expiry date</label>
      <select data-name="expiryMonth">
        <option value="">MM</option>
        <option value="1">1</option>
        <!-- ... -->
        <option value="12">12</option>
      </select>

      <select data-name="expiryYear">
        <option value="">YYYY</option>
        <option value="2017">2017</option>
        <!-- ... -->
        <option value="2025">2025</option>
      </select>
    </div>

    <div>
      <label>Security code</label>
      <input type="text" data-name="securityCode" placeholder="123" />
    </div>

    <div>
      <button>Checkout</button>
    </div>
  </form>

  <!-- omise.jsを含めます。 -->
  <script src="https://cdn.omise.co/omise.js"></script>

  <!-- お客様のapp.jsを含めます。 -->
  <script src="app.js"></script>
</body>

ステップ3 JavaScriptファイルを実装する

パブリックキーを設定し、決済フォームからカード情報を収集します。 Omise.createToken()を実行することで、 Omiseサーバーに情報を送信しトークン化します。Omiseは Omise Token ID を作成し、 Omise.createToken(type, object, callback) メソッドのcallback関数に返します。

次に、ステップ2で決済フォームで作成した非表示の入力欄にトークンIDを割り当て、実際のフォーム送信アクションを実行し、Omiseトークンをバックエンドサーバーに送信します。

送信される前にカードデータがトークンの形式でエンコードされることで、機密情報の盗難から保護されます。

JavaScriptの例(app.js)

// OmiseパブリックキーをOmise APIに対し認証するように設定します。これでカード情報を直接Omiseに送る準備ができました。
Omise.setPublicKey('YOUR_PUBLIC_KEY');

var checkoutForm = document.getElementById('checkout-form')
    checkoutForm.addEventListener('submit', submitHandler, false);

// チェックアウトフォームのsubmitイベントハンドラ
function submitHandler(event) {
  event.preventDefault();

  /*
  注意: `data-name` を使用して、クレジットカード情報欄をHTTP Post経由でバックエンドサーバに送信しないようにご注意下さい。
  (セキュリティのベストプラクティスを参照のこと https://www.omise.co/ja/security-best-practices#never-send-card-data-through-your-servers).
  */
  var cardObject = {
    name:             document.querySelector('[data-name="nameOnCard"]').value,
    number:           document.querySelector('[data-name="cardNumber"]').value,
    expiration_month: document.querySelector('[data-name="expiryMonth"]').value,
    expiration_year:  document.querySelector('[data-name="expiryYear"]').value,
    security_code:    document.querySelector('[data-name="securityCode"]').value
  };

  Omise.createToken('card', cardObject, function(statusCode, response) {
    if (statusCode === 200) {
      // 成功:Omiseトークンをチェックアウトフォームに戻します。
      checkoutForm.omiseToken.value = response.id;

      // 次に、フォーム送信アクションを実行します。
      checkoutForm.submit();
    }
    else {
      // エラー時:エラーメッセージが表示されます。`response.message` には整形済みエラーメッセージが含まれます。
      // カード情報に対して有効性エラーが発生した場合は
      // `response.code`の値は "invalid_card" となります。

      console.log(response.message);
    }
  });
}

HTMLおよびJavaScriptファイルの全サンプルコードは、こちらでご参照いただけます 。

バックエンド側でトークン情報を POST リクエストで受け取り、課金の要求処理をします。

PHPの例(checkout.php)

<?php

require_once dirname(__FILE__).'/omise-php/lib/Omise.php';

define('OMISE_PUBLIC_KEY', 'pkey_test_52jyu0r8o4307z0zz00');
define('OMISE_SECRET_KEY', 'skey_test_52jyu0r8mim84ylp454');

$charge = OmiseCharge::create(array(
  'amount'   => 10000,
  'currency' => 'thb',
  'card'     => $_POST["omiseToken"]
));

if ($charge['status'] == 'successful') {
  // 注文状況を 'successful'に更新します。
} else {
  // 注文状況を 'failed'に更新します。
}

詳細は 決済を行うをご参照ください。

Omise既成デザインの決済入力フォームを利用する

Omise.jsには、 チェックアウトページに簡単に組み込める、既成デザインの決済入力フォームが用意されています。このフォームに入力されたカード情報はOmiseサーバーに送信されます。このフォームを使えば、決済を処理するためのHTMLとJavaScriptコードをご自分で実装する手間を省くことができます。

Omise.jsでは既成デザインの決済入力フォームの <form></form> エレメント内にボタンが用意されています。このボタンをクリックすると、既存デザインの決済入力フォームが表示されます。

以前、クレジットカード入力フォームはCard.jsという異なるライブラリに分かれていましたが、最近のアップデートにより、Omise.jsの一部として運用されることになりました。

以下のドキュメントでは、Omise既成デザインの決済入力フォームを購入ページに組み込む手順をご案内しています。

実装

<form></form> エレメント内にOmise既成デザインの決済入力フォームを使用するには、Omise.jsをいくつかのデータ属性とともに挿入して、既成デザインの決済入力フォームを設定する必要があります。

Omise.jsは必ず <form></form> エレメントに内に挿入してください。エレメントの外に設定されると、Omise.jsによってエラーメッセージ Missing form element for omise script tag が表示されます(see how to prevent this error in カスタマイズでこのエラーを防ぐ方法をご参照下さい)。

<html>
<body>
  <form class="checkout-form" name="checkoutForm" method="POST" action="/checkout">
    <script type="text/javascript" src="https://cdn.omise.co/omise.js"
            data-key="YOUR_PUBLIC_KEY"
            data-amount="10000"
            data-button-label="Click to see an example">
    </script>
  </form>
</body>
</html>

Omise.js は、フォームエレメントの下にある 'クリックして例を見る' ボタンと <input type="hidden" name="omiseToken"> エレメントを自動的に表示します。

以下は、Omise.js既成の決済入力フォームで設定できるデータ属性です。

データ属性

名前 タイプ デフォルト 説明
data-key string "" (必須) サインイン時にダッシュボード上で確認することのできるパブリックキー
data-amount number 0 (必須) 支払い金額。単位は各通貨の最小ユニット。
data-currency string THB 決済画面に表示される通貨 (THB, USD, JPY のいずれか。 小文字でも可)
data-image string "" ロゴ画像へのURI。例: http://example.com/logo.png
data-frame-label string Omise ポップアップされる支払い画面のヘッダ部分に表示させたいテキスト
data-frame-description string "" ヘッダーテキストの下部に表示される説明テキスト
data-submit-label string Checkout ポップアップされる支払い画面上の送信ボタンに表示するラベル
data-button-label string Pay with Omise お使いのフォームに埋め込むボタンに表示されるラベル
data-location string no この属性が空欄ではなく何らかの値があった場合、ポップアップには郵便番号と都市の入力フォーム欄が表示されます。(yes もしくは no)
data-locale string en クレジットカードフォームの言語 (en, ja, th)

カスタマイズ

以下のアプローチを利用することで、Omise.js scriptを、 <form></form> エレメントに直接挿入することができない複雑な構造(Ajaxフォームなど)のフォームでもボタンをカスタマイズしたり、特別な設定をご使用のボタンに紐付けることができます。

代替の決済方法

クレジットカードを保有していない、または他の決済方法の利用をご希望するお客様に対しては、設定画面から必要なフィールドを追加し、代替の決済方法(インターネットバンキング、Alipayなど)をデフォルトまたは追加オプションとして有効化することができます。

1. 新しい決済オプションを有効化する場合には、support@omise.coからサポートチームへご連絡ください。

2. バージョン `2017-11-02`以降のAPIと互換性があります。ダッシュボードでご利用中のバージョンをご確認ください。

Alternative payment methods form example

名前 タイプ デフォルト 説明
data-default-payment-method string credit_card 主な決済方法。
credit_card
internet_banking
alipay
bill_payment_tesco_lotus
pay_easy
net_banking
convenience_store
data-other-payment-methods string "" 代替の決済方法。
internet_banking - すべての銀行を表示する
internet_banking(scb, ktb, bay, bbl) - 銀行を特定する
alipay
bill_payment_tesco_lotus
credit_card
pay_easy
net_banking
convenience_store

例 HTML (checkout.html)

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1">
  <title>Example using `omise.js` alternative payment form</title>
</head>
<body>
<form class="checkout-form" name="checkoutForm" method="POST" action="checkout.php">
  <script type="text/javascript" src="https://cdn.omise.co/omise.js"
          data-key="YOUR_PUBLIC_KEY"
          data-frame-label="Merchant site name"
          data-frame-description="Merchant site description"
          data-default-payment-method="convenience_store"
          data-other-payment-methods="internet_banking, bill_payment_tesco_lotus, alipay, credit_card"
          data-amount="10000"
          data-currency="usd"
          data-button-label="Click to see an example">
  </script>
</form>

</body>
</html>

Omise.jsは、フォームエレメント内の”Click to see an example”(クリックして例を見る)ボタンと、<input type = "hidden" name = "omiseSource"> および <input type = "hidden" name = "omiseToken"> のエレメントを自動的にレンダリングします。

このバックエンドによって、POSTリクエストを介したトークンの取得、支払いの処理、ソースオブジェクトの作成を行うことができます。

例 PHP (checkout.php)

<?php
require_once dirname(__FILE__).'/omise-php/lib/Omise.php';
define('OMISE_PUBLIC_KEY', 'pkey_test_52jyu0r8o4307z0zz00');
define('OMISE_SECRET_KEY', 'skey_test_52jyu0r8mim84ylp454');


if ($_POST['omiseSource']) { // for alternative payment methods
  $charge = OmiseSource::create(array(
    'amount'   => 10000,
    'currency' => 'thb',
    'source'     => $_POST["omiseSource"],
    'type' => 'alipay'
  ));
} elseif ($_POST['omiseToken']) { // for credit card
  $charge = OmiseCharge::create(array(
    'amount'   => 10000,
    'currency' => 'thb',
    'card'     => $_POST["omiseToken"]
  ));
}

if ($charge['status'] == 'successful') {
  // Update order status to 'successful'.
} else {
  // Update order status to 'failed'.
}
?>

configure(config)

クレジットカードフォームを動作させるすべてのボタンに対してデフォルト設定します。詳細については、データの属性をご確認下さい。

名前 タイプ デフォルト 説明
config object {} すべてのボタンに対するデフォルト設定。下記の設定に関する詳細をご参照ください。

<script>
  // デフォルト構成を設定します。
  OmiseCard.configure({
    publicKey:        'YOUR_PUBLIC_KEY',
    amount:           10000,
    currency:         'thb',
    image:            'YOUR_LOGO_URL',
    frameLabel:       'Merchant name',
    frameDescription: 'Merchant description',
    submitLabel:      'Pay',
    buttonLabel:      'Pay with Omise',
    location:         'no',
    submitFormTarget: null,
  });
</script>

configureButton(selector, config)

特定のボタンに対してコンフィグを設定します。クレジットカードフォームを動作させるボタンが複数ある場合に適用されます。

名前 タイプ デフォルト 説明
selector string {} 設定の対象となるボタンのセレクタ。
config object {}  ボタンの様式を設定する (デフォルトと同じconfigを使用することができます)。 

<script>
  // デフォルトの構成
  OmiseCard.configure(/* ...config */);


  // ボタンの構成はマージされ、デフォルトの構成を上書きします。
  // このボタンにのみ適用されます。
  OmiseCard.configureButton('#checkout-button', {
    amount:           10000,
    currency:         'thb',
    image:            'YOUR_LOGO_URL',
    frameLabel:       'Merchant name',
    frameDescription: 'Merchant description',
    submitLabel:      'Pay',
    buttonLabel:      'Pay with Omise',
    location:         'no',
    submitFormTarget: null,
  });
</script>

open(config)

設定画面から決済フォームを開いてください。

トークンが正常に作成されましたらonCreateTokenSuccessを利用し、フォームを管理することができます。 例えば、バックエンドにデータを送信する、フォームを送信する前に構成の設定を行う、などです。

このフォームが閉じられると onFormClosedとなります。

Name type default description
config object {} ボタンの様式を設定する (デフォルトと同じconfigを使用することができます)。)
OmiseCard.open({
  frameLabel: 'Esimo',
  frameDescription: 'Invoice #3847',
  amount: 10000,
  onCreateTokenSuccess: (token) => {
    /* Your code, e.g., submit form or send ajax request to server */
  },
  onFormClosed: function() {
    /* Your handler when form was closed */
  },
})

attach()

configureButtonを使用して設定されたすべてのボタンに設定情報を紐付けます。

<script>
  OmiseCard.configure({
    publicKey: 'YOUR_PUBLIC_KEY',
    amount: 10000
  });

  OmiseCard.configureButton('#checkout-button', {
    frameLabel: 'Merchant name',
    submitLabel: 'PAY RIGHT NOW !',
  });

  OmiseCard.attach();
</script>

サンプルコード

お客様のご要望に合わせた、ボタンのカスタマイズ例が多数用意されています。 下記のリンクはGitHubのコードサンプルの保存サイトです。Omise.js既成デザインの決済入力フォームとチェックアウトページを組み込む際の詳細をご確認する際にご参照ください。

リンク: https://github.com/omise/examples/tree/master/omise.js