INTRODUCTIONセクションは、トークン決済v2を初めて扱うシステム担当者の方、開発者の方に向けたドキュメントです。 トークン決済v2の概要、トークン決済v2でできること、利用イメージ、トークン決済v1との比較について説明します。
トークン発行後の決済に関する仕様は、各接続方式(プロトコルタイプ/モジュールタイプ/OpenAPIタイプ)のリファレンスを参照ください。
本リファレンスのサンプルコードについて、実装にあたっては加盟店様にて十分に検証を行ってください。

クレジットカードでの決済を取り扱う加盟店様は、 PCI DSSに準拠するか、カード情報の「非保持化」が必要です。 カード情報をトークン化すると、加盟店様はお客様のカード情報を通過、処理、保存することなく決済ができ、「非保持化」を実現できます。 また、Google Payで支払いをする際に必要なPayment tokenを簡単に取得できる機能も提供します。

当サービスはお客様のカード情報を直接受け取り、解読不能な文字列「MPクレカトークン」に置き換えます。 加盟店様はMPクレカトークンを受け取り、加盟店様サーバー上で安全に処理ができます。 カード情報を保管し、次回の支払い時に利用したい場合は、当サービスの「カード登録」機能をお使いください。

MPクレカトークンが使える決済手段

MPクレカトークンは、当サービスの以下決済手段で利用可能です。詳細については後続のAPI処理を参照ください。 本リファレンスではMPクレカトークンの仕様のみ扱います。

トークン決済v2がどのようにカード情報を扱うかを解説します。
お客様のブラウザまたはネイティブアプリから当サービスへ直接カード情報を送信することで加盟店様サーバーはカード情報非保持を実現できます。 MPクレカトークン発行後、決済処理やカード情報の登録を行います。

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor お客様
participant device as ブラウザ<br>ネイティブアプリ 
participant 加盟店様サイト
participant 当サービス
お客様->>device: カード情報入力
rect rgba(170, 202, 222, 0.2) 
Note over device: カード情報のトークン化
device->>当サービス: 当サービスへカード情報送信
当サービス-->>device: トークン化して返却
device->>加盟店様サイト: MPクレカトークンを送信
end
加盟店様サイト->>当サービス: MPクレカトークンを利用したAPI実行
Note over 当サービス: MPクレカトークンを復号化し処理

トークン決済v1(/ext/js/token.js もしくは /ext/api/credit/getToken API)は引き続き利用できますが、2027年4月以降にサポートを終了する予定です。 ただし、新たな脆弱性の登場やPCI DSSの要件が変更になる等の理由によりサポート終了時期が早まる可能性がありますので、より便利になった「トークン決済v2」への移行を推奨します。
どちらの方式で取得したトークンでも、後続のAPI処理のパラメーターに設定できます。

トークン決済v1とトークン決済v2の比較

移行時の注意事項

トークン決済v2では安全性を高めるために以下の仕様変更がされています。トークン決済v1から移行する際は加盟店様側も合わせて対応をお願いします。

• 返却するマスク済みカード番号
  トークン決済v1では、管理画面にてマスクレベルを変更できましたが、トークン決済v2で返却する値には適用されません。
  トークン決済v2で返却するカード番号のマスクレベルは上6桁、下4桁の表示で固定です。

• MPクレカトークン利用範囲
  トークン決済v2で発行したトークンは、発行時の認証情報のショップIDが属するサイトID内のショップのみが後続のAPI処理で利用できます。 発行したトークンの有効期間はどちらで発行しても変わりません。
  以下の図の例では、ショップAの認証情報で発行したトークンはショップA、ショップB、ショップCでは利用できますが、
  異なるサイトに属するショップD、ショップEでは利用できません。

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8',
    'lineColor': '#6A7FAB'
  }
 }
}%%

graph TD
    A(サイト1)---B[ショップA]
    A---C[ショップB]
    A---D[ショップC]

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8',
    'lineColor': '#6A7FAB'
  }
 }
}%%
graph TD
    A(サイト2)---B[ショップD]
    A---C[ショップE]

• JavaScript版の認証情報
  トークン決済v1のJavaScript版では個別の認証情報を事前に登録する必要はありませんが、トークン決済v2では必要です。
  ただし、MpToken.jsの下位互換メソッドであるinit、getTokenを利用する場合はこれまで通りです。

GET STARTEDセクションは、開発者の方に向けた技術仕様に関するドキュメントです。 実際にトークン決済v2の組み込み開発をするにあたりお読みください。

トークン決済v2を利用するために、以下のライブラリを提供していますので、加盟店様の環境や用途に応じて選択してください。 それぞれの特徴については以下の通りです。

*1：トークン決済v1のJavaScriptメソッドinit、getTokenをサポートします。

こちらのテスト環境申し込みページからテストアカウントの即時発行が可能です。 登録が完了すると申し込み時のメールアドレスにショップ管理画面のログイン情報が届きます。 ショップ管理画面にログインできることを確認し、トークン決済v2を利用するための認証情報を登録します。

トークン決済v2の認証情報は以下の2つのデータを指します。

トークン決済v2の利用にあたり、事前にショップ管理画面にて認証情報を登録する必要があります。 ショップ管理画面の「都度決済」->「クレジットカード」->「設定」ページを開き、「MPクレカトークン認証情報」メニューに進み、「登録」ボタンを押して認証情報を発行します。 登録された「公開鍵」と「APIキー」は、組み込み時に設定します。

テスト環境と本番環境を用意しています。 各環境はFQDN(絶対ドメイン名)で区別され、認証情報やトークンのデータは共用されません。 テスト環境での確認を終えて商用利用を開始する際は、以下の対応をお願いします。

• 本番アカウントの認証情報を管理画面で登録して設定値を更新
• MpToken.jsを直接読み込んでいる場合は、srcに指定するURLを本番用のURLに更新
• npmインストールしたパッケージは、初期化時のproductionModeをtrueに設定

発行されたトークンは有効期限を過ぎるか、後続のAPI処理で利用すると無効になります。 ただし、OpenAPIタイプのカード詳細情報取得API(getCardDetails)で利用しても無効になりません。 有効期限は発行した時点から30分ですが、予告なしに変更される場合があります。 実際の値はトークン発行時のレスポンスパラメーターの「MPクレカトークン有効期限」で確認できます。

加盟店様のフロントエンドで受け取ったMPクレカトークンは、加盟店様サーバーサイドでの当サービスAPI呼び出し時に設定します。 対応するAPIは以下の通りです。 詳細については各リファレンスを参照ください。 マルペイDocsの利用方法はこちらのFAQページを参照してください。

*1：APIでMPクレカトークンを利用してもトークンは無効になりません。

Elements機能とは、弊社が提供するカード情報の入力フォームを利用してトークン化する機能です。
トークン決済v1では、加盟店様が設置した入力フォームを経由してトークン化していました。 どちらも加盟店様のカード情報非保持を実現しますが、Elements機能はiframeを通じて弊社サーバー側でカード情報を受け付けます。
Elements機能に対応している入力フォームは以下の3つです。

• カード番号
• 有効期限
• セキュリティコード

これらのフォームは弊社サーバー上で動作するため、加盟店様が用意するスタイル(CSSファイル、styleタグ)は適用できません。 スタイルを変更する場合は、フォーム生成時のオプションで設定します。

Elements機能に対応している組み込み方法は以下の通りです。

• ESモジュール MpToken.js
• React MpToken.js
• Vue MpToken.js

詳細な組み込み方法についてはElementsによるカード情報入力フォームの生成を参照ください。

テスト環境で利用可能なカード番号は、マルペイDocsのテストカード一覧ページを参照してください。
マルペイDocsのログイン情報はこちらのFAQページを参照してください。|

トークン決済v2を利用するための手段として、JavaScriptライブラリMpToken.jsを提供しています。
以下のいずれかの方法でJavaScriptを読み込んでください。

パッケージマネージャーを利用してインストールする

npmパッケージを利用してMpToken.jsをインストールします。

ESモジュール MpToken.jsを利用する場合

インストール

npm install --save @mul-pay/mptoken-js

呼び出す

import { loadMulpay } from '@mul-pay/mptoken-js'

Vue MpToken.jsを利用する場合

インストール

npm install --save @mul-pay/mptoken-vue-js

呼び出す

import VueMultiPayment  from '@mul-pay/mptoken-vue-js';

React MpToken.jsを利用する場合

インストール

npm install --save @mul-pay/mptoken-react-js

呼び出す

import { Elements } from "@mul-pay/mptoken-react-js";
import { LoadMulpay, MultiPayment } from "@mul-pay/mptoken-js";

scriptへ追加

HTMLのhead要素にスクリプトを追加してMpToken.jsを読み込みます。
スクリプトとして追加することでMultiPaymentオブジェクトが使用できます。
MpToken.jsは常に当サービスで提供するURLから読み込んでください。

テスト環境と本番環境を用意しています。
テスト環境での確認を終えて商用利用を開始する際は、srcに指定するURLを切り替えてください。

テスト環境

<script src="https://stg.static.mul-pay.jp/payment/js/mp-token.js"></script>

本番環境

<script src="https://static.mul-pay.jp/payment/js/mp-token.js"></script>

MpToken.jsを利用することでJavaScriptで簡単にクレジットカード情報をトークン化できます。
Multipayment.init()で初期化を行い、MPクレカトークンを取得したいタイミングでMultipayment.getToken()を行ってください。

MpToken.jsを利用しカード情報をトークン化して都度決済を行うシーケンス例

%%{
init: {
'theme': 'base',
'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
}
}
}%%
sequenceDiagram
actor お客様
participant お客様ブラウザ
participant 加盟店様サイト
participant 当サービス
お客様ブラウザ->>お客様ブラウザ: Multipayment.init()
お客様->>お客様ブラウザ: カード情報入力
お客様ブラウザ->>当サービス: Multipayment.getToken()
当サービス-->>お客様ブラウザ: 
お客様ブラウザ->>加盟店様サイト: MPクレカトークンを送信
加盟店様サイト->>当サービス: (OpenAPIタイプ)クレカ払い 都度払い<br>(プロトコルタイプ)決済実行

サンプルコード

Multipayment.init('tshop00000001');	 // ショップID
Multipayment.getToken(
{ 
    cardno: '4111111111111111',   // カード番号
    expire: '201501',             // カード有効期限
    securitycode: '111',          // セキュリティコード
    holdername: 'SOME HOLDER',    // カード名義人
    tokennumber: '5'              // MPクレカトークン発行数
}, someCallbackFunction         // MPクレカトークン取得後に実行するコールバック関数
);

// MPクレカトークン取得後に呼び出すコールバック関数を定義する
function someCallbackFunction ( result ){
// 処理結果コードが'000'以外の時はエラーのためダイアログを表示する
if( result.resultCode != '000' ){
    window.alert('購入処理中にエラーが発生しました')
} else {
// 予め購入フォームに用意したtokenフィールドに値を設定
document.getElementById('token').value = result.tokenObject.token
// フォームをsubmitして購入処理を進める
document.getElementById('purchaseform').submit()
}
}

Multipayment.init(apiKey)

Multipaymentオブジェクトを初期化するメソッドです。
Multipaymentオブジェクトの機能を利用するために必要です。
※npmパッケージを利用する場合は、loadMulpay()を呼び出してください。

Multipayment.getToken(card, callback)

MPクレカトークンを取得するメソッドです。
MPクレカトークン取得後にMPクレカトークンを含むresultオブジェクトを引数callbackに渡してコールバック関数を呼び出します。 resultオブジェクトを参照することでMPクレカトークンを利用できます。

card オブジェクト

Multipayment.getToken(card, callback)の第一引数cardオブジェクトにはカード情報を指定します。
以下の項目を設定してください。

result オブジェクト

Multipayment.getToken(card, callback)でコールバック関数を呼び出す際に、
引数としてresult オブジェクトを渡します。result オブジェクトのデータ構造は以下の通りです。

resultオブジェクトサンプル

{
"resultCode": "000",
"tokenObject": {
    "token": "a33c8bec609ffc75726249d8d82286d529bd1deb973119cf497eeb54610ab9d2",
    "toBeExpiredAt": "2016-09-26-17-56-38",
    "maskedCardNo": "411111******1111",
    "isSecurityCodeSet": true
}
}

Multipaymentオブジェクトを初期化するメソッドです。
Multipaymentオブジェクトの機能を利用するために必要です。
※npmパッケージを利用する場合は、loadMulpay()を呼び出してください。

MPクレカトークンを取得するメソッドです。
MPクレカトークン取得後にMPクレカトークンを含むresultオブジェクトを引数callbackに渡してコールバック関数を呼び出します。 resultオブジェクトを参照することでMPクレカトークンを利用できます。

card オブジェクト

Multipayment.getToken(card, callback)の第一引数cardオブジェクトにはカード情報を指定します。
以下の項目を設定してください。

result オブジェクト

Multipayment.getToken(card, callback)でコールバック関数を呼び出す際に、
引数としてresult オブジェクトを渡します。result オブジェクトのデータ構造は以下の通りです。

resultオブジェクトサンプル

{
"resultCode": "000",
"tokenObject": {
    "token": "a33c8bec609ffc75726249d8d82286d529bd1deb973119cf497eeb54610ab9d2",
    "toBeExpiredAt": "2016-09-26-17-56-38",
    "maskedCardNo": "411111******1111",
    "isSecurityCodeSet": true
}
}

Elementsを利用することでカード情報入力フォームを動的に生成できます。
iframeで生成されるため、カード情報の入力をより安全に行えます。
以下のような手順を行うことで、MPクレカトークンを取得できます。

1. Multipayment.createElements()で初期化
2. elements.create()でカード情報入力フォームを生成し、入力フォームにしたいdiv要素にmountする
3. mulpay.getTokenThroughIframe()でMPクレカトークンを取得

   Elementsを利用しカード情報をトークン化して都度決済を行うシーケンス例

%%{
init: {
'theme': 'base',
'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
}
}
}%%
sequenceDiagram
actor お客様
participant お客様ブラウザ
participant 加盟店様サイト
participant 当サービス
お客様ブラウザ->>お客様ブラウザ:  mulpay.createElements()で初期化
お客様ブラウザ->>お客様ブラウザ:  elements.create()でカード情報入力フォームを生成
お客様ブラウザ->>お客様ブラウザ:  elements.create()の返り値を入力フォームにしたいdiv要素にmountする
お客様->>お客様ブラウザ: カード情報入力
お客様ブラウザ->>当サービス: mulpay.getTokenThroughIframe()でMPクレカトークンを発行
当サービス-->>お客様ブラウザ: 
お客様ブラウザ->>加盟店様サイト: MPクレカトークンを送信
加盟店様サイト->>当サービス: (OpenAPIタイプ)クレカ払い 都度払い<br>(プロトコルタイプ)決済実行

<!doctype html>
<html>
<head>
    <title>MPクレカトークン生成フォーム(iframe)</title>
    <script src="./useMpToken.js"></script>
</head>
<body>
    <h1>MPクレカトークン生成フォーム(iframe)</h1>
<form action="#" method="post">
<label for="cardNumber">カード番号:</label>
<div id="any-wrapper-id1"></div>
<br /><br />

<label for="expiry">有効期限:</label>
<div id="any-wrapper-id2"></div>
<br /><br />

<label for="cvc">セキュリティコード:</label>
<div id="any-wrapper-id3"></div>
<br /><br />

<label for="name">名義人:</label>
<input type="text" id="name-input-id" />
<br />
<br />

<input type="button" id="submit-button" value="決済する" />
</form>
<div id="result"></div>
</body>
</html>

import { loadMulpay } from "@mul-pay/mptoken-js";

window.addEventListener("load", async () => {
    const apiKey = "API_KEY";
    const mulpay = await loadMulpay(apiKey); // apiKeyを指定してMultipaymentオブジェクトを初期化する

    // カード情報入力フォーム(カード番号)のスタイルを設定する
    const cardInputStyle = {
    base: {
        fontFamily: "'Noto Sans Japanese', sans-serif",
        "::placeholder": {
        color: "rgba(0, 0, 0, 0.54)",
    },
        caretColor: "#198FCC",
        lineHeight: "28px",
    },
    invalid: {
        color: "#9e2146",
    },
    };
    // カード情報入力フォーム(有効期限)のスタイルを設定する
    const expiryInputStyle = {
    base: {
        fontFamily: "'Noto Sans Japanese', sans-serif",
        "::placeholder": {
        color: "rgba(0, 0, 0, 0.54)",
        },
        caretColor: "#198FCC",
    lineHeight: "28px",
    },
    invalid: {
        color: "#9e2146",
    },
    };
    // カード情報入力フォーム(セキュリティコード)のスタイルを設定する
    const cvcInputStyle = {
    base: {
        fontFamily: "'Noto Sans Japanese', sans-serif",
        "::placeholder": {
        color: "rgba(0, 0, 0, 0.54)",
        },
        caretColor: "#198FCC",
        lineHeight: "28px",
    },
    invalid: {
        color: "#9e2146",
    },
    };

    // カード情報入力フォームのタイプを設定する
    const cardElementType = {
    type: "cardNumber",
    options: { style: cardInputStyle, placeholder: "hogehoge" },
    };
    const expiryInputType = {
    type: "cardExpiry",
    options: { style: expiryInputStyle },
    };
    const cvcInputType = {
    type: "cardCvc",
    options: { style: cvcInputStyle },
    };

    // カード情報入力フォームのラッパー要素を取得する
    const elements = mulpay.createElements();
    
    // カード情報入力フォームを作成する
    const cardNumberInputElement = elements.create('cardNumber', { style: cardInputStyle, placeholder: 'hogehoge'} );
    const expiryInputElement = elements.create('cardExpiry',{ style: expiryInputStyle });
    const cvcInputElement = elements.create('cardCvc', { style: cvcInputStyle });

    // カード情報入力フォームのラッパー要素を取得する
    const cardNumberWrapperElement = document.getElementById('any-wrapper-id1');
    const cardExpiryWrapperElement = document.getElementById('any-wrapper-id2');
    const cardCvcWrapperElement = document.getElementById('any-wrapper-id3');

    // カード情報入力フォームをラッパー要素にマウントする
    cardNumberInputElement.mount(cardNumberWrapperElement);
    expiryInputElement.mount(cardExpiryWrapperElement);
    cvcInputElement.mount(cardCvcWrapperElement);
    
    // カード情報入力フォームのラッパー要素を配列に格納する
    const mulPayFormElements = [
    cardNumberInputElement,
    expiryInputElement,
    cvcInputElement,
    ];
    // 名義人入力フォームを取得する
    const nameInputElement = document.getElementById("name-input-id");

    const btn = document.getElementById("submit-button");
    // 決済ボタンをクリックした時の処理を定義する
    btn.addEventListener("click", (e) => {
    // buttonを非活性にする
    btn.setAttribute("disabled", "true");

    const options = {
        tokenNumber: 2,
    };
    
    // mulpayオブジェクトのgetTokenThroughIframeメソッドを呼び出します。
    // このメソッドは、第一引数にフォーム要素、第二引数に名前の入力要素の値、第三引数にオプションを取ります。
    mulpay
        .getTokenThroughIframe(
        mulPayFormElements[0],
        nameInputElement.value,
        options
    )
        // getTokenThroughIframeメソッドはPromiseを返すため、thenメソッドを使用して非同期処理の結果を取得します。
        .then((response) => {
        const resultElement = document.getElementById("result");
        resultElement.innerHTML = JSON.stringify(response);
        btn.setAttribute("disabled", "false");
        cleanup();
    });
    });

    const cleanup = () => {
    mulPayFormElements.forEach(function (element) {
        // カード情報入力フォームをアンマウントする
        element.clear();
    });
    };
});

loadMulpayはnpmパッケージを利用してMpToken.jsを読み込む際に使用する関数です。

Example

import { loadMulpay } from "@mul-pay/mptoken-js";

const apiKey = "API_KEY"
const publicKey = "PUB_KEY"
const merchantIds = {
googlePayMerchantId: "01234567890123456789"
}
const mulpay = await loadMulpay(apiKey, publicKey, ids, true, false);

Multipayment.createElements()は、Elementsオブジェクトを返すメソッドです。
このメソッドを使用することで、Elementsオブジェクトを利用できます。

指定されたtypeのElementsオブジェクトを返すメソッドです。
生成されたElementsオブジェクトは、指定されたdiv要素にmountすることで、カード情報入力フォームを生成します。

Example

const cardInputStyle = {
base: {
    fontFamily: "'Noto Sans Japanese', sans-serif",
    caretColor: "#198FCC",
    lineHeight: "28px",
    "::placeholder": {
    color: "rgba(0, 0, 0, 0.54)",
    },
},
invalid: {
    color: "#9e2146",
},
};

const cardNumberInputElement = elements.create('cardNumber', { style: cardInputStyle, placeholder: 'hogehoge'} );
const cardNumberWrapperElement = document.getElementById('any-wrapper-id1');
cardNumberInputElement.mount(cardNumberWrapperElement);

optionsの指定方法について

optionsはCSSプロパティのマッピングを指定するオブジェクトで、styleプロパティにはCSSプロパティに加えて、Elementsでサポートする状態や疑似クラス・疑似要素を指定できます。
状態には、base, complete, empty, invalid, focusの状態を指定できます。
疑似クラス・疑似要素は:hover, :focus, ::placeholder, ::selection, :-webkit-autofill, :disabled, ::-ms-clearを指定できます。
上記のExampleを参考にしてください。

指定可能なCSSプロパティ

elments.createで生成したフォーム要素を指定して、MPクレカトークンを取得するメソッドです。
Multipayment.getToken(card, callback)とは異なり、elements.createで生成したフォームに入力された情報を利用してMPクレカトークンを取得します。

MpToken.jsでは Google Payトークンを取得できる機能を提供します。 カード情報は当サービスではなくGoogle Payによってトークン化されます。
作成したトークンを当サービスに送信することで決済ができます。

Google Payのトークンを取得して都度決済を行うシーケンス例

%%{
init: {
'theme': 'base',
'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
}
}
}%%
sequenceDiagram
actor お客様
participant お客様ブラウザ
participant 加盟店様サイト
participant 当サービス
お客様ブラウザ->>お客様ブラウザ: mulpay.createPaymentRequest(Object)
お客様ブラウザ->>お客様ブラウザ: mulpay.checkAvailability()
お客様->>お客様ブラウザ: Google Payボタンをクリックして<br>支払いシートで支払いを行う
お客様ブラウザ->>お客様ブラウザ: mulpay.fetchEncryptedTokenObject(mulpay.createPaymentRequestの返り値)
お客様ブラウザ->>加盟店様サイト: Google Payのトークンを送信
加盟店様サイト->>当サービス: (OpenAPIタイプ)クレカ払い 都度払い<br>(プロトコルタイプ)決済実行

<!doctype html>
<html>
<head>
    <title>Google Pay の利用サンプル</title>
    <script async src="https://pay.google.com/gp/p/js/pay.js"></script>
    <script type="module" src='./useMpToken.js'></script>
</head>
<body>
    <h1>Google Pay</h1>
    <!-- Google Payボタンを表示するためのラッパー要素 -->
    <div id="google-pay-button-wrapper" style="display: none">
    <!-- Google Payボタン -->
    <button id="google-pay-btn">Let's get token</button>
    </div>
    <!-- トークン取得結果を表示するための要素 -->
    <div id="result"></div>
</body>
</html>

import { loadMulpay } from "@mul-pay/mptoken-js"; // Multipaymentオブジェクトを初期化するためのメソッドをインポートする

// Google Payのトークンを取得するための引数を設定する
const argsForGoogle = {
    merchantName: "merchant name", // 購入者を設定する
    currency: "JPY", // 通貨を設定する
    country: "JP", // 国を設定する
    total: "1000", // 金額を設定する
};

window.addEventListener("load", async () => {
    const apiKey = "ec9946c42bbbef17658f0bea238f8dacac8d91ab15071fdf4d7b8cce70ce1ed4"; // apiKeyを設定する
    const publicKey = "pub_key"; // 公開鍵を設定する
    const ids = {
    googlePayMerchantId: "google_merchant_id", 
    }; // Google PayのmerchantIdを設定する

    const mulpay = await loadMulpay(apiKey, publicKey, ids); // Multipaymentオブジェクトを初期化する
    // Google Payの支払い情報を作成する
    const paymentRequestForGoogle = mulpay.createPaymentRequest(argsForGoogle);
    // Google Payが利用可能かどうかをチェックする
    const { googlePayAvailable } = await mulpay.checkAvailability();
    // Google Payが利用可能な場合、Google Payボタンを表示する
    const togglePayButton = (googlePayAvailable) => {
    if (googlePayAvailable) {
        document.getElementById("google-pay-button-wrapper").style.display =
        "block";
    }
    };
    togglePayButton(googlePayAvailable);
    
    /**
    * Google Payボタンをクリックした時の処理
    * Google Payのトークンを取得する
    */
    const onClickForGoogle = async (e) => {
    const encryptedTokenObject = await mulpay.fetchEncryptedTokenObject(
        paymentRequestForGoogle
    ); // Google Payのトークンを取得する
    };
    const btn = document.getElementById("google-pay-btn"); // Google Payボタンを取得する
    btn.addEventListener("click", onClickForGoogle); // Google Payボタンをクリックした時の処理を登録する
});

mulpay.createPaymentRequest(argsForGoogle)

Google Payの支払い情報を作成するメソッドです。

argsForGoogle オブジェクト

mulpay.createPaymentRequest(argsForGoogle)の引数argsForGoogleオブジェクトにはGoogle Payのトークンを取得する引数を指定します。
以下の項目を設定してください。

mulpay.checkAvailability()

Google Payの利用可否をチェックするメソッドです。

返り値

mulpay.fetchEncryptedTokenObject(paymentRequestForGoogle);

Google Payのトークンを取得するメソッドです。
mulpay.createPaymentRequest(argsForGoogle)で作成した支払い情報を引数に指定してください。

Google Payの支払い情報を作成するメソッドです。

argsForGoogle オブジェクト

mulpay.createPaymentRequest(argsForGoogle)の引数argsForGoogleオブジェクトにはGoogle Payのトークンを取得する引数を指定します。
以下の項目を設定してください。

Google Payの利用可否をチェックするメソッドです。

返り値

Google Payのトークンを取得するメソッドです。
mulpay.createPaymentRequest(argsForGoogle)で作成した支払い情報を引数に指定してください。

MpToken.jsでエラーが発生した場合は、resultオブジェクトのresultCodeに以下の処理結果コードを返します。 500番以下のエラーは、パラメーター不正です。処理結果コードに従って、お客様に再入力を促し、リトライ可能です。 500番以上のエラーは、原則サーバー側もしくは当社設定の異常ですので、お問い合わせください。

Web APIでカード情報をトークン化します。
スマートフォンのネイティブアプリから直接呼ばれることを想定しています。
TLS は1.2 に対応しています。 ATSにつきましては対応していませんので、アプリ側でATSに対応している場合はホワイトリストへのURLの登録をお願いします。

Web APIで利用するパラメーターencryptedDataはカード情報を暗号化した文字列です。 作成の手順を説明します。

カード情報データの用意

お客様が入力した値からネイティブアプリ内で以下のカード情報データをJSON形式で用意します。

以下はカード情報データのサンプルです。

{
  "card": {
    "cardNumber":"4111111111111111",
    "cardholderName":"HOLDER NAME",
    "expiryMonth":"05",
    "expiryYear":"24",
    "securityCode":"123"
  }
}

暗号化とBase64エンコード

前述のカード情報データのJSON文字列を管理画面からダウンロードした公開鍵を用いてRSA方式(2048bit)で暗号化します。公開鍵については認証情報を参照ください。 暗号化後の文字列をBase64エンコードした文字列を「カード情報オブジェクト」としてトークン発行リクエストパラメーターに設定します。

サンプルコード

JavaとSwiftのコードスニペットです。変数の保持方法や例外処理は適切に変更してください

public String createEncryptedData() throws Exception {
  // 管理画面からダウンロードした公開鍵
  String publicKeyString = "MIIBIjA...";
  // カード情報データのJSON文字列
  String cardInfoJson = "{\"card\":{\"cardNumber\":\"4111111111111111\",\"cardholderName\":\"HOLDERNAME\",\"expiryMonth\":\"05\",\"expiryYear\":\"24\",\"securityCode\":\"123\"}}";
  
  // 公開鍵から公開鍵オブジェクトを作成
  byte[] decodedPublicKey = Base64.getDecoder().decode(publicKeyString.getBytes(StandardCharsets.UTF_8));
  PublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(decodedPublicKey));

  // カード情報データを暗号化
  Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
  cipher.init(Cipher.ENCRYPT_MODE, publicKey);
  byte[] encryptedByte = cipher.doFinal(cardInfoJson.getBytes());

  // Base64エンコード
  String encryptedData = Base64.getEncoder().encodeToString(encryptedByte);

  return encryptedData;
}

func makeCardInfoData() -> String? {
  do{
    let publicKeyString = "MIIBIjA..."
    let cardInfoJson = "{\"card\":{\"cardNumber\":\"4111111111111111\",\"cardholderName\":\"HOLDERNAME\",\"expiryMonth\":\"05\",\"expiryYear\":\"24\",\"securityCode\":\"123\"}}"

    // 公開鍵から公開鍵オブジェクトを作成
    let data:Data = Data(base64Encoded: publicKeyString, options: Data.Base64DecodingOptions.ignoreUnknownCharacters)!
    let keyDict:[NSObject:NSObject] = [kSecAttrKeyType: kSecAttrKeyTypeRSA,
      kSecAttrKeyClass: kSecAttrKeyClassPublic,
      kSecAttrKeySizeInBits: NSNumber(value: 2048),
      kSecReturnPersistentRef: true as NSObject
    ]
    let publicKey = SecKeyCreateWithData(data as CFData, keyDict as CFDictionary, nil)

    // カード情報データを暗号化
    let plainBuffer = [UInt8](cardInfoJson.utf8)
    var cipherBufferSize : Int = Int(SecKeyGetBlockSize(publicKey!))
    var cipherBuffer = [UInt8](repeating:0, count:Int(cipherBufferSize))
    let status = SecKeyEncrypt(publicKey!, SecPadding.PKCS1, plainBuffer, plainBuffer.count, &cipherBuffer, &cipherBufferSize)
    if (status != errSecSuccess) {
      // 失敗時の処理
    }

    // Base64エンコード
    let mudata = NSData(bytes: &cipherBuffer, length: cipherBufferSize)
    let encryption = mudata.base64EncodedString(options: NSData.Base64EncodingOptions.lineLength64Characters)
    return encryption
  } catch {
    return nil
  }
}

APIリクエストがエラーになると、HTTPステータスコードは4xx、5xxを返却します。 HTTPレスポンスヘッダー、レスポンスボディはAPI仕様のResponsesを参照してください。 ただし、以下表の「種別」が「アクセスエラー」、「サービス利用不可」は、APIを受け付ける前のエラーであり、上記Responsesには記載していません。

エラー時のHTTPステータスコードとエラー情報

処理結果コード一覧

処理結果コードlegacyCodeパラメーターの一覧は以下の通りです。

PGマルチペイメントサービス 加盟店用 FAQサイトを参照ください。