トークン決済V2（MpToken.js）概要
概要
本機能は、当サービスのクレジットカード決済で利用するフロントエンドSDKです。
加盟店様は、このSDKを利用することでカード情報を直接扱わずに決済処理を実装できます。
クレジットカード決済を取り扱う加盟店様には、PCI DSSへの準拠、またはカード情報の「非保持化」が必要です。
本SDKでは、お客様が入力したカード情報を当サービスでトークン化し、解読不能な文字列「MPクレカトークン」として返却します。
加盟店様は返却されたMPクレカトークンを利用して、加盟店様サーバー上で安全に決済処理を実行できます。
Google Payの支払いで必要なPayment tokenの取得にも対応しています。
決済処理の構成は以下のとおりです。
- クライアントサイド：SDK（本ページ）
- サーバーサイド：後続のAPI処理（OpenAPIタイプ / プロトコルタイプ / モジュールタイプ）
対応決済手段
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のgetToken方式（下位互換メソッド init / getToken）を利用する場合は従来どおりです。
MpToken.js
MpToken.js は、クレジットカード情報をトークン化（MPクレカトークン）するためのJavaScriptライブラリです。
カード情報を当サービスでトークン化することで、加盟店様のシステムでカード情報を直接扱う必要がなくなり、PCI DSSの準拠範囲を削減できます。
SDK（Software Development Kit）は、当サービスのAPIを効率的に利用するためのライブラリ・ツール群です。
決済システムの開発を迅速かつ安全に行うための機能を提供します。
提供パッケージ
| パッケージ | 想定環境 | 利用可能な方式 | 推奨方式 | 補足 |
|---|---|---|---|---|
| @mul-pay/mptoken-js | Vanilla JS / ESモジュール | getToken方式 / Elements方式 | Elements方式 | 自由度の高い実装向け |
| @mul-pay/mptoken-react-js | React / Next.js | Elements方式 | Elements方式 | React向けコンポーネント・フック提供 |
| @mul-pay/mptoken-vue-js | Vue.js / Nuxt.js | Elements方式 | Elements方式 | Vue向けコンポーネント・プラグイン提供 |
トークン化方式
MpToken.js では2つのトークン化方式を提供しています。
| 方式 | 概要 | 主な対象 | 備考 |
|---|---|---|---|
| getToken方式 | 加盟店画面でカード情報を扱い、SDKでトークン化 | 既存フォームを活用したい場合 | @mul-pay/mptoken-js で利用可能 |
| Elements方式 | iframe化された入力要素を使ってトークン化 | セキュリティと実装標準化を重視する場合 | React / Vue はこの方式のみ対応。ESモジュールでも推奨 |
Elements方式の利点
Elements方式では、カード情報入力フォームがiframeで生成されるため、加盟店様のサイトにカード情報が一切通過しません。
より高いセキュリティレベルが求められる場合に推奨します。
対応している入力フォームは以下の3つです。
- カード番号
- 有効期限
- セキュリティコード
これらのフォームは弊社サーバー上で動作するため、加盟店様が用意するスタイル(CSSファイル、styleタグ)は適用できません。
スタイルを変更する場合は、フォーム生成時のオプションで設定します。
組み込み方法
トークン決済v2を利用するために、以下のライブラリを提供していますので、加盟店様の環境や用途に応じて選択してください。
| SDK / 提供形態 | 想定利用環境 | 詳細 |
|---|---|---|
| 直接読み込み MpToken.js | ブラウザ / WebView | ESモジュールページ |
@mul-pay/mptoken-js | ブラウザ / WebView | ESモジュールページ |
@mul-pay/mptoken-react-js | React / Next.js | Reactページ |
@mul-pay/mptoken-vue-js | Vue / Nuxt.js | Vueページ |
| Web API | ネイティブアプリ | MPクレカトークン発行 API仕様 |
認証情報
トークン決済v2の認証情報は以下の2つのデータを指します。
| データ名 | 用途 |
|---|---|
| 公開鍵 | カード情報を暗号化するための公開鍵です。 |
| APIキー | トークン化リクエストを当サービスで認証するための情報です。 |
トークン決済v2の利用にあたり、事前にショップ管理画面にて認証情報を登録する必要があります。 ショップ管理画面の「都度決済」->「クレジットカード」->「設定」ページを開き、「MPクレカトークン認証情報」メニューに進み、「登録」ボタンを押して認証情報を発行します。 登録された「公開鍵」と「APIキー」は、組み込み時に設定します。
環境について
本サービスでは、本番環境とテスト環境で以下の設定値が異なります：
- APIエンドポイント（FQDN）
- 認証情報（公開鍵 / APIキー）
- 発行されるトークン
異なる環境間で認証情報やトークンを共用することはできません。
また、npmパッケージをご利用の場合は、初期化時に productionMode=true を設定することで本番環境へ接続できます。
各SDKにおける環境設定方法および本番環境・テスト環境の切替方法については、各SDKページを参照してください。
| 環境 | 目的 | 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クレカトークンを利用してもトークンは無効になりません。