トークン決済V2（MpToken.js）概要
概要
クレジットカードでの決済を取り扱う加盟店様は、 PCI DSSに準拠するか、カード情報の「非保持化」が必要です。
カード情報をトークン化すると、加盟店様はお客様のカード情報を通過、処理、保存することなく決済ができ、「非保持化」を実現できます。
また、Google Payで支払いをする際に必要なPayment tokenを簡単に取得できる機能も提供します。
当サービスはお客様のカード情報を直接受け取り、解読不能な文字列「MPクレカトークン」に置き換えます。
加盟店様はMPクレカトークンを受け取り、加盟店様サーバー上で安全に処理ができます。
カード情報を保管し、次回の支払い時に利用したい場合は、当サービスの「カード登録」機能をお使いください。
対応決済
MPクレカトークンは、当サービスの以下の決済手段で利用できます。
詳細は後続のAPI処理を参照してください。
| 接続方式 | 決済手段 |
|---|---|
| OpenAPIタイプ | クレカ払い |
| プロトコルタイプ モジュールタイプ | クレジットカード決済 クレジットカード決済 自動売上 多通貨クレジットカード決済（DCC） 不正防止サービス（ReD Shield） |
利用イメージ
トークン決済v2がどのようにカード情報を扱うかを解説します。
お客様のブラウザまたはネイティブアプリから当サービスへ直接カード情報を送信することで、加盟店様サーバーはカード情報非保持を実現できます。
MPクレカトークン発行後、決済処理やカード情報の登録を行います。
トークン決済v1との違い
トークン決済v1（/ext/js/token.js もしくは /ext/api/credit/getToken API）は引き続き利用できますが、2027年4月以降にサポートを終了する予定です。
新たな脆弱性の登場やPCI DSSの要件変更等の理由によりサポート終了時期が早まる可能性があるため、「トークン決済v2」への移行を推奨します。
どちらの方式で取得したトークンでも、後続のAPI処理のパラメーターに設定できます。
トークン決済v1とトークン決済v2の比較
| 機能・特徴 | トークン決済v1 | トークン決済v2 |
|---|---|---|
| JavaScript版のパス | /ext/js/token.js | /payment/js/mp-token.js |
| API版のエンドポイント | /ext/api/credit/getToken | /payment/CreateToken.json |
| npmパッケージ公開 | ✖ | ✔ |
| ESモジュール対応 | ✖ | ✔ |
| TypeScript対応 | ✖ | ✔ |
| React、Vue.js対応 | ✖ | ✔ |
| セキュリティ | ✔ | ✔✔✔ |
| フォームのiframe対応 | ✖ | ✔ |
| Google Pay対応 | ✖ | ✔ |
| API版のJSON対応 | ✖ | ✔ |
| iOS、Android SDK対応 | ✖ | ✖ |
移行時の注意事項
トークン決済v2では、安全性向上のため仕様を変更しています。トークン決済v1から移行する場合は、加盟店様側でも対応が必要です。
返却するマスク済みカード番号
トークン決済v1では管理画面でマスクレベルを変更できましたが、トークン決済v2の返却値には適用されません。 トークン決済v2で返却するカード番号のマスクレベルは、上6桁・下4桁表示で固定です。
MPクレカトークンの利用範囲
トークン決済v2で発行したトークンは、発行時の認証情報のショップIDが属するサイトID内のショップのみで、後続のAPI処理に利用できます。 トークンの有効期間は、どのショップで発行しても同じです。
以下の例では、ショップAの認証情報で発行したトークンは、同一サイト内のショップA・ショップB・ショップCで利用できますが、異なるサイトに属するショップD・ショップEでは利用できません。
- サイト1: ショップA、ショップB、ショップC
- サイト2: ショップD、ショップE
JavaScript版の認証情報
トークン決済v1のJavaScript版では、個別の認証情報を事前登録する必要はありませんでしたが、トークン決済v2では必要です。 ただし、MpToken.jsの下位互換メソッドであるinit、getTokenを利用する場合は従来どおりです。
組み込み方法
トークン決済v2を利用するために、以下のライブラリを提供していますので、加盟店様の環境や用途に応じて選択してください。 それぞれの特徴については以下の通りです。
| ライブラリ | インストール | 対応環境 | 互換性*1 | 特徴 |
|---|---|---|---|---|
| MpToken.js | 直接読み込み | ブラウザ ネイティブアプリ内の WebView | あり | 当サービスが提供するJavaScriptライブラリです。 加盟店様の画面は自由にデザインできます。 |
| ESモジュール MpToken.js | npm@mul-pay/mptoken-js | ブラウザ ネイティブアプリ内の WebView | なし | 当サービスが提供するJavaScriptライブラリです。 加盟店様の画面は自由にデザインできます。 型定義に対応しています。 |
| React MpToken.js | npm@mul-pay/mptoken-react-js | ブラウザ ネイティブアプリ内の WebView | なし | 上記JavaScriptをReactアプリケーション から利用するためのコンポーネントです。 型定義に対応しています。 |
| Vue MpToken.js | npm@mul-pay/mptoken-vue-js | ブラウザ ネイティブアプリ内の WebView | なし | 上記JavaScriptをVueアプリケーション から利用するためのコンポーネントです。 型定義に対応しています。 |
| Web API | N/A | ネイティブアプリ | N/A | 当サービスが提供するWeb APIです。 テスト環境以外では加盟店様サーバーサイド から利用しないでください。 |
*1：トークン決済v1のJavaScriptメソッドinit、getTokenをサポートします。
認証情報
トークン決済v2の認証情報は以下の2つのデータを指します。
| データ名 | 用途 |
|---|---|
| 公開鍵 | カード情報を暗号化するための公開鍵です。 |
| APIキー | トークン化リクエストを当サービスで認証するための情報です。 |
トークン決済v2の利用にあたり、事前にショップ管理画面にて認証情報を登録する必要があります。 ショップ管理画面の「都度決済」->「クレジットカード」->「設定」ページを開き、「MPクレカトークン認証情報」メニューに進み、「登録」ボタンを押して認証情報を発行します。 登録された「公開鍵」と「APIキー」は、組み込み時に設定します。
環境とFQDN
テスト環境と本番環境を用意しています。 各環境はFQDN(絶対ドメイン名)で区別され、認証情報やトークンのデータは共用されません。 テスト環境での確認を終えて商用利用を開始する際は、以下の対応をお願いします。
- 本番アカウントの認証情報を管理画面で登録して設定値を更新
- MpToken.jsを直接読み込んでいる場合は、
srcに指定するURLを本番用のURLに更新 - npmインストールしたパッケージは、初期化時の
productionModeをtrueに設定
| 環境 | 目的 | JavaScriptのFQDN | Web APIのFQDN |
|---|---|---|---|
| テスト環境 | 接続を確認する | stg.static.mul-pay.jp | stg.token.mul-pay.jp |
| 本番環境 | 商用の取引を実行する | static.mul-pay.jp | token.mul-pay.jp |
トークンの有効期限
発行されたトークンは有効期限を過ぎるか、後続のAPI処理で利用すると無効になります。
ただし、OpenAPIタイプのカード詳細情報取得（/credit/getCardDetails）で利用しても無効になりません。
有効期限は発行した時点から30分ですが、予告なく変更される場合があります。
実際の値はトークン発行時のレスポンスパラメーターの「MPクレカトークン有効期限」で確認できます。
後続のAPI処理
加盟店様のフロントエンドで受け取ったMPクレカトークンは、加盟店様サーバーサイドでの当サービスAPI呼び出し時に設定します。対応するAPIは以下のとおりです。詳細については各リファレンスを参照してください。
| 接続方式 | 決済手段 | 対応するAPI | リファレンス |
|---|---|---|---|
| OpenAPIタイプ | クレカ払い | 都度支払い 有効性確認 カード登録 カード詳細情報取得*1 | |
| プロトコルタイプ モジュールタイプ | クレジットカード決済 | 決済実行 カード登録/更新 カード属性照会 | |
| プロトコルタイプ モジュールタイプ | クレジットカード決済 自動売上 | 自動売上定義登録 | |
| プロトコルタイプ モジュールタイプ | 多通貨クレジットカード決済（DCC） | 決済実行 カード登録/更新 カード属性照会 | |
| プロトコルタイプ モジュールタイプ | 不正防止サービス（ReD Shield） | 不正審査 |
*1: APIでMPクレカトークンを利用してもトークンは無効になりません。
MpToken.js
MpToken.js は、クレジットカード情報をトークン化（MPクレカトークン）するためのJavaScriptライブラリです。
カード情報を当サービスでトークン化することで、加盟店様のシステムでカード情報を直接扱う必要がなくなり、PCI DSSの準拠範囲を削減できます。
SDK（Software Development Kit）は、当サービスのAPIを効率的に利用するためのライブラリ・ツール群です。
決済システムの開発を迅速かつ安全に行うための機能を提供します。
提供パッケージ
| パッケージ | 用途 | 説明 |
|---|---|---|
| @mul-pay/mptoken-js | Vanilla JS / ESモジュール | 基本ライブラリ、従来型開発向け |
| @mul-pay/mptoken-react-js | React / Next.js | Reactコンポーネント・フック提供 |
| @mul-pay/mptoken-vue-js | Vue.js / Nuxt.js | Vueコンポーネント・プラグイン提供 |
トークン化方式
MpToken.js では2つのトークン化方式を提供しています。
| 方式 | 説明 | 推奨用途 |
|---|---|---|
| getToken方式 | Multipayment.getToken() でカード情報を直接指定してトークン化 | シンプルな実装、既存フォームとの連携 |
| Elements方式 | iframeで生成された入力フォームを使用してトークン化 | より安全な実装 |
Elements方式の利点
Elements方式では、カード情報入力フォームがiframeで生成されるため、加盟店様のサイトにカード情報が一切通過しません。
より高いセキュリティレベルが求められる場合に推奨します。
対応している入力フォームは以下の3つです。
- カード番号
- 有効期限
- セキュリティコード
これらのフォームは弊社サーバー上で動作するため、加盟店様が用意するスタイル(CSSファイル、styleタグ)は適用できません。
スタイルを変更する場合は、フォーム生成時のオプションで設定します。
SDK選択のポイント
クライアントサイド（ブラウザ）
カード情報のトークン化には MpToken.js を利用します。
フレームワークに応じて適切なパッケージを選択してください。
| 開発環境 | 推奨パッケージ |
|---|---|
| Vanilla JavaScript / 従来型開発 | @mul-pay/mptoken-js |
| React / Next.js | @mul-pay/mptoken-react-js |
| Vue.js / Nuxt.js | @mul-pay/mptoken-vue-js |
サーバーサイド
サーバーサイドでのAPI連携には以下の選択肢があります。
| 接続方式 | 推奨 | 説明 |
|---|---|---|
| OpenAPIタイプ | OpenAPI Generator | OpenAPI Generatorでクライアントコードを自動生成 |
| プロトコル/モジュールタイプ | モジュールタイプ | Java/PHPのクラスライブラリを使用 |
OpenAPIタイプでは、OpenAPI Generatorを使用してAPIクライアントコードを自動生成できます。
Java、Python、PHP、Node.js など多くの言語に対応しています。
エラー情報
MpToken.jsでエラーが発生した場合は、resultオブジェクトのresultCodeに以下の処理結果コードを返します。
500番以下のエラーは、パラメーター不正です。
処理結果コードに従って、お客様に再入力を促し、リトライ可能です。
500番以上のエラーは、原則サーバー側もしくは当社設定の異常ですので、お問い合わせください。
| コード | 説明 |
|---|---|
000 | 正常終了 |
100 | カード番号必須チェックエラー |
101 | カード番号フォーマットエラー(数字以外を含む) |
102 | カード番号フォーマットエラー(10-16桁の範囲外) |
110 | 有効期限必須チェックエラー |
111 | 有効期限フォーマットエラー(数字以外を含む) |
112 | 有効期限フォーマットエラー(6または4桁以外) |
113 | 有効期限フォーマットエラー(月が13以上) |
121 | セキュリティコードフォーマットエラー(数字以外を含む) |
122 | セキュリティコード桁数エラー |
131 | カード名義人フォーマットエラー(半角英数字、一部の記号以外を含む) |
132 | カード名義人フォーマットエラー(51桁以上) |
141 | MPクレカトークン発行数フォーマットエラー(数字以外を含む) |
142 | MPクレカトークン発行数フォーマットエラー(1-10の範囲外) |
150 | カード情報オブジェクト必須チェックエラー |
160 | APIキー必須チェックエラー |
161 | APIキーフォーマットエラー |
180 | APIキーが無効 |
190 | カード情報オブジェクトが復号できない |
191 | カード情報オブジェクトフォーマットエラー |
901 | 当サービス内部のシステムエラー |
902 | 処理が混み合っている |