Omise.js

Omise.js は、ユーザーのブラウザ上で決済情報を収集し、Omise サーバーへ安全に送信するための JavaScript ライブラリです。

ウェブサイトで決済情報を受け付ける場合、Omise.js の使用が必須です。

このドキュメントでは、Omise.js の仕組みを概説するとともに、チェックアウトページへの組み込み方法をご案内します。

要件

• チェックアウトページで HTTPS を有効化 してください。

推奨： サイト全体で HTTPS を有効にすることを強く推奨します。
カード情報をサーバーで収集・保存しないでください。
詳細は 加盟店向けセキュリティベストプラクティス を参照してください。

仕組み

Omise.js は、クレジットカード、デビットカード、およびその他の決済方法の情報をユーザーのブラウザ上で安全に収集します。

収集された情報は指定サーバーへ送信され、一回限り有効な値である トークン または ソース が返されます。この値はサーバー上で安全に使用して請求を作成できます。

サンプル

以下の GitHub リポジトリに、Omise.js を使った実装サンプルが含まれています。

• omise.js-example
• omise-flask-example

事前構築済み決済フォーム

Omise.js を使ってトークンやソースを直接リクエストすることも、事前構築済みの決済フォームを使用することもできます。事前構築済みフォームは、ユーザーデータを安全に収集・検証し、Omise サーバーへ送信します。また、不正利用対策のために追加のブラウザデータも収集します。

事前構築済みフォームの仕組み

インテグレーションは以下の順序で動作します。

1. ユーザー（顧客）がチェックアウトページにアクセスします。
2. ウェブサイトが Omise.js を読み込みます。
3. Omise.js が安全な決済収集のために iframe を作成します。
4. Omise.js が iframe 内に pay.html を読み込みます。
5. PayJS がセキュアな環境で Omise.js を読み込みます。
6. PayJS が自身を読み込み、決済インターフェースを準備します。
7. 決済方法またはフォームがユーザーに表示されます。
8. 顧客が決済情報を送信すると、ペイロードが PayJS に送信されます。
9. PayJS がペイロードを検証します。
10. 検証に失敗した場合、エラーが顧客に表示されます。
11. 検証に成功した場合：
    1. ペイロードが Omise.js に送信されます。
    2. Omise.js が /token または /source API を呼び出します。
    3. Omise サーバーがトークンまたはソースオブジェクトを返します。
    4. Omise.js が API レスポンスを PayJS に送信します。
    5. API がエラーを返した場合、エラーメッセージが顧客に表示されます。
    6. API 呼び出しが成功した場合：
       1. PayJS が結果を Omise.js に送信します。
       2. Omise.js がトークン、ソース、またはその両方をウェブサイトに送信します。
       3. ウェブサイトがデータを処理します。
       4. サーバーがトークンまたはソースを使って決済を開始します。
       5. サーバーが決済結果を受け取ります。
       6. サーバーが決済ステータスを更新します。
       7. ウェブサイトが結果を顧客に表示します。

デフォルトでは、Omise.js は Pay with Omise ボタンをレンダリングします。ボタンをクリックすると決済フォームが開き、ユーザーは決済情報を入力します。Pay [金額] をクリックすると、Omise サーバーから一回限り有効なトークンまたはソースがリクエストされます。

フォームは HTML data 属性 または JavaScript で設定できます。

data 属性を使用する場合

data 属性を使用する場合、カスタム JavaScript は不要です。チェックアウトページに以下の HTML を追加してフォームを設定します。

使用方法

<form id="checkoutForm" method="POST" action="/charge">
  <script type="text/javascript" src="https://cdn.omise.co/omise.js"
          data-key="OMISE_PUBLIC_KEY"
          data-amount="12345"
          data-currency="THB"
          data-default-payment-method="credit_card">
  </script>
</form>

注意事項：

• action パスは、トークンまたはソースを含む POST リクエストを受け付けるバックエンドサーバー上のパスを指定してください。
• <script> 要素は <form> 要素の内側に配置する必要があります。
• data-key — 公開鍵を指定します。
• data-amount — フォームに表示する金額を通貨の最小単位で指定します。
• data-default-payment-method — フォームに表示するデフォルトの決済方法を指定します。
• 追加のパラメーターについてはパラメーターを参照してください。

次のステップ

サーバーの /charge パス（または action に指定したパス）で omiseToken および omiseSource パラメーターを受け取り、処理できるように設定してください。

• クレジットカードまたはデビットカードの情報が送信された場合、omiseToken に生成されたトークン識別子がセットされ、omiseSource は null になります。
• 他の決済方法の情報が送信された場合、omiseSource に生成されたソース識別子がセットされ、omiseToken は null になります。

トークンとソースの処理 を参照してください。

JavaScript を使用する場合

JavaScript を使用して決済フォームの動作を設定することもできます。Omise.js はこのために OmiseCard オブジェクトを提供しています。

使用方法

<form id="checkoutForm" method="POST" action="/charge">
  <input type="hidden" name="omiseToken">
  <input type="hidden" name="omiseSource">
  <button type="submit" id="checkoutButton">チェックアウト</button>
</form>

<script type="text/javascript" src="https://cdn.omise.co/omise.js"></script>

<script>
  OmiseCard.configure({
    publicKey: "OMISE_PUBLIC_KEY"
  });

  const button = document.querySelector("#checkoutButton");
  const form = document.querySelector("#checkoutForm");

  button.addEventListener("click", (event) => {
    event.preventDefault();
    OmiseCard.open({
      amount: 12345,
      currency: "THB",
      defaultPaymentMethod: "credit_card",
      onCreateTokenSuccess: (nonce) => {
        if (nonce.startsWith("tokn_")) {
          form.omiseToken.value = nonce;
        } else {
          form.omiseSource.value = nonce;
        }
        form.submit();
      }
    });
  });
</script>

注意事項：

• action パスは、トークンまたはソースを含む POST リクエストを受け付けるバックエンドサーバー上のパスを指定してください。
• 追加のパラメーターについてはパラメーターを参照してください。

次のステップ

サーバーの /charge パス（または action に指定したパス）で omiseToken および omiseSource パラメーターを受け取り、処理できるように設定してください。

• クレジットカードまたはデビットカードの情報が送信された場合、omiseToken に生成されたトークン識別子がセットされ、omiseSource は null になります。
• 他の決済方法の情報が送信された場合、omiseSource に生成されたソース識別子がセットされ、omiseToken は null になります。

トークンとソースの処理 を参照してください。

OmiseCard メソッド

OmiseCard には、フォームの外観と動作をカスタマイズするための以下のメソッドがあります。

configure

フォームのデフォルト設定を行います。公開鍵はここで設定することを推奨します。configureButton で設定したボタンおよび open で開くフォームは、この設定を継承します。

open を呼び出す前に必ず configure を呼び出してください。

OmiseCard.configure({
  publicKey: 'OMISE_PUBLIC_KEY',
});

configureButton

ボタン固有のフォーム設定を行います。ボタンがフォームの外部にある場合は、設定オブジェクトに submitFormTarget キーを含めてフォームを指定してください。

OmiseCard.configure({
  publicKey: 'OMISE_PUBLIC_KEY'
});

OmiseCard.configureButton('#checkout-button', {
  amount: 3000,
  currency: 'USD',
  buttonLabel: 'Pay 30 USD'
});

OmiseCard.configureButton('#checkout-button-alt', {
  amount: 100000,
  currency: 'THB',
  buttonLabel: 'Pay 1000 THB'
});

attach

configureButton で設定した内容をターゲットボタンに適用します。適用後、設定済みのボタンをクリックすると決済フォームが起動します。

OmiseCard.configureButton('#checkout-button', {
  publicKey: 'OMISE_PUBLIC_KEY',
  amount: 10000,
  frameLabel: 'Merchant Name',
  submitLabel: 'Pay',
});

OmiseCard.attach();

open

決済フォームを開きます。

このメソッドを呼び出す前に必ず configure を呼び出してください。

OmiseCard.open({
  amount: 10000,
  submitFormTarget: '#checkout-form',
  onCreateTokenSuccess: (nonce) => {
    /* トークンまたはソース作成時のハンドラー。フォームの送信や Ajax リクエストの送信に使用します。 */
  },
  onFormClosed: () => {
    /* フォームが閉じられたときのハンドラー。 */
  },
});

パラメーター

以下のパラメーターは特定の決済方法にのみ適用される条件付きパラメーターです。

事前構築済みフォームで対応している決済方法

Omise.js はすべての決済方法に対応していますが、以下の決済方法のみが事前構築済みフォームでサポートされています。利用可能な決済方法は、アカウント設定およびアカウントの登録国によって異なります。

ライブアカウントで追加の決済方法を有効にするには、support@omise.co までお問い合わせください。

* 作成されるソースの type は econtext になります。

トークンとソースの直接リクエスト

この方法はもっとも柔軟性が高く、すべての決済方法に対応しています。ただし、フォームの作成とすべてのイベント処理を自前で実装する必要があります。

カスタムフォームの <input> 要素の識別子として name 属性を使用しないでください。name 属性が存在すると、フォーム送信時にその値がサーバーへの POST ボディに含まれます。カード番号などの機密情報がサーバーを経由するリスクがあります。

代わりに id または data-* 属性を識別子として使用してください。詳細は加盟店向けセキュリティベストプラクティスを参照してください。

カスタムフォームの仕組み

インテグレーションは以下の順序で動作します。

1. ユーザーがウェブサイトにアクセスします。
2. ウェブサイトが Omise.js を読み込みます。
3. ウェブサイトがカスタムカードフォームをユーザーに表示します。
4. ユーザーがカード情報を入力します。
5. ウェブサイトがペイロードを検証します。
6. 検証に失敗した場合、ウェブサイトはエラーをユーザーに表示します。
7. 検証に成功した場合：
   1. ユーザーが「支払う」ボタンをクリックします。
   2. ウェブサイトがトークン作成のためにカード情報を Omise.js に送信します。
   3. Omise.js が /token または /source API を呼び出します。
   4. Omise サーバーがトークンまたはソースオブジェクトを返します。
   5. Omise.js が API レスポンスをウェブサイトに返します。
   6. API がエラーを返した場合、ウェブサイトはエラーをユーザーに表示します。
   7. API 呼び出しが成功した場合、ウェブサイトはレスポンスをバックエンドに送信します。

使用方法

以下の <script> 要素を追加して Omise.js を読み込みます。

<script type="text/javascript" src="https://cdn.omise.co/omise.js"></script>

読み込みが完了すると、Omise オブジェクトが環境内で使用できるようになります。

Omise メソッド

Omise オブジェクトには、一回限り有効なトークンまたはソースを作成するための以下のメソッドがあります。

setPublicKey

公開鍵を使用してリクエストを認証します。

Omise.setPublicKey("OMISE_PUBLIC_KEY");

createToken

Omise サーバーから一回限り有効なトークンを作成します。トークンは、請求の作成や顧客オブジェクトへのカード登録に使用できます。

const tokenParameters = {
  "city": "New York",
  "country": "US",
  "expiration_month": 2,
  "expiration_year": 2022,
  "name": "Somchai Prasert",
  "number": "4242424242424242",
  "phone_number": "0123456789",
  "postal_code": 10320,
  "security_code": 123,
  "state": "NY",
  "street1": "476 Fifth Avenue"
};

Omise.createToken("card", tokenParameters, function(statusCode, response) {
  if (statusCode === 200) {
    // response["id"] にトークン識別子が含まれます
    console.log(response["id"]);
  } else {
    // エラー処理 — response["message"] にエラーの説明が含まれます
    console.error(response["message"]);
  }
});

createSource

Omise サーバーから一回限り有効なソースを作成します。ソースは請求の作成に使用できます。利用可能なソースタイプと必須パラメーターについては、Source API を参照してください。

const sourceParameters = {
  "amount": 12345,
  "currency": "THB",
  "phone_number": "0123456789"
};

Omise.createSource("truemoney_jumpapp", sourceParameters, function(statusCode, response) {
  if (statusCode === 200) {
    // response["id"] にソース識別子が含まれます
    console.log(response["id"]);
  } else {
    // エラー処理 — response["message"] にエラーの説明が含まれます
    console.error(response["message"]);
  }
});

トークンとソースの処理

Omise.js がフロントエンドにトークンまたはソースを返した後、サーバーはそれを使用して請求を作成する必要があります。トークンとソースは一回限り有効であり、使用されない場合は有効期限が切れます。

• トークンについては、カード請求を参照してください。詳細とコード例については、Charge API を参照してください。
• ソースについては、決済方法カテゴリー下の API ドキュメント内の各ガイドを参照してください。

重要： トークンまたはソースは絶対に複数回使用しないでください。各値は、請求の成否に関わらず、一度の請求試行後に無効化されます。

エラー処理

コールバックが 200 以外のステータスコードを受け取った場合、レスポンスオブジェクトには失敗の詳細が含まれます。

Omise.js が返す主なエラーコード：

エラーコードの完全なリストについては、API エラーリファレンスを参照してください。

CDN

以下の URL から Omise.js を読み込んでください。

https://cdn.omise.co/omise.js

よくある質問

全般

Omise.js とは何ですか？なぜ必要なのですか？

Omise.js は、ユーザーのブラウザから Omise サーバーへ決済情報を安全に収集・送信する JavaScript ライブラリです。ウェブベースのすべての決済インテグレーションで必須です。機密性の高いカードデータがサーバーに渡らないため、PCI DSS コンプライアンスの対象範囲を大幅に削減できます。

Omise.js はカードデータをサーバーに保存しますか？

いいえ。Omise.js はユーザーのブラウザから直接 Omise サーバーへ決済情報を送信し、サーバーにはトークンまたはソース識別子のみを返します。サーバーが生のカードデータを受け取ったり保存したりすることはありません。

事前構築済みフォームとカスタムフォーム、どちらを使うべきですか？

迅速かつ低メンテナンスなインテグレーションを希望する場合は事前構築済みフォームを使用してください。UI を完全に制御したい場合や、事前構築済みフォームで対応していない決済方法を利用する必要がある場合はカスタムフォームを使用してください。

Omise.js はシングルページアプリケーション（SPA）に対応していますか？

はい。JavaScript（OmiseCard）メソッドを使用し、初期化時に OmiseCard.configure() を一度だけ呼び出してください。ユーザーが支払いの準備ができたタイミングでプログラムから OmiseCard.open() を呼び出してください。ルート変更ごとにスクリプトタグを再埋め込みしないよう注意してください。

React、Vue、Angular などのフレームワークで Omise.js を使用できますか？

はい。HTML の <script> タグ（またはコンポーネントのマウント時に動的に）Omise.js を読み込み、OmiseCard または Omise グローバルオブジェクトを操作してください。公式のフレームワークラッパーは現在提供されていませんが、どちらの API もイベント駆動型のコンポーネントアーキテクチャと問題なく連携できます。

セキュリティ

チェックアウトページで HTTPS が必要な理由は何ですか？

HTTPS により、ユーザーのブラウザとページ間の通信が暗号化されます。HTTPS がない場合、攻撃者が Omise.js の読み込み前にページを傍受または改ざんし、安全なフォームを悪意のあるものに置き換える可能性があります。Omise.js は HTTP で提供されるページでは動作しません。

カスタムフォームの入力要素に name 属性を使用してはいけないのはなぜですか？

フォームが送信されると、name 属性を持つ <input> 要素の値がサーバーへの POST ボディに含まれます。カード番号や CVV コードなどの機密フィールドに name 属性があると、生のカードデータがサーバーを経由することになり、深刻なセキュリティリスクおよび PCI DSS 違反となります。代わりに id または data-* 属性を識別子として使用し、その値がブラウザ内で Omise.js のみに読み取られるようにしてください。

事前構築済みフォームの iframe は何のために使用されますか？

事前構築済みフォームは、Omise 独自のドメインから提供された iframe 内に読み込まれます。これにより、決済フォームがあなたのページとは別のブラウジングコンテキストで動作します。iframe 内に入力されたカード情報には JavaScript からアクセスできないため、機密データの意図しない流出や不正アクセスを防ぐことができます。

公開鍵はどこで確認できますか？

公開鍵は Omise ダッシュボード の 設定 → 鍵 から確認できます。開発時はテスト用公開鍵を使用し、本番環境ではライブ用公開鍵を使用してください。クライアントサイドのコードに秘密鍵を使用しないでください。

トークンとソース

トークンとソースの違いは何ですか？

トークン はクレジットカードまたはデビットカードを表し、顧客がカード情報を入力した際に作成されます。ソース は非カード決済方法（PromptPay、GrabPay、電子ウォレットなど）を表し、決済完了に必要なリダイレクトや QR 情報を含みます。どちらも一回限り有効な識別子であり、サーバーから Charge API に渡して使用します。

トークンまたはソースはどのくらいの期間有効ですか？

トークンは一回限り有効であり、使用されない場合は短時間（通常数分以内）で有効期限が切れます。ソースは基盤となる決済方法のルールに従って有効期限が設定されます。受け取ったトークンまたはソースはすぐに使用し、キャッシュや再利用はしないでください。

サーバーへの POST で omiseToken と omiseSource の両方が null だった場合はどうなりますか？

これは、トークンまたはソースの作成が成功しないまま決済フォームが送信されたことを示しています。たとえば、ユーザーが決済を完了する前にフォームを閉じた場合などが該当します。サーバーはこのケースを適切に処理し、適切なメッセージとともにユーザーをチェックアウトページに戻すなどの対応をしてください。

将来の請求に備えて、カードトークンを顧客に紐付けることはできますか？

はい。トークン識別子を Customers API に渡すことで、カードを顧客オブジェクトに登録できます。その後、顧客にカード情報を再入力させることなく、後から請求を行うことができます。

決済方法

アカウントで使用可能な決済方法を確認するにはどうすればよいですか？

利用可能な決済方法は、アカウントの登録国と Omise が有効化している方法によって異なります。Omise ダッシュボードにログインして、有効な決済方法を確認してください。追加の決済方法を希望する場合は、support@omise.co までお問い合わせください。

事前構築済みフォームで複数の決済方法を表示できますか？

はい。data-other-payment-methods 属性（JavaScript では otherPaymentMethods パラメーター）を使用して、デフォルトに加えて追加の決済方法識別子をカンマ区切りで指定してください。例：

data-other-payment-methods="promptpay,truemoney_jumpapp,grabpay"

事前構築済みフォームは Google Pay と Apple Pay に対応していますか？

はい。ただし、本番トラフィックでは追加の設定が必要です。

• Google Pay — data-googlepay-merchant-id に Google Pay のマーチャント ID を設定してください。
• Apple Pay — data-applepay-merchant-id に Apple Pay のマーチャント ID を、data-applepay-validation-url にサーバー検証エンドポイントを設定してください。

テストモードではこれらのパラメーターなしで動作します。

トラブルシューティング

ボタンをクリックしても決済フォームが表示されません。

以下の点を確認してください。

• OmiseCard.open() を呼び出す前に、有効な publicKey を指定して OmiseCard.configure() が呼び出されていること。
• OmiseCard の呼び出しを行う前に Omise.js スクリプトが完全に読み込まれていること。スクリプトのロジックは <script src="https://cdn.omise.co/omise.js"> タグの後に配置するか、DOMContentLoaded イベントを待ってから実行してください。
• ページが HTTPS で提供されていること。Omise.js は HTTP ページでは読み込まれません。
• ブラウザコンソールにエラーが表示されていないこと。ブラウザの開発者ツールを開き、コンソールおよびネットワークタブでブロックされたリクエストや JavaScript エラーを確認してください。

authentication_failure エラーが発生します。

Omise.js に渡された公開鍵が存在しない、不正な形式、または期待される環境（テストと本番）と一致していないことを意味します。以下の点を確認してください。

• 鍵が pkey_ で始まっていること（公開鍵は常にこのプレフィックスを使用します）。
• 環境に合った正しい鍵を使用していること（テストモードにはテスト鍵、本番環境には本番鍵）。
• 鍵のコピー時に余分な空白や文字が混入していないこと。

サーバーがトークンまたはソースを受け取れていません。

以下の点を確認してください。

• <form> の action 属性が正しいサーバーエンドポイントを指していること。
• data 属性方式の場合、<script> タグが <form> 要素の内側にあること。
• JavaScript 方式の場合、form.submit() を呼び出す前に form.omiseToken.value または form.omiseSource.value がセットされていること。
• サーバーが omiseToken および omiseSource を（クエリパラメーターではなく）POST パラメーターとして読み取っていること。

カスタムフォームが誤ってカードデータをサーバーに送信しています。

カード関連の <input> 要素に name 属性が設定されている場合に発生します。カード入力フィールドから name 属性をすべて削除し、代わりに id または data-* 属性を使用してください。詳細はトークンとソースの直接リクエストを参照してください。

実際の決済を処理せずにインテグレーションをテストするにはどうすればよいですか？

Omise ダッシュボードのテスト用公開鍵を使用してください。テストモードでは、Omise のテストカード番号を使用して、実際の請求なしに決済の成功・失敗シナリオをシミュレートできます。