PGマルチペイメントサービス OpenAPIタイプ (1.2.3)

Download OpenAPI specification:Download

はじめに

INTRODUCTIONセクションは、OpenAPIタイプを初めて扱うシステム担当者の方、開発者の方に向けたドキュメントです。
OpenAPIタイプの全体像、実現できる決済処理、導入までの流れやテストについて説明します。
また、従来の接続方式であるプロトコル/モジュールタイプをご利用の加盟店様が、OpenAPIタイプに移行する場合に考慮すべき事項についても説明しています。
プロトコルタイプの仕様はマルペイDocsを参照してください。
※マルペイDocsの利用方法はこちら

OpenAPIタイプ用語集


用語 説明
加盟店様 PGマルチペイメントサービスを利用する貴社を指します。
お客様 加盟店様からサービス・物品の提供を受ける、最終利用者を指します。
支払いタイプ OpenAPIタイプでは、決済手段を支払いの特徴ごとに3つの支払いタイプに
分類しています。APIは支払いタイプごとに集約された構成になっています。
Webhook 一部の支払いタイプにおいて、取引状態に更新があった際に、加盟店様に
HTTPプロトコルを使用して通知する仕組みです。

OpenAPIタイプの特徴

OpenAPIタイプは、簡単かつ安全に利⽤いただくことを⽬指し、RFCやOpenAPI SpecificationなどのWeb標準に従っています。
加えて、決済手段の追加や不正検知への対応を柔軟に行えるよう最適化されています。
具体的な技術的特徴は以下の通りです。より詳細な仕様はGET STARTEDセクションを参照ください。

  • OpenAPI Specification(OAS)に準拠
    OpenAPI Generatorなどのツールを使ってコードの一部自動生成やモックサーバーの構築ができます。 OASの標準に従っているので、API仕様を理解しやすく、開発負荷を削減し、接続作業を効率化します。

  • Remote Procedure Call(RPC/遠隔手続き呼び出し)に基づいた設計
    決済処理の特性をAPIで表現するには、「リソース」操作をベースとしたREST形式ではなく、「手続き」を要求するRPC形式が最適です。
    全てのAPIはアクションで表され、HTTPメソッドはPOSTで統一されています。
    つまり、取引の「照会」「削除」要求APIであってもRESTとは異なりHTTPメソッドはPOSTです。
    ペイロードはJSON形式で表すこと、HTTPステータスコードでレスポンスの内容を表す様式は、使い慣れたRESTと同じです。

  • 冪等性(Idempotency)をサポート
    二重決済となる心配は無用です。同一の冪等キーを設定した決済要求を何度リトライしても、決済は一回しか行われず同じレスポンスを返します。
    ネットワークエラーなどの場合に加盟店様から自動リトライすれば、不整合となった決済リクエストを安全に修復できます。
    決済データの一貫性を保ち、加盟店様サービスのお客様にも安心してご利用いただける環境を提供します。

他にも末永く安心して使っていただけるよう以下の特徴を提供します。

  • 簡単な決済手段追加
    支払いタイプごとに集約したAPI構成になっています。
    決済手段追加時の開発コストを削減できるので、貴社ビジネス部門からの「この決済手段を試したい」という要望に迅速に対応できます。

  • 決済の不正利用を防止
    あらゆる不正検知ソリューションに対応しています。
    決済要求APIに組み込まれているので、追加の開発は必要ありません。
    主にクレジットカード決済を対象としています。

  • 高度なセキュリティ対策
    APIの通信はTLS(SSL)による暗号を必須としており、政府機関レベルの強固な暗号化方式のみを許可しています。
    また、APIへのアクセス認証においては、従来のパスワード方式に加えて、より安全性の高いOAuth 2.0を利用したアクセストークン方式もサポートします。
    PCI DSS(Payment Card Industry Data Security Standard)に準拠した内部システムでは、全ての個人情報が暗号化されています。
    私たちのシステムは常に最新のセキュリティ標準にアップデートしており、お客様に安心してご利用いただける環境を提供しています。

また、OpenAPIタイプと従来のプロトコルタイプ/モジュールタイプには互換性があります。
現在プロトコル/モジュールタイプをご利⽤いただいている加盟店様は、簡単にOpenAPIタイプへ移行できます。
取引の情報や登録済みの会員データはそのまま利⽤ができ、ショップの情報や各種設定は変わりません。
管理画⾯、取引配信サービス、SFTP⼀括処理などはこれまで通りご利⽤になれます。
詳細はプロトコルタイプ/モジュールタイプからの移行を参照ください。

支払い処理

OpenAPIタイプが様々な決済手段をどのように定義し、処理しているかを解説します。
まず、支払いパターンは支払いのタイミングやお客様操作の有無によって3つに分類されます。

支払いパターン 説明 OpenAPIタイプでの取り扱い
都度支払い
one-off
支払いの都度、お客様が決済に必要な情報入力や手続きをする支払いパターンです。
例)
クレジットカード番号を入力しての支払い
Amazonアカウントに登録してあるクレジットカードを使ったAmazon Pay V2での支払い
払い出された決済番号を使った、コンビニでの支払い
全ての決済手段で
利用できます。
随時支払い
on-file
支払いに必要な番号や認証情報を当サービスに事前に保管しておき、お客様が都度の情報を入力することなくお支払いができる支払いパターンです。
オートチャージのように一定の条件下でお客様の操作なく支払いを完了させる場合も含まれます。
以下の「定期支払い」と同様の仕組みを加盟店様システム内にて構築する場合は「随時支払い」をご利用ください。
例)
当サービスに保管済みの番号を設定したクレジットカード支払い
当サービスに保管済みの認証情報を設定してログイン遷移なく実施する楽天ペイ(オンライン決済)V2での支払い
一部の決済手段で
利用できます。
定期支払い
recurring
決められたスケジュール、決められた金額での支払いを継続する支払いパターンです。
例)
当サービスに保管済みのカード番号を利用して、自動で毎月10日に会費1,000円をクレジットカードで支払い
現在は利用できません。
今後、クレジットカード決済
のみ対応予定です。

決済手段は以下の支払いタイプに分類されます。

支払い
タイプ
決済手段 処理の流れと支払い成立条件 随時支払い(on-file)への対応 対応するAPI
クレカ払い 1.クレジットカード
2.Google Pay
3.Apple Pay

*Apple Pay以外は
3Dセキュアに対応
加盟店様サイトからの支払い要求リクエストを
受けると、当サービスからカード会社にオーソリ
(信用照会)を行います。
カード会社から与信成功が返れば支払い
成立です。
支払いの結果はレスポンスとして即時
お戻しします。

3Dセキュア認証を行う場合は一度外部の
認証機関に遷移した後にオーソリをします。
当サービスに保管したカード情報を
利用して随時支払いが可能です。

Google Payのアカウントそのものを保管
して随時支払いはできません。
しかし、実際に使用されたクレジットカード
を保管してクレカ払いとして随時支払いに
利用できます。

Apple Payについては、VISAブランド以外
は随時支払いに対応していますが、利用
できなくなる可能性があります。
/credit/charge
/credit/on-file/charge
Pay払い 1.PayPay
2.d払い
3.楽天ペイ(オンライン決済)V2
4.Amazon Pay V2
5.au PAY(ネット支払い)アプリ方式
6.メルペイ
加盟店様サイトからの支払い要求リクエスト後に
別のサイトやアプリに遷移し、お客様自身
による同意が必要です。
Pay払い提供会社の認証が成功して加盟店様
サイトが設定したURLに遷移が戻った
タイミングで支払いを成立させてください。
全てのPay払いで認証情報を保管できます。
ご利用には事前の承諾が必要です。
詳細は利用承諾APIを参照ください。
/wallet/charge
/wallet/on-file/charge
現金払い 1.コンビニ
2.Pay-easy
3.銀行振込
(バーチャル口座)
加盟店様サイトからの支払い要求リクエストを
受けて決済機関に対して支払いに必要な情報を
要求します。
それらの支払い番号などの情報を戻します
ので加盟店様からお客様に通知してください。
お客様が支払うと、当サービスから加盟店様に
Webhookで通知します。
この通知を受け取ったタイミングで支払い
を成立させてください。
利用できません。 /cash/charge

導入の流れとテスト

OpenAPIタイプを利用してPGマルチペイメントサービスをインテグレーションする流れを説明します。

  1. テストアカウントの申し込み
    PGマルチペイメントサービスのテストアカウントはこちらからどなたでも申し込み可能です。

  2. テストアカウントの認証情報でテスト環境に接続してテスト
    テストアカウントのショップIDとショップパスワードがテスト環境の認証情報です。
    認証情報を設定してAPIにアクセスするためには、APIの認証を参照ください。
    テスト環境の接続先情報については、環境とFQDNを参照ください。
    テスト環境はメンテナンス時を除き、24時間365日無料で利用可能です。

  3. 本番アカウントの申し込み
    本番環境のアカウント申し込みは、貴社ビジネス担当の方から当サービス営業窓口までお願いします。
    審査、契約のお手続きが完了後に本番アカウントが発行されます。

  4. 本番環境に接続を切り替えて商用利用開始
    本番アカウントのショップIDとショップパスワードが本番環境の認証情報です。
    認証情報の設定とAPIエンドポイント(URI)を本番環境のものに切り替えたら接続準備は完了です。


プロトコルタイプ/モジュールタイプからの移行

プロトコルタイプ/モジュールタイプは引き続き利用いただけますが、より便利なOpenAPIタイプに移行することを推奨します。
前述の通り、OpenAPIタイプと従来の接続方式には互換性があり併用が可能です。
例えば取引の確定をするスケジュール処理を先⾏して実装するといった柔軟な移⾏が可能です。
詳細な情報については、プロトコルタイプ対応表を参照ください。

プロトコルタイプ/モジュールタイプとOpenAPIタイプで共通して取り扱うデータについて説明します。

データ 説明
ショップID 共通して利用でき、変更の必要はありません。
テスト環境のショップIDも同様です。
ショップパスワード 共通して利用でき、変更の必要はありません。
管理画面からパスワードを変更した場合、両方に反映されます。
サイトID OpenAPIタイプでは利用しません。
ショップIDの設定により、紐づくサイトIDが自動で利用されます。
カード登録時の処理料ご請求先は、これまで通り請求先ショップです。
サイトパスワード OpenAPIタイプでは利用しません。
取引ID 共通の仕様で発行され、両方で利用できます。
取引パスワード OpenAPIタイプでは利用しません。
元の取引を指定する場合は取引IDのみで行います。
取引ステータス 共通して利用できます。
オーダーID 共通して利用できます。
会員ID 共通して利用できます。
カード登録連番モード OpenAPIタイプでは利用しません。
従来の「物理モード」が標準ですが、「論理モード」もサポートします。
カード登録連番 OpenAPIタイプでは従来の「物理登録連番」を「カードID」と表します。
「論理登録連番」は「カードインデックス」として扱います。

従来のプロトコルタイプ/モジュールタイプとOpenAPIタイプには、一部の仕様に差異があります。
移行においては、特に以下の点にご注意ください。

  • OpenAPIタイプでは、従来の「結果通知プログラム」は利用できません。
    タイムアウトなどのレスポンスを受け取れない場合は、同一の冪等キーを設定してリトライをお願いします。
  • モバイルEdy決済、モバイルSuica決済など、支払い処理に記載のない決済手段は現時点で提供の予定はありません。
  • 金額と税送料は統合しました。税送料は個別に設定できません。
  • 個別の加盟店様向けの特殊機能やオプションパラメーターは利用できません。
  • 同時接続数はプロトコルタイプ/モジュールタイプに適用されている値に準じます。
  • プロトコルタイプ/モジュールタイプで取引登録を行った取引に対してOpenAPIタイプで処理を行った場合、従来の「結果通知プログラム」仕様に則り通知がされます。

接続してみましょう

GET STARTEDセクションは、開発者の方に向けた共通の技術仕様に関するドキュメントです。
実際にOpenAPIタイプに接続するプログラム開発をするにあたりお読みください。


テストアカウントの申し込み

OpenAPIタイプに接続するための第一歩は、テストアカウントの作成です。
こちらのテスト環境申し込みページから即時発行が可能です。
登録が完了すると申し込み時のメールアドレスにショップ管理画面のログイン情報が届きます。
ショップ管理画面にログインし、「ショップ管理」メニューから「ショップパスワード」を確認します。
メールまたは管理画面に表示されている「ショップID」と「ショップパスワード」が、APIを利用するための認証情報です。


APIエンドポイントの原則

APIのエンドポイントはRemote Procedure Call(RPC/遠隔手続き呼び出し)のマナーに従います。
一般に広く利用されているREST APIのようにエンドポイントは操作するリソースを表していません。
クレジットカード決済の「オーソリ(信用照会)」、取引の「確定」のように操作の単位にエンドポイントがあります。
例えばクレジットカードの支払い要求APIは「/credit/charge」、取引照会APIは「/order/inquiry」です。


セキュリティ

APIを安全にご利用いただくための情報やご注意事項を説明します。

TLS通信の暗号スイート

APIへの接続は安全なHTTPSおよびSSLプロトコルTLS 1.2の暗号通信を利用します。
高い安全性を実現するために以下のTLS暗号スイートのみが利用可能です。
API通信を行う加盟店様のサーバーがこれらの暗号スイートに対応していることを確認してください。
新たな脆弱性が見つかった場合、この一覧は変更になる可能性があります。

暗号スイート
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

APIへのアクセス認証

APIにアクセスするための認証方式は以下の2つを用意しています。
組み合わせて利用できますので、現在パスワード方式をご利用の加盟店様は順次アクセストークン方式に切り替え可能です。
APIエンドポイントによりサポートする方式が異なります。各API仕様詳細のAUTHORIZATIONS:欄を確認してください。

  • パスワード方式
    ショップIDとショップパスワードの組み合わせで認証します。
    ショップパスワードの紛失・漏洩に備え、定期的なショップパスワード変更を推奨します。
    変更の方法はこちらのFAQページを参照ください。

  • アクセストークン方式
    事前に取得したアクセストークンで認証します。
    アクセストークンは有効期間内であれば何回も利用できますが、一定の時間で失効します。
    これにより、万が一アクセストークンが漏洩した場合でも、リスクを最小限に抑えられます。
    本方式を利用する場合、管理画面からパスワード認証方式を無効にすることにより、セキュリティをさらに強化できます。

詳細な仕様については、APIの認証を参照ください。
どちらの認証方式においても、ショップIDとショップパスワードが用いられます。
これら2つの認証情報をセットで外部に公開しないよう、厳重な管理をお願いします。

セッション管理

OpenAPIタイプが提供する全てのAPIはセッションを維持しません。
APIの通信時に毎回上記の認証をします。

偽装通信への対策

リダイレクトやWebhook時は、当サービスから加盟店様サーバーに通信します。
これらの通信は、悪意のあるユーザーにより偽装される可能性があります。
対策としては、事前のリクエスト時にMerchant.csrfTokenパラメーターに加盟店様側で発行した任意の文字列を設定します。
このcsrfTokenの値をリダイレクトやWebhook時に返しますので、通信の正当性を確認してください。

パラメーターの設定

フォーマット

支払いAPIのパラメーターはJSON形式、文字コードはUTF-8で設定します。
認証APIはRFCに準拠しているため、キー・バリューのフォームデータ型で設定します。
利用可能な文字はパラメーターにより異なります。
各APIのリクエストパラメーターの説明を確認してください。

リクエストの必須パラメーター

requiredがついているパラメーターは必ず設定してください。
加盟店(ショップ)情報merchantや取引情報orderなど、支払いのタイプに関係なく共通して利用する可能性があるパラメーターを設定必須にしています。
購入者の氏名(フルネーム)payer.nameなど、加盟店様サイトで取得が難しい項目につきましても、できる限り設定するようお願いします。

リクエストの任意パラメーター

requiredがついてないパラメーターであっても、支払いのタイプによっては設定が必要です。
missing_parameterエラーを返しますので設定をお願いします。
必須ではないパラメーターに値を設定しない場合、以下のいずれの方式でも受け付けます。

  • 値に「null」を設定
    {"requestParameter": null}
    
  • Stringタイプのパラメーターの場合、値に「空文字 ""」を設定
    {"requestParameter":""}
    
  • パラメーターを設定しない
    {}
    

レスポンスパラメーター

レスポンスパラメーターについて、値なし(null)の場合は当サービスからパラメーターを返しません。
加盟店様のシステムでは、パラメーターなしのレスポンスを正しく受け取れるようにしてください。
またアップグレードにより、追加のパラメーターが返される可能性があります。
定義されていないパラメーターをエラーとして扱わないようお願いします。


リクエストのHTTPヘッダー

HTTPヘッダーにはAPIリクエストにおける共通の内容を設定します。
OpenAPIタイプでは以下のデータを送信してください。

項目 備考
Authorization 認証情報
認証方式により設定する内容が異なります。
 - パスワード方式: Basic ベーシック認証データ
 - アクセストークン方式: Bearer アクセストークン
詳細はAPIの認証を参照ください。
Content-Type コンテントタイプ
APIエンドポイントにより設定する内容が異なります。
 - アクセストークン発行API: application/x-www-form-urlencoded
 - 上記以外のAPI: application/json
Idempotency-Key 冪等キー
UUIDv4に則った書式でリクエスト毎にユニークな
最大36桁の値です。
詳細は冪等処理を参照ください。
X-MP-Version APIバージョン
本APIのバージョンを表すYYYY-MM形式の値です。
例) 2023-06, 2024-12
OpenAPIタイプのAPIバージョンを
指定して実行する場合に利用します。
省略時や日付の様式が正しくない
場合は最新のバージョンとして
扱われます。
詳細はバージョン管理を参照ください。

パスワード方式で冪等キーとAPIバージョンを利用しない場合の設定例です。

Authorization: Basic dGVzdDoxMjPCow==
Content-Type: application/json

アクセストークン方式で冪等キーとAPIバージョンを利用する場合の設定例です。

Authorization: Bearer M2NlNjE1ZjYtMzc1Yy00ZGQ5LTg0OTAtOGEwNzliMzYyMjUzOjAwMDAwMDAwMDAwMDA=
Content-Type: application/json
Idempotency-Key: ede66c43-9b9d-4222-93ed-5f11c96e08e2
X-MP-Version: 2023-06

APIの認証

認証方式によって加盟店様の開発コスト、セキュリティレベルが異なります。
それぞれの特徴・注意事項はセキュリティを参照ください。

方式 方式(和名) ベース技術 開発コスト セキュリティ
レベル
Password パスワード方式 Basic HTTP認証スキーム(ベーシック認証)
AccessToken アクセストークン方式 OAuth2.0認可フレームワーク

パスワード方式

ショップIDとショップパスワードを利用したBasic HTTP認証スキーム(ベーシック認証)で認証します。
ベーシック認証(RFC 7617)で定義されている仕様に従います。
「ショップID」と「:」(コロン)と「ショップパスワード」を連結した文字列をBase64エンコードした値を用意します。
認証スキーマ名である「Basic」と「 」(半角スペース)の後にこのエンコード後の値を続けた文字列が認証データです。
この認証データをHTTPリクエストヘッダーのAuthorizationに設定します。

以下はHTTPリクエストヘッダーの設定例です。

Authorization: Basic dGVzdDoxMjPCow==

アクセストークン方式

事前に取得したアクセストークンで認証します。
OAuth2.0認可フレームワーク(RFC 6749)で定義されている仕様に従います。
アクセストークン発行APIをリクエストすることでアクセストークンが払い出されます。
アクセストークン発行APIの認証は、パスワード方式で行います。
アクセストークンは有効期間内であれば何回も利用できます。
有効期間はデフォルト3,600秒(1時間)ですが、予告なしに変更される場合があります。
実際の値はアクセストークン発行APIのレスポンスの有効期間(秒)expires_inで確認できます。
有効期間を過ぎるとHTTPステータス401のエラーが返されますので、再度アクセストークンを発行してください。


アクセストークンを発行する認可サーバーは環境によりURLが異なります。
環境 認可サーバー
テスト環境 https://stg.oauth.mul-pay.jp/token
本番環境 https://oauth.mul-pay.jp/token

認証スキーマ名である「Bearer」と「 」(半角スペース)の後にアクセストークンを加えた文字列が認証データです。
支払いAPIなどをリクエストする場合は、この認証データをHTTPリクエストヘッダーのAuthorizationに設定します。

以下はHTTPリクエストヘッダーの設定例です。

Authorization: Bearer M2NlNjE1ZjYtMzc1Yy00ZGQ5LTg0OTAtOGEwNzliMzYyMjUzOjAwMDAwMDAwMDAwMDA=

冪等処理

冪等性(べきとうせい)とは、同じ操作を何度繰り返しても、同じ結果が得られるという性質です。
OpenAPIタイプの対象APIは冪等性をサポートしており、安全にリトライが可能です。
冪等にするためには、HTTPヘッダーに任意の値の冪等キーを設定します。
同一の冪等キーが設定された支払い要求は、何度呼ばれても支払いは一回しか行われず同じレスポンスを返します。
冪等キーの有効期間は対象取引の開始から24時間です。
冪等キーは、UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値を設定してください。

以下はHTTPリクエストヘッダーの設定例です。

Idempotency-Key: ede66c43-9b9d-4222-93ed-5f11c96e08e2

主に更新処理を伴うAPIが冪等性を持ちます。冪等性を持つか否かは、各APIの詳細仕様を確認してください。


リダイレクトとコールバック

リダイレクト

3Dセキュア認証処理やPay払いは、外部のサイトにリダイレクトします。
OpenAPIタイプでは全てのリダイレクト処理をHTTPメソッドGETで実現します。
当サービスから返された遷移先URLにリダイレクトする処理のサンプルです。

<!--  HTTPヘッダを使って302リダイレクトする場合 -->
HTTP/1.1 302 Found
Location: {redirectUrl}
<!-- meta refreshでリダイレクトする場合 -->
<html>
  <head>
    <meta http-equiv="refresh" content="0; URL={redirectUrl}" />
  </head>
</html>

コールバック

リダイレクト後は、お客様と遷移先のサイトの間で処理が行われます。
処理が終わると取引リクエスト時に設定した加盟店様のコールバックURLcallbackUrlに遷移を戻します。
加盟店様のシステムで遷移を受け取れるようコールバックのエンドポイントをご用意ください。
コールバックの呼び出し時のHTTPメソッドはGETです。
元の取引を特定するために、以下のパラメーターを送信します。
パラーメーターはJSON形式の文字列をBase64URLエンコードし、コールバックURLのクエリパラメーターpに設定します。
Base64URLデコードしてご利用ください。

パラメーター 説明
accessId 取引リクエスト時に返された取引ID
event このコールバックのイベントタイプ
TDS_CHARGE_FINISHED
3Dセキュアの支払いにてautoAuthorization=trueの場合に返します。取引照会にて状態を確認し決済成否を判断してください。
TDS_VERIFICATION_FINISHED
3Dセキュアの有効性確認にてautoAuthorization=trueの場合に返します。取引照会にて状態を確認し決済成否を判断してください。
TDS_FINISHED
3Dセキュアの支払い・有効性確認にてautoAuthorization=falseの場合に返します。3Dセキュア後の支払い・有効性確認を実施してください
WALLET_CHARGE_FINISHED
Pay払いの都度支払いにて返します。取引照会にて状態を確認し決済成否を判断してください。
WALLET_APPROVAL_FINISHED
Pay払いの利用承諾にて返します。取引照会にて状態を確認し決済成否を判断してください。
csrfToken chargeリクエスト時に加盟店様が設定した任意の値
※加盟店様システムにてコールバック受け取り後にCSRF対策として
正当性を確認することを想定しています。文字数は最大36桁です。

例を以下に示します。

取引リクエスト時に加盟店様が設定したコールバックURL

https://merchant.example.com/callback

コールバック時に当サービスにてBase64URLエンコードした値をクエリパラメーターに追加

https://merchant.example.com/callback?p=eyJhY2Nlc3NJZCI6ImFjZGM3ZDUzZjdhNzhmNDg4ZDhkMDk5N2VmZjk5YzZmIiwiZXZlbnQiOiJURFNfQ0hBUkdFX0ZJTklTSEVEIiwiY3NyZlRva2VuIjoiYmRiMDRjNWYtNDJmMC0yOWUyLTA5NzktZWRhZTNlNzc2MGJmIn0=

上記pパラメーターの値をBase64URLデコードした結果

{
  "accessId":"acdc7d53f7a78f488d8d0997eff99c6f",
  "event":"TDS_CHARGE_FINISHED",
  "csrfToken":"bdb04c5f-42f0-29e2-0979-edae3e7760bf"
}

Webhook通知

非同期で処理された取引の結果を取引リクエスト時に設定した加盟店様のWebhook URLwebhookUrlに通知します。
以下の取引イベントが通知の対象です。

加盟店様のシステムで通知を受け取れるようWebhookエンドポイントをご用意ください。
Webhookを通知する時のHTTPメソッドはPOSTで、HTTPリクエストヘッダーのContent-Typeは、application/jsonです。
通知のパラメーターは、WebhookのAPI仕様を参照ください。
Webhookを受信して正常に処理をした後は、HTTPステータス200番台を返してください。
レスポンスのボディは不要です。
200番台以外が返された場合は通知失敗とみなし、約60分毎に最大5回再送します。

加盟店様システムにて通信制限をしている場合、Webhookを受け取るよう以下のIPアドレスを許可してください。

環境 送信元IPアドレス
テスト環境 210.197.108.196
本番環境 210.175.7.20

環境とFQDN

テスト環境と本番環境を用意しています。
各環境はFQDN(絶対ドメイン名)で区別され、取引のデータは共用されません。
テスト環境での確認を終えて商用利用を開始する際は、以下の2点を切り替えます。

  • HTTPヘッダーの「認証情報」を本番アカウントのものに更新
  • 接続先のAPIエンドポイントのFQDNを以下のものに更新
環境 目的 FQDN
テスト環境 APIの接続を確認する stg.openapi.mul-pay.jp
本番環境 商用の取引を実行する openapi.mul-pay.jp

バージョン管理

OpenAPIタイプのAPI仕様は順次アップグレードされ機能が追加されていきますが、加盟店様の稼働中システムに影響を与える破壊的変更は原則行いません。
それでも破壊的変更を伴うアップグレード時は、数ヵ月前に加盟店様にご連絡いたします。
以下は破壊的変更ではなく、後方互換があるものとして扱われます。

  • エンドポイントの追加
  • Webhook通知、コールバック時イベントeventの追加 (加盟店様側で新たなイベントを受け取れるための開発は必要です)
  • 設定任意リクエストパラメーターの追加
  • レスポンスパラメーターの追加
  • 設定任意リクエストHTTPヘッダー項目の追加
  • レスポンスHTTPヘッダー項目の追加
  • リクエストパラメーターに設定する文字列長・文字種・パターンの追加
  • 設定必須リクエストパラメーターを任意へ変更

OpenAPIタイプのAPIリファレンス(OASファイル)とAPI仕様それぞれにバージョンがあります。
変更の内容は変更履歴を参照ください。

種類 形式 表記の例
APIリファレンス
(OASファイル)
バージョン
セマンティック・バージョニング形式
1.0.1
APIバージョン YYYY-MM(年月)形式 2023-06

APIリファレンス(OASファイル)バージョン

OpenAPIタイプのAPIリファレンス、およびダウンロード可能なOpenAPI specification(OAS)ファイルのバージョンです。
以下の基準で各バージョンが上がります。

バージョン 基準
メジャー (1番目の数字) 後方互換がない破壊的変更
マイナー (2番目の数字) 仕様追加や変更・削除
パッチ (3番目の数字) 軽微な仕様変更や説明の追加・修正

APIバージョン

当サービスのAPI仕様のバージョン番号です。
後方互換がない破壊的変更を伴うリリース時の年月を新規に割りあてます。
HTTPヘッダーのAPIバージョンを設定することで破壊的変更前の仕様を保証します。
該当しないバージョン番号(年月)が設定されている場合、それより過去で最も近い年月のバージョンで動作します。
APIバージョンは頻繁に上がりませんが、将来の破壊的変更に備えて予めHTTPヘッダーにバージョン番号または加盟店様システム構築時の年月を設定してください。

例)
APIバージョンが2023-06から2024-06にアップグレード
HTTPヘッダーのAPIバージョンに2023-10が設定されている場合は2023-06バージョンで動作
ただし、2023-13のように日付の様式が正しくない場合は最新バージョンで動作

HTTPステータスコード

HTTPステータスコードは、APIリクエストに対する処理結果を表す3桁の数字です。
OpenAPIタイプでは、RFC 7231, section 6の仕様に従って、以下の3つのカテゴリのHTTPステータスコードを返します。

  • 2xxはリクエストが正常に受け付けられ、当サービスで処理されたことを表します。
  • 4xxは接続方法やパラメーターが正しくないなどのリクエストに誤りがあることを表します。
    お客様のアカウント状態や残高に問題があり、支払いが完了できない場合のエラーも含まれます。
  • 5xxは、当サービスまたは当サービスから先のネットワーク事業者、決済事業者に問題が発生していることを表します。

APIごとに発生するHTTPステータスコードについては、各API仕様のResponsesを確認してください。
ただし、以下表の「種別」が「認証エラー」、「アクセスエラー」は、APIを受け付ける前のエラーであり、全てのAPIで発生する可能性があります。

HTTP
ステータス
コード
種別 説明
200 成功 照会系のリクエストは正常に処理されました。
201 成功 更新系のリクエストは正常に処理されました。
202 成功 更新系のリクエストが受け付けられ、完了のためには後続の処理が必要です。
400 リクエストパラメーターエラー パラメーターの内容が正しくない、または状態が不正なため、リクエストは処理できません。
401 認証エラー APIの認証情報が正しくないため、リクエストは受け付けられません。
402 リクエストエラー 外部の事業者にて支払い・承認・確定・取消リクエストが拒否されました。
404 アクセスエラー APIエンドポイントが無効であるため、リクエストは受け付けられません。
405 アクセスエラー HTTPメソッドが正しくないため、リクエストは受け付けられません。
リダイレクト時はGET、それ以外はPOSTです。
409 アクセスエラー 二重リクエストのため、リクエストは受け付けられません。
415 アクセスエラー Content-Typeヘッダーが正しくないため、リクエストは受け付けられません。
429 アクセスエラー 同時処理数が規定値を超えているため、リクエストは受け付けられません。
500 当サービス内部のシステムエラー 当サービスのサーバーで問題が発生したため、リクエストを処理できませんでした。
502 外部事業者のシステムエラー 外部事業者やネットワークで問題が発生したため、リクエストを処理できませんでした。
503 メンテナンスのため利用不可 メンテナンス中のため、リクエストは受け付けられません。

エラーの情報

APIリクエストがエラーになると、前述の通りHTTPステータスコード4xx5xxで返します。
レスポンスボディはRFC 9457の仕様に従って以下のエラー情報をJSON形式で返します。
HTTPレスポンスヘッダーのContent-Typeは、application/problem+jsonです。

キー 説明
type エラーの説明ページURL
該当のエラーに説明ページがない場合は何も返しません
https://mp-faq.gmo-pg.com/s/article/D00923
title エラーの内容サマリー
エラーコードとして取り扱えます
一覧は以下の表を参照ください
invalid_parameter
detail エラーの詳細説明
エラーメッセージとして取り扱えます
全て英文です。
The value provided for parameter is invalid.(orderid)
instance エラーが発生したエンドポイント /credit/charge

titleパラメーター(エラーの内容サマリー)の一覧は以下の通りです。

title名 説明 HTTP
ステータス
コード
invalid_contract 対象ショップの契約状態が無効であるか、ショップの設定が不足しています。 400
invalid_header リクエストヘッダの値が不正です。 400
invalid_parameter リクエストパラメーターの書式または桁数が不正です。 400
invalid_request 対象の取引に対して不正なリクエストです。 400
invalid_status 対象の取引状態に対して処理できないリクエストです。 400
missing_parameter 必須パラメーターが設定されていません。 400
transaction_count_exceeded 同一取引に対する処理上限を超過しています。
所定の返金回数を超過した場合などに発生します。
400
transaction_expired 処理期限を超過しています。
オーソリの有効期限超過後に確定を行った場合などに発生します。
400
unauthorized_request APIの認証情報が正しくないため、リクエストは受け付けられません。 401
operation_aborted_by_user お客様の操作により決済手続きが中止されました。 402
card_declined カード起因のエラーにより、リクエストが拒否されました。 402
insufficient_balance 残高が不足しているため、リクエストが拒否されました。 402
amount_limit_exceeded 上限金額を超過しているため、リクエストが拒否されました。 402
processing_failure 決済事業者からエラーが返されました。
詳細はdetailを参照ください。
402
resource_not_found APIエンドポイントが無効であるため、リクエストは受け付けられません。 404
method_not_allowed HTTPメソッドが正しくないため、リクエストは受け付けられません。
リダイレクト時はGET、それ以外はPOSTです。
405
conflict 二重リクエストのため、リクエストは受け付けられません。 409
unsupported_media_type Content-Typeヘッダーが正しくないため、リクエストは受け付けられません。
application/jsonのみに対応しています。
415
too_many_requests 同時接続数の上限を超過しています。 429
internal_server_error 当サービスのサーバーで問題が発生したため、リクエストを処理できませんでした。 500
bad_gateway 外部事業者やネットワークで問題が発生したため、リクエストを処理できませんでした。 502
maintenance 外部事業者によるメンテナンスのため、リクエストは受け付けられません。 502
service_unavailable メンテナンス中のため、リクエストは受け付けられません。 503

以下はエラーレスポンスのサンプルです。

{
  "type":"https://mp-faq.gmo-pg.com/s/article/XXXXXX",
  "title":"invalid_parameter",
  "detail":"The parameter value is invalid.(order.amount)",
  "instance":"/credit/charge"
}

アクセストークン

支払いAPIを利用するためのアクセストークンを発行します

アクセストークン発行

アクセストークン方式の認証に利用するアクセストークンを発行するために呼び出すAPIです。
認証の詳細はAPIの認証を参照ください。

Authorizations:
Password
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

グラントタイプ
client_credentialsを設定してください。

scope
required
string
Value: "openapi"

スコープ openapiを設定してください。

Responses

Request samples

Content type
application/x-www-form-urlencoded
grant_type=client_credentials&scope=openapi

Response samples

Content type
application/json
{
  • "access_token": "M2NlNjE1ZjYtMzc1Yy00ZGQ5LTg0OTAtOGEwNzliMzYyMjUzOjAwMDAwMDAwMDAwMDA=",
  • "expires_in": "3600",
  • "scope": "openapi",
  • "token_type": "bearer"
}

クレカ払い

クレカ払いで利用するAPIです。

ご利用可能なカード

以下の国際ブランドがついたクレジットカード・デビットカード、およびそのカード情報を登録したApple Pay、Google Payのお支払いに対応します。

  • VISA
  • Mastercard
  • JCB
  • American Express
  • Diners Club

仮売上と確定

「仮売上」については、こちらのFAQページを参照ください。
支払い要求タイプが仮売上"creditChargeOptions.authorizationMode" : "AUTH"の支払いは、確定処理により売上が確定します。
仮売上の有効期限は60日後の23時59分59秒であり、詳細な日時は支払い完了後に返される仮売上有効日時creditResult.captureExpiryDateTimeを確認してください。
例えば2020/1/8 17:00に仮売上の支払いをした場合、確定処理の期限は2020/3/8 23:59:59です。
即時売上"creditChargeOptions.authorizationMode" : "CAPTURE"の支払いは、即座に売上が確定するため、確定処理は必要ありません。

処理シーケンス

3Dセキュア認証(EMV 3-D Secure)は、自動オーソリの有無により処理のシーケンスが異なります。
不正検知サービスは、非同期モードの設定により処理のシーケンスが異なります。
いずれの場合も、カード情報のトークン化は本APIの呼び出し前に行ってください。

3Dセキュア認証なし
3Dセキュア認証を利用しない場合、または未対応カードのために3Dセキュア認証とならない場合のシーケンスです。
支払いの結果を即時レスポンスパラメーターで返します。

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor pyr as お客様
participant brw as ブラウザ
participant mer as 加盟店様
participant psp as 決済代行<br>(当サービス)
participant acq as カード会社
pyr->>+brw: 「支払い/カード確認」<br>ボタンクリック
brw->>+mer: 支払い/有効性確認
mer->>+psp: クレカ払い/有効性確認要求<br>charge/verify card
Note right of psp: 3Dセキュア利用なし<br>または未対応カード
psp->>+acq: オーソリ(信用照会)
acq-->>-psp: オーソリ(信用照会)結果
psp-->>-mer: クレカ払い/有効性確認結果
mer-->>-brw: 結果画面
brw-->>-pyr: 「支払い/カード確認」<br>結果表示

3Dセキュア認証・自動オーソリあり
3Dセキュア認証後に、自動でオーソリ(信用照会)をする"autoAuthorization":true場合のシーケンスです。
chargeのレスポンスを受け取った後に3Dセキュア認証に進むために、お客様のブラウザを指定のURLにリダイレクトします。
3Dセキュア認証後は自動でオーソリ(信用照会)が実行され、処理の完了をコールバックします。
支払いの完了状況は、加盟店様コールバック後に取引照会API(/order/inquiry)を呼び出して確認してください。
ブラウザが閉じられるなどのお客様の操作により加盟店様にコールバックされず、状態不整合となる可能性があります。
状態不整合を発生させたくない場合は、以下の「自動オーソリなし」のシーケンスを参照ください。

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor pyr as お客様
participant brw as ブラウザ
participant mer as 加盟店様
participant psp as 決済代行<br>(当サービス)
participant tds as 3Dセキュア<br>サーバー
participant acq as カード会社
pyr->>+brw: 「支払い/カード確認」<br>ボタンクリック
brw->>+mer: 支払い/有効性確認
mer->>+psp: クレカ払い/有効性確認要求<br>charge/verify card
psp->>+tds: 認証初期化
tds-->>-psp: 認証URL
psp-->>-mer: リダイレクト情報
mer->>-brw: 認証開始URLへの<br>リダイレクト
brw->>brw: 
brw->>+psp: 
psp->>-brw: 3DセキュアURLへのリダイレクト
brw->>brw: 
brw->>+tds: 
tds->>-brw: 当サービスのコールバックURLへのリダイレクト
brw->>brw: 
brw->>+psp: 
psp->>+tds: 認証依頼
tds-->>-psp: 認証結果
opt 認証チャレンジが必要な場合
  psp->>-brw: チャレンジ画面へのリダイレクト
  brw->>brw: 
  brw->>+tds: 
  tds-->>-brw: 認証チャレンジ画面
  brw-->>-pyr: 認証画面
  pyr->>+brw: パスワード入力等の認証
  brw->>+tds: 本人認証情報
  tds->>-brw: 当サービスのコールバックURLへのリダイレクト
  brw->>brw: 
  brw->>+psp: 
  psp->>+tds: チャレンジ判定依頼
  tds-->>-psp: チャレンジ結果
end
psp->>-brw: 当サービスのコールバックURLへのリダイレクト
brw->>brw: 
alt 認証失敗、チャレンジ失敗の場合
  brw->>+psp: 
  psp->>-brw: 加盟店様コールバックURLへのリダイレクト
else 認証成功の場合
  brw->>+psp: 
  psp->>+acq: オーソリ(信用照会)
  acq-->>-psp: オーソリ(信用照会)結果
  psp->>-brw: 加盟店様コールバックURLへのリダイレクト
end
brw->>brw: 
brw->>+mer: 
mer->>+psp: 取引照会
psp-->>-mer: 取引結果
mer-->>-brw: 結果画面
brw-->>-pyr: 「支払い/カード確認」<br>結果表示      

3Dセキュア認証・自動オーソリなし
3Dセキュア認証後に、自動でオーソリ(信用照会)をしない"autoAuthorization":false場合のシーケンスです。
chargeのレスポンスを受け取った後に3Dセキュアに進むために、お客様のブラウザを指定のURLにリダイレクトします。
3Dセキュア認証後は認証処理の完了をコールバックします。
この時点でオーソリ(信用照会)は完了していません。
コールバック後は加盟店様にて元の取引を特定し、3Dセキュア後の支払いAPI(/tds2/finalizeCharge)を呼び出すことでオーソリ(信用照会)が行われます。

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor pyr as お客様
participant brw as ブラウザ
participant mer as 加盟店様
participant psp as 決済代行<br>(当サービス)
participant tds as 3Dセキュア<br>サーバー
participant acq as カード会社
pyr->>+brw: 「支払い/カード確認」<br>ボタンクリック
brw->>+mer: 支払い/有効性確認
mer->>+psp: クレカ払い/有効性確認要求<br>charge/verify card
psp->>+tds: 認証初期化
tds-->>-psp: 認証URL
psp-->>-mer: リダイレクト情報
mer->>-brw: 認証開始URLへの<br>リダイレクト
brw->>brw: 
brw->>+psp: 
psp->>-brw: 3DセキュアURLへのリダイレクト
brw->>brw: 
brw->>+tds: 
tds->>-brw: 当サービスのコールバックURLへのリダイレクト
brw->>brw: 
brw->>+psp: 
psp->>+tds: 認証依頼
tds-->>-psp: 認証結果
opt 認証チャレンジが必要な場合
  psp->>-brw: チャレンジ画面へのリダイレクト
  brw->>brw: 
  brw->>+tds: 
  tds-->>-brw: 認証チャレンジ画面
  brw-->>-pyr: 認証画面
  pyr->>+brw: パスワード入力等の認証
  brw->>+tds: 本人認証情報
  tds->>-brw: 当サービスのコールバックURLへのリダイレクト
  brw->>brw: 
  brw->>+psp: 
  psp->>+tds: チャレンジ判定依頼
  tds-->>-psp: チャレンジ結果
end
psp->>-brw: 加盟店様コールバックURLへのリダイレクト
brw->>brw: 
brw->>+mer: 
mer->>+psp: 認証後クレカ払い/有効性確認要求<br>finalize charge/verification
alt 認証失敗、チャレンジ失敗の場合
  psp-->>mer: 3Dセキュア結果
else 認証成功の場合
  psp->>+acq: オーソリ(信用照会)
  acq-->>-psp: オーソリ(信用照会)結果
  psp-->>-mer: 3Dセキュア結果<br>クレカ払い/有効性確認結果
end
mer-->>-brw: 結果画面
brw-->>-pyr: 「支払い/カード確認」<br>結果表示

不正検知・同期モード
不正検知・同期モード"asyncMode":falseの場合のシーケンスです。
不正検知APIの審査結果が返却された後にレスポンスを返します。

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor pyr as お客様
participant brw as ブラウザ
participant mer as 加盟店様
participant psp as 決済代行<br>(当サービス)
participant acq as カード会社
participant frd as 不正防止<br>サービス
pyr->>+brw: 「支払い」<br>ボタンクリック
brw->>+mer: 支払い
mer->>+psp: クレカ払い要求<br>charge
psp->>+acq: オーソリ(信用照会)
acq-->>-psp: オーソリ(信用照会)結果
psp->>+frd: 不正検知API呼び出し
frd-->>-psp: 審査結果返却
psp-->>-mer: クレカ払い結果
mer-->>-brw: 結果画面
brw-->>-pyr: 「支払い」<br>結果表示

不正検知・非同期モード
不正検知・非同期モード"asyncMode":trueの場合のシーケンスです。
不正検知APIの審査結果を待たずにレスポンスを返します。

%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor pyr as お客様
participant brw as ブラウザ
participant mer as 加盟店様
participant psp as 決済代行<br>(当サービス)
participant acq as カード会社
participant frd as 不正検知<br>サービス
pyr->>+brw: 「支払い」<br>ボタンクリック
brw->>+mer: 支払い
mer->>+psp: クレカ払い<br>charge
psp->>+acq: オーソリ(信用照会)
acq-->>-psp: オーソリ(信用照会)結果
psp->>+frd: 不正検知API呼び出し<br>(非同期)
psp-->>-mer: クレカ払い結果
mer-->>-brw: 結果画面
brw-->>-pyr: 「支払い」<br>結果表示
frd-->>-psp: 審査結果返却
mer-->>+psp: 取引照会<br>/order/inquiry
psp-->>-mer: 不正検知結果を含む<br>取引情報を返却

共通パラメーター

merchant order payerは、全ての支払いタイプで共通のパラメーターです。
設定した値は、各決済手段ごとに以下の目的で利用されます。
その決済手段で利用されないパラメーターは「-」で表しており、設定した値は無視されます。

共通パラメーター対応表

merchant

クレジットカード決済 Google Pay Apple Pay ReD Shield
name required
3DS2.0認証画面に表示
- - -
nameKana - - - -
nameAlphabet required
3DS2.0の認証画面に表示
※nameが正しく表示
できない場合
- - -
nameShort - - - -
contactName - - - -
contactEmail - - - -
contactUrl - - - -
contactPhone - - - -
contactOpeningHours - - - -

order

クレジットカード決済 Google Pay Apple Pay ReD Shield
currency - - - 不正審査に利用
items.name - - - 不正審査に利用
items.description - - - 不正審査に利用
items.quantity - - - 不正審査に利用
items.type - - - 不正審査に利用
items.price - - - 不正審査に利用
items.category - - - 不正審査に利用
items.productId - - - 不正審査に利用
items.productCode - - - 不正審査に利用
transactionType - - - -
shippingAddress.name - - - 不正審査に利用
shippingAddress.line1 3DS2.0認証に利用 - - 不正審査に利用
shippingAddress.line2 3DS2.0認証に利用 - - 不正審査に利用
shippingAddress.line3 3DS2.0認証に利用 - - 不正審査に利用
shippingAddress.city 3DS2.0認証に利用 - - -
shippingAddress.state 3DS2.0認証に利用 - - 不正審査に利用
shippingAddress.postCode 3DS2.0認証に利用 - - 不正審査に利用
shippingAddress.country 3DS2.0認証に利用 - - 不正審査に利用
billingAddress.name - - - 不正審査に利用
billingAddress.line1 3DS2.0認証に利用 - - 不正審査に利用
billingAddress.line2 3DS2.0認証に利用 - - 不正審査に利用
billingAddress.line3 3DS2.0認証に利用 - - 不正審査に利用
billingAddress.city 3DS2.0認証に利用 - - -
billingAddress.state 3DS2.0認証に利用 - - 不正審査に利用
billingAddress.postCode 3DS2.0認証に利用 - - 不正審査に利用
billingAddress.country 3DS2.0認証に利用 - - 不正審査に利用

payer

クレジットカード決済 Google Pay Apple Pay ReD Shield
name - - - -
nameKana - - - -
nameAlphabet - - - -
gender - - - 不正審査に利用
dateOfBirth - - - 不正審査に利用
email 3DS2.0認証に利用 - - 不正審査に利用
deliveryEmail 3DS2.0認証に利用 - - -
phones.type 3DS2.0認証に利用 *1 - - -
phones.countryCode 3DS2.0認証に利用 *1 - - -
phones.number 3DS2.0認証に利用 *1 - - 不正審査に利用
accountId - - - -
ip - - - 不正審査に利用
deviceType - - - -
httpUserAgent - - - -

*1 3DS2.0認証で利用するためにはphone.typephone.countryCodephone.numberの3つ全てを設定する必要があります。その場合、phone.typeOTHER以外を設定してください。

都度支払い

カード情報を都度設定して支払う場合に呼び出すAPIです。
Apple Pay、Google Payでのお支払いもこのAPIを利用します。
※ApplePayでは3Dセキュアおよび不正検知のご利用ができません。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

カード情報の設定方法は以下のいずれかです。

  1. トークン化して設定

    • MPクレカトークン
      当サービス標準のカード情報トークンです。
      詳細はカード情報トークン化 開発ガイドを参照ください。

    • Apple Payトークン
      Apple Payに対応した端末で取得したApple PayのPayment tokenをbase64エンコードした値です。
      詳細は「BT01_ApplePay開発ガイド」を参照ください。

    • Google Payトークン
      Google Pay APIで取得したPayment tokenをbase64エンコードした値です。
      当サービスが提供するMpToken.jsを利用してトークンを取得することができます。
      詳細はカード情報トークン化 開発ガイドを参照ください。
      Google Payに関する詳細はデベロッパー向けドキュメントを参照ください。

  2. 直接設定
    PCI DSSの認定を得ている加盟店様のみが利用できます。
    本番環境で利用するためにはお申し込みが必要です。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Order)

取引情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Payer)

購入者情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
トークン化 (object) or 直接 (object) (CreditInformation)
object (Tds2Information)

3Dセキュア情報

object (FraudDetectionInformation)

不正検知情報

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "order": {
    },
  • "payer": {
    },
  • "creditInformation": {
    },
  • "tds2Information": {
    },
  • "fraudDetectionInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "nextAction": "CAPTURE",
  • "orderReference": {
    },
  • "creditResult": {
    },
  • "fraudDetectionResult": {
    }
}

随時支払い

登録されているカード情報を使って支払う場合に呼び出すAPIです。
対応している決済手段はクレジットカード、Apple Payです。
ただしVISAブランドのカード番号が登録されたApple Payはご利用になれません。
また、VISA以外のブランドについても、将来的に利用できなくなる可能性があります。
※ApplePayでは3Dセキュアおよび不正検知のご利用ができません。
Google Payについては、アカウント情報を当サービスに保管できません。
都度支払い時にGoogle Payで使用されたクレジットカード情報を保管することで、通常のクレジットカードとして随時支払いが利用可能です。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

カードのタイプはcreditOnfileInformation.onfileCard.typeで設定します。
プロトコルタイプとは異なりカード登録連番を物理モードで設定できません。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Order)

取引情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Payer)

購入者情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (CreditOnfileInformation)

登録済みクレカ払い情報

object (Tds2Information)

3Dセキュア情報

object (FraudDetectionInformation)

不正検知情報

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "order": {
    },
  • "payer": {
    },
  • "creditOnfileInformation": {
    },
  • "tds2Information": {
    },
  • "fraudDetectionInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "nextAction": "CAPTURE",
  • "orderReference": {
    },
  • "creditResult": {
    },
  • "fraudDetectionResult": {
    }
}

3Dセキュア後の支払い

3Dセキュアに進んだ後に最終的に支払いをするためのAPIです。
Chargeリクエスト時に自動オーソリなしの場合には、コールバック後にこのAPIで支払いを完了してください。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

対象の取引のID

accessId
required
string (AccessId) ^[a-zA-Z0-9]{32}$

3Dセキュアにリダイレクトする前の支払いリクエスト時に返された取引ID

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "nextAction": "CAPTURE",
  • "orderReference": {
    },
  • "creditResult": {
    },
  • "tds2Result": {
    },
  • "fraudDetectionResult": {
    }
}

有効性確認

カード情報の有効性確認をするためのAPIです。
加えて有効性の確認が取れたカード情報を会員に紐づけて登録できます。
利用可能な決済手段はクレジットカード、Google Payであり、Apple Payは利用できません。
Google Payは通常のクレジットカードとして会員に紐づけて登録します。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

カード情報の設定方法は以下のいずれかです。

  1. トークン化して設定

  2. 登録済み情報を設定
    登録されているカード情報を利用します。
    対象の会員IDが必要です。

  3. 直接設定
    PCI DSSの認定を得ている加盟店様のみが利用できます。
    本番環境で利用するためにはお申し込みが必要です。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (OrderWithoutAmount)

取引情報

required
object (Payer)

購入者情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
トークン化 (object) or 登録済み (object) or 直接 (object) (CreditVerificationInformation)
object (Tds2Information)

3Dセキュア情報

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "order": {
    },
  • "payer": {
    },
  • "creditVerificationInformation": {
    },
  • "tds2Information": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "nextAction": "NO_ACTION",
  • "orderReference": {
    },
  • "creditResult": {
    },
  • "onfileCardResult": {
    }
}

3Dセキュア後の有効性確認

3Dセキュア認証に進んだ後に最終的に有効性確認とカード登録をするためのAPIです。
有効性リクエスト時に自動オーソリなしの場合には、コールバック後にこのAPIで処理を完了してください。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

対象の取引のID

accessId
required
string (AccessId) ^[a-zA-Z0-9]{32}$

3Dセキュアにリダイレクトする前の有効性確認リクエスト時に返された取引ID

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "nextAction": "NO_ACTION",
  • "orderReference": {
    },
  • "creditResult": {
    },
  • "onfileCardResult": {
    },
  • "tds2Result": {
    }
}

カード登録

カード情報を会員に紐づけて登録するためのAPIです。
有効性確認(/credit/verifyCard)とは異なり、カード情報の有効性確認をしません
このため、トークンまたは直接設定で登録したカード情報については、随時支払いに失敗する可能があります。
利用可能な決済手段はクレジットカード、Google Payであり、Apple Payは利用できません
ただし、Google Payの場合は、通常のクレジットカードとして会員に紐づけて登録します。

登録したカード情報を利用して、継続課金サービスや一括決済サービスをお使いになる場合は、以下にご注意ください。
トークンまたは直接設定で登録したカード情報は、有効性確認がされていないため、チャージバックやカード会社契約停止のリスクがあります。
必ず有効性確認(/credit/verifyCard)を使用してカード情報を登録してください。
成功した取引情報を使って登録したカード情報は問題ありせん。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

カード情報の設定方法は以下のいずれかです。

  1. 成功した取引を設定
    成功した支払いや有効性確認時に返された取引IDaccessIdを設定することで、該当の取引で利用されたカード情報を登録します。

  2. トークン化して設定

  3. 直接設定
    PCI DSSの認定を得ている加盟店様のみが利用できます。
    本番環境で利用するためにはお申し込みが必要です。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
成功取引 (object) or トークン化 (object) or 直接 (object) (CreditStoringInformation)
object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "creditStoringInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "nextAction": "NO_ACTION",
  • "onfileCardResult": {
    },
  • "cardResult": {
    }
}

カード詳細情報取得

カードの詳細情報を返すためのAPIです。
「クレカトークン」または「会員ID+カードID」から紐づいたカード情報を取得します。
利用可能な決済手段はクレジットカードのみです。
※本APIを利用するには契約が必要です。

Authorizations:
PasswordAccessToken
Request Body schema: application/json
required

カード情報の設定方法は以下のいずれかです。

  1. トークン化して設定

    • MPクレカトークン
      当サービス標準のカード情報トークンです。
      本APIではトークンを利用しても無効化されず、支払いAPIで同じMPクレカトークンを設定できます。
      詳細はカード情報トークン化 開発ガイドを参照ください。
  2. 登録済み情報を設定
    登録されているカード情報を利用します。
    対象の会員IDが必要です。

required
トークン化 (object) or 登録済み (object) (CardInformation)
object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "cardInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "cardDetailResult": {
    }
}

Pay払い

Pay払いで利用するAPIです。

処理シーケンス

「都度支払い」と「随時支払いのための利用承諾」のシーケンス



%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor pyr as お客様
participant brw as ブラウザ
participant mer as 加盟店様
participant psp as 決済代行<br>(当サービス)
participant pcp as Pay払い<br>事業者
pyr->>+brw: 「支払い/利用承諾」<br>ボタンクリック
brw->>+mer: 支払い/利用承諾
mer->>+psp: Pay払い/利用承諾<br>charge/authorize account
psp->>+pcp: 初期化
pcp-->>-psp: リダイレクトURL
psp-->>-mer: リダイレクト情報
mer->>-brw: 開始URLへの<br>リダイレクト
brw->>brw: 
brw->>+psp: 
psp->>-brw: Pay払いURLへのリダイレクト
brw->>brw: 
brw->>+pcp: 
pcp-->>-brw: 認証画面
brw-->>-pyr: 認証画面表示
pyr->>+brw: パスワード入力等の認証
brw->>+pcp: 本人認証情報
pcp->>brw: 当サービスのコールバックURLへのリダイレクト
brw->>brw: 
brw->>+psp: 
psp->>+pcp: 確定
pcp-->>-psp: 結果
psp->>-brw: 加盟店様コールバックURLへのリダイレクト
brw->>brw: 
brw->>+mer: 
mer->>+psp: 取引照会
psp-->>-mer: 取引結果
mer-->>-brw: 結果画面
brw-->>-pyr: 結果表示

「随時支払い」のシーケンス



%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
actor pyr as お客様
participant brw as ブラウザ
participant mer as 加盟店様
participant psp as 決済代行<br>(当サービス)
participant pcp as Pay払い<br>事業者
pyr->>+brw: 「支払い」<br>ボタンクリック
brw->>+mer: 支払い
mer->>+psp: Pay払い<br>on-file charge
psp->>+pcp: 支払い要求
pcp-->>-psp: 支払い結果
psp-->>-mer: 支払い結果
mer-->>-brw: 結果画面
brw-->>-pyr: 結果表示

共通パラメーター

merchant order payerは、全ての支払いタイプで共通のパラメーターです。
設定した値は、各決済手段ごとに以下の目的で利用されます。
その決済手段で利用されないパラメーターは「-」で表しており、設定した値は無視されます。

共通パラメーター対応表

merchant

PayPay d払い 楽天ペイ(オンライン決済)V2 Amazon Pay V2 au PAY(ネット支払い)アプリ方式 メルペイ
name - required
決済画面、レシートメール、
利用明細に表示
- - - -
nameKana - - - - - -
nameAlphabet - - - - - -
nameShort - - - - - -
contactName - required
レシートメール、利用明細に表示
- - - -
contactEmail - required
レシートメール、利用明細に表示
- - - -
contactUrl - レシートメール、利用明細に表示 - - - -
contactPhone - - - - - -
contactOpeningHours - - - - - -

order

PayPay d払い 楽天ペイ(オンライン決済)V2 Amazon Pay V2 au PAY(ネット支払い)アプリ方式 メルペイ
currency - - - - - -
items.name - - 楽天ペイ管理画面に表示 - - required
かんたん出品連携に利用
items.description - - - - - かんたん出品連携に利用
items.quantity - - - - - required
かんたん出品連携に利用
items.type - - - - - -
items.price - - - - - required
かんたん出品連携に利用
items.category - - - - - required
かんたん出品連携に利用
items.productId - - - - - かんたん出品連携に利用
items.productCode - - - - - かんたん出品連携に利用
transactionType - - - - - -
shippingAddress.name - - - (ApbTypePayAndShipの場合のみ) required
決済画面に表示、支払い保証ポリシーの検証に利用
- -
shippingAddress.line1 - - - (ApbTypePayAndShipの場合のみ) required
決済画面に表示、支払い保証ポリシーの検証に利用
- -
shippingAddress.line2 - - - (ApbTypePayAndShipの場合のみ)
決済画面に表示、支払い保証ポリシーの検証に利用
- -
shippingAddress.line3 - - - (ApbTypePayAndShipの場合のみ)
決済画面に表示、支払い保証ポリシーの検証に利用
- -
shippingAddress.city - - - (ApbTypePayAndShipの場合のみ) required
決済画面に表示、支払い保証ポリシーの検証に利用
- -
shippingAddress.state - - - (ApbTypePayAndShipの場合のみ) required
決済画面に表示、支払い保証ポリシーの検証に利用
- -
shippingAddress.postCode - - - (ApbTypePayAndShipの場合のみ) required
決済画面に表示、支払い保証ポリシーの検証に利用
- -
shippingAddress.country - - - (ApbTypePayAndShipの場合のみ) required
決済画面に表示、支払い保証ポリシーの検証に利用
- -
billingAddress.name - - - - - -
billingAddress.line1 - - - - - -
billingAddress.line2 - - - - - -
billingAddress.line3 - - - - - -
billingAddress.city - - - - - -
billingAddress.state - - - - - -
billingAddress.postCode - - - - - -
billingAddress.country - - - - - -

payer

PayPay d払い 楽天ペイ(オンライン決済)V2 Amazon Pay V2 au PAY(ネット支払い)アプリ方式 メルペイ
name - - - - - -
nameKana - - - - - -
nameAlphabet - - - - - -
gender - - - - - -
dateOfBirth - - - - - -
email - - - - - -
deliveryEmail - - - - - -
phones.type - - - - - -
phones.countryCode - - - - - -
phones.number - - - (ApbTypePayAndShipの場合のみ) required
決済画面に表示、支払い保証ポリシーの検証
- -
accountId - - - - - -
ip - - - - - -
deviceType - - - - - -
httpUserAgent - - - - - 流入経路解析に利用

都度支払い

都度のお手続きをしてPay払いで支払う場合に呼び出すAPIです。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

どのPay払いを利用するかはwalletInformation.walletTypeで設定します。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Order)

取引情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Payer)

購入者情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (WalletInformation)

Pay払い(都度)情報

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "order": {
    },
  • "payer": {
    },
  • "walletInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "nextAction": "REDIRECT",
  • "orderReference": {
    },
  • "redirectInformation": {}
}

随時支払い

事前に承認済の認証情報を使ってPay払いで支払う場合に呼び出すAPIです。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

どのPay払いを利用するかはwalletOnfileInformation.onfileWalletで設定します。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Order)

取引情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Payer)

購入者情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (WalletOnfileInformation)

Pay払い(随時)情報

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "order": {
    },
  • "payer": {
    },
  • "walletOnfileInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "nextAction": "CAPTURE",
  • "orderReference": {
    },
  • "walletResult": {
    }
}

利用承諾

随時決済のための利用承諾手続き時に呼び出すAPIです。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

どのPay払いを利用するかはwalletInformation.walletTypeで設定します。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (OrderWithoutAmount)

取引情報

required
object (Payer)

購入者情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (WalletAuthorizationInformation)

Pay払い利用承諾情報

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Callbacks

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "order": {
    },
  • "payer": {
    },
  • "walletAuthorizationInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "nextAction": "REDIRECT",
  • "orderReference": {
    },
  • "redirectInformation": {}
}

購入者情報取得

決済事業者で保持している購入者情報を取得するためのAPIです。
現時点ではAmazon Pay V2のみ利用可能です。

Authorizations:
PasswordAccessToken
Request Body schema: application/json
required
accessId
string (AccessId) ^[a-zA-Z0-9]{32}$

取引リクエスト時に返された取引ID

object (CustomerDataAmazonPay)

Amazon Pay V2専用パラメーター

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "amazonPay": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "buyerId": "amzn1.account.XXXX",
  • "name": "見本 太郎",
  • "email": "taro.mihon@example.com",
  • "remarks": "JCB ****1111 (Amazon Pay)",
  • "shippingInformation": {
    },
  • "billingInformation": {
    }
}

現金払い

現金払いで利用するAPIです。

共通パラメーター

merchant order payerは、全ての支払いタイプで共通のパラメーターです。
設定した値は、各決済手段ごとに以下の目的で利用されます。
その決済手段で利用されないパラメーターは「-」で表しており、設定した値は無視されます。

共通パラメーター対応表

merchant

コンビニ決済 Pay-easy決済 銀行振込(バーチャル口座) 銀行振込(バーチャル口座 あおぞら)
name - - - -
nameKana - - - -
nameAlphabet - - - -
nameShort - - - -
contactName required
Loppi・ファミリーマートのマルチ
コピー機支払い後の受領書に表示
- - -
contactEmail - - - -
contactUrl - - - -
contactPhone required
Loppi・ファミリーマートのマルチ
コピー機支払い後の受領書に表示
- - -
contactOpeningHours required
Loppi・ファミリーマートのマルチ
コピー機支払い後の受領書に表示
- - -

order

コンビニ決済 Pay-easy決済 銀行振込(バーチャル口座) 銀行振込(バーチャル口座 あおぞら)
currency - - - -
items.name - - 振込依頼メールに表示 振込依頼メールに表示
items.description - - - -
items.quantity - - - -
items.type - - - -
items.price - - - -
items.category - - - -
items.productId - - - -
items.productCode - - - -
transactionType - - - -
shippingAddress.name - - - -
shippingAddress.line1 - - - -
shippingAddress.line2 - - - -
shippingAddress.line3 - - - -
shippingAddress.city - - - -
shippingAddress.state - - - -
shippingAddress.postCode - - - -
shippingAddress.country - - - -
billingAddress.name - - - -
billingAddress.line1 - - - -
billingAddress.line2 - - - -
billingAddress.line3 - - - -
billingAddress.city - - - -
billingAddress.state - - - -
billingAddress.postCode - - - -
billingAddress.country - - - -

payer

コンビニ決済 Pay-easy決済 銀行振込(バーチャル口座) 銀行振込(バーチャル口座 あおぞら)
name required
支払い画面、払込票に表示
required
ATM画面、利用明細に表示
required
振込依頼メールに表示
required
振込依頼メールに表示
nameKana - - - -
nameAlphabet - - - -
gender - - - -
dateOfBirth - - - -
email 「コンビニ決済依頼完了のお知らせ」メール送信先 「Pay-easy決済依頼完了のお知らせ」メール送信先 振込依頼メール送信先 振込依頼メール送信先
deliveryEmail - - - -
phones.type - - - -
phones.countryCode - - - -
phones.number required
ファミリーマートのレシートにマスク表示
required
利用明細に表示
- -
accountId - - - -
ip - - - -
deviceType - - - -
httpUserAgent - - - -

支払い番号発行

コンビニ決済や銀行振込などの現金払いでのお支払い時に利用するAPIです。
支払いの結果は、非同期で加盟店様がリクエスト時に設定したWebhook URLにHTTPメソッドPOSTで通知します。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

どの現金払いを利用するかはcashInformation.cashTypeで設定します。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Order)

取引情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (Payer)

購入者情報
決済手段ごとの指定要否や各パラメーターの用途は、本セクション冒頭の「共通パラメーター対応表」を参照してください。

required
object (CashInformation)

現金払い情報

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "merchant": {
    },
  • "order": {
    },
  • "payer": {
    },
  • "cashInformation": {
    },
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "nextAction": "AWAIT",
  • "orderReference": {
    },
  • "cashResult": {
    }
}

取引管理

各種取引管理のAPIです。

確定

決済確定のためのAPIです。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required
accessId
required
string (AccessId) ^[a-zA-Z0-9]{32}$

取引リクエスト時に返された取引ID

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "orderReference": {
    },
  • "creditResult": {
    },
  • "tds2Result": {
    }
}

金額変更

すでに支払い済みの取引の金額を変更します。
決済手段と支払い状態により実行できる処理が異なります。
クレジットカードの場合は、当サービス内部で取消と再オーソリ(信用照会)の処理を実施します。
お客様の信用状態によっては、再オーソリ(信用照会)が失敗する場合があり、その場合は取消は無効となり金額変更APIを呼び出す前の状態に戻ります。
クレジットカードは同じ金額を設定して呼び出すことで、仮売上状態の延長が可能です。

仮売上
の減額
仮売上
の増額
実売上
の減額
実売上
の増額
即時売上
の減額
即時売上
の増額
クレカ払い クレカ
Google Pay
Apple Pay △*1 △*1 △*1 △*1 △*1 △*1
Pay払い PayPay × × × ×
d払い × × △*2 △*2
楽天ペイ(オンライン決済)V2
Amazon Pay V2 × ×
au PAY(ネット支払い)アプリ方式 × ×
メルペイ × × × ×
現金払い コンビニ - - - - - -
Pay-easy - - - - - -
銀行振込 - - - - - -

*1 Visaブランドのカードは増額・減額ができません。
*2 減額した取引に限り、元取引金額までの決済金額の増額ができます。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required
accessId
required
string (AccessId) ^[a-zA-Z0-9]{32}$

取引リクエスト時に返された取引ID

amount
required
string

税送料込の取引金額
決済手段により設定可能な値が異なります。

authorizationMode
string (AuthorizationMode)
Enum: "AUTH" "CAPTURE"

支払い要求のタイプ
クレカ払いの場合は必ず設定してください。
クレカ払い以外は設定しても無視されます。

  • AUTH:仮売上
  • CAPTURE:即時売上
object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "amount": "1000",
  • "authorizationMode": "AUTH",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "orderReference": {
    },
  • "creditResult": {
    }
}

キャンセル

支払いを取り消すためのAPIです。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required
accessId
required
string (AccessId) ^[a-zA-Z0-9]{32}$

取引リクエスト時に返された取引ID

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "orderReference": {
    },
  • "creditResult": {
    }
}

照会

取引を照会するためのAPIです。
accessIdとorderIdのどちらかは必ず設定してください。
accessIdとorderIdの両方を設定した場合は両方に一致する取引情報を返却します。

Authorizations:
PasswordAccessToken
Request Body schema: application/json
required
accessId
string (AccessId) ^[a-zA-Z0-9]{32}$

取引リクエスト時に返された取引ID
オーダーIDを省略する場合、取引IDは必ず設定してください。
取引IDとオーダーIDを設定した場合、組み合わせが一致する取引情報を返します。

orderId
string (OrderId) <= 27 characters ^[-0-9a-zA-Z\-]+$

取引リクエスト時に設定した任意のオーダーID
取引IDを省略する場合、オーダーIDは必ず設定してください。
取引IDとオーダーIDを設定した場合、組み合わせが一致する取引情報を返します。

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "orderId": "order-001",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "orderReference": {
    },
  • "creditResult": {
    },
  • "tds2Result": {
    },
  • "fraudDetectionResult": {
    }
}

会員管理

各種会員管理のAPIです。

ID登録

会員を登録するためのAPIです。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required
memberId
required
string (MemberId) ^[a-zA-Z0-9-@_ . ]{1,60}$

登録する会員のID

memberName
string (MemberName) <= 255 characters

新規登録する会員の名称

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "memberId": "member-001",
  • "memberName": "TARO MIHON",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "memberId": "member-001",
  • "memberName": "TARO MIHON"
}

照会

会員情報を照会するためのAPIです。

Authorizations:
PasswordAccessToken
Request Body schema: application/json
required
memberId
required
string (MemberId) ^[a-zA-Z0-9-@_ . ]{1,60}$

照会したい会員のID

onfileType
string (OnfileType)
Enum: "CARD" "WALLET"

照会したい登録認証情報のタイプ
設定なしの場合は全てのタイプを返します。

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "memberId": "member-001",
  • "onfileType": "CARD",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "memberId": "member-001",
  • "memberName": "TARO MIHON",
  • "onfileCards": [
    ],
  • "onfileWallets": [
    ]
}

全削除

会員情報を削除するためのAPIです。
Pay払いの認証情報も含まれます。
一度削除した会員ID、認証情報は二度と利用できないため、ご注意ください。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required
memberId
required
string (MemberId) ^[a-zA-Z0-9-@_ . ]{1,60}$

会員ID
削除する会員のIDです。

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
{
  • "memberId": "member-001",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
{
  • "memberId": "member-001",
  • "deletedCards": [
    ],
  • "deletedWallets": [
    ]
}

認証情報削除

会員に登録されている情報を削除するためのAPIです。

Authorizations:
PasswordAccessToken
header Parameters
Idempotency-Key
string <uuid> <= 36 characters

冪等キー
UUIDv4に則った書式でリクエスト毎にユニークとなる最大36桁の値。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required
One of
memberId
required
string (MemberId) ^[a-zA-Z0-9-@_ . ]{1,60}$

会員ID
削除するカード情報が登録されている会員のIDです。

onfileType
required
string (OnfileType)
Enum: "CARD" "WALLET"

認証情報タイプ
削除する認証情報タイプとしてクレジットカードCARDを設定してください。

onfileCardType
required
string (OnfileCardType)
Enum: "CREDIT_CARD" "APPLE_PAY"

削除するカードのタイプ

  • CREDIT_CARD:クレジットカード
  • APPLE_PAY:Apple Pay
cardId
required
string (OnfileCardId) ^[0-9]{1,4}$

カードのID 削除するカードのID(物理連番)です。

object (AdditionalOptions)

追加情報
予備項目であり、通常は使用しないでください。
任意のMap(Key:Value)形式で、KeyとValueはともにString型のみ設定可能です。
20個までの要素を設定可能です。

Responses

Request samples

Content type
application/json
Example
{
  • "memberId": "member-001",
  • "onfileType": "CARD",
  • "onfileCardType": "CREDIT_CARD",
  • "cardId": "0",
  • "additionalOptions": { }
}

Response samples

Content type
application/json
Example
{
  • "memberId": "member-001",
  • "deletedCard": {
    }
}

Webhook

加盟店様のサーバーで当サービスから送信するWebhookを受け取るためのAPI仕様です。

現金払い支払い完了通知 Webhook

Request Body schema: application/json

現金払いの支払い完了通知
お客様による支払いが完了したことを通知します。
取引リクエスト時に加盟店様が設定したURLに以下のパラメーターを送信します。
Webhookの詳細についてはWebhook通知を参照ください。

accessId
required
string (AccessId) ^[a-zA-Z0-9]{32}$

取引ID
取引リクエスト時に返された取引IDです。

event
required
string
Value: "CASH_PAID"

Webhookイベントタイプ

  • CASH_PAID:現金払い支払い完了
csrfToken
string

Webhook任意パラメーター
chargeリクエスト時に加盟店様が設定した任意の値です。
CSRF対策のために利用してください。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "event": "CASH_PAID",
  • "csrfToken": "bdb04c5f-42f0-29e2-0979-edae3e7760bf"
}

Amazon Pay V2キャンセル結果通知 Webhook

Request Body schema: application/json

Amazon Pay V2のキャンセル結果通知
Amazon Pay V2のキャンセルリクエストの結果を通知します。
取引リクエスト時に加盟店様が設定したURLに以下のパラメーターを送信します。
Webhookの詳細についてはWebhook通知を参照ください。

accessId
required
string (AccessId) ^[a-zA-Z0-9]{32}$

取引ID
キャンセルリクエスト時に設定した取引IDです。

event
required
string
Enum: "REFUND_SUCCEEDED" "REFUND_FAILED"

Webhookイベントタイプ

  • REFUND_SUCCEEDED:キャンセル成功
  • REFUND_FAILED:キャンセル失敗
csrfToken
string

Webhook任意パラメーター
chargeリクエスト時に加盟店様が設定した任意の値です。
CSRF対策のために利用してください。

Responses

Request samples

Content type
application/json
{
  • "accessId": "acdc7d53f7a78f488d8d0997eff99c6f",
  • "event": "REFUND_SUCCEEDED",
  • "csrfToken": "bdb04c5f-42f0-29e2-0979-edae3e7760bf"
}

よくあるご質問(FAQ)

プロトコルタイプ対応表

従来の接続方式であるプロトコルタイプからOpenAPIタイプへ移行する加盟店様向けの情報です。
各ユースケースに対応するエンドポイント及びその使用方法は以下の通りです。

クレジットカード決済