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

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⼀括処理などはこれまで通りご利⽤になれます。
詳細はプロトコルタイプ/モジュールタイプからの移行を参照ください。

支払い機能

PGマルチペイメントサービスが提供する決済機能を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

本人確認機能

PGマルチペイメントサービスが提供する本人確認機能「Verifyサービス」をOpenAPIタイプでどのように扱うかを説明します。
「Verifyサービス」は、お客様の会員登録時、ログイン認証時、属性情報変更時など任意のタイミングにおいて、多様な認証手段で本人確認ができる機能です。
複数の認証手段を簡易に単一のAPIでまとめて導入することができます。

本人確認の認証手段

利用可能な認証手段は以下の通りです。

認証手段 お客様のデータ 処理の流れ
SMS認証 携帯電話番号 加盟店様サイトからのリクエストを受けると
お客様の携帯電話に認証コード(6桁数値)を送信します。
お客様は当サービスが提供する画面にて認証コードを入力します。
認証成功後は加盟店様サイトが設定したURLに戻ります。

※今後はマイナンバーカードを使った本人確認(マイナIC認証)への対応も予定しています。


導入の流れとテスト

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タイプでは利用しません。
従来の「物理モード」が標準ですが、「論理モード」もサポートします。
カード登録連番 OpenAPIタイプでは従来の「物理登録連番」を「カードID」と表します。
「論理登録連番」は「カードインデックス」として扱います。

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

  • OpenAPIタイプでは、一部の決済手段を除いて従来の「結果通知」はサポートしていません。
    タイムアウトなどのレスポンスを受け取れない場合は、同一の冪等キーを設定してリトライをお願いします。
    詳細についてはWebhook通知、従来の結果通知 概要(マルペイDocs)を参照ください。
    ※マルペイDocsの利用方法はこちら
  • モバイルEdy決済、モバイルSuica決済など、支払い処理に記載のない決済手段は現時点で提供の予定はありません。
  • 金額と税送料は統合しました。税送料は個別に設定できません。
  • 個別の加盟店様向けの特殊機能やオプションパラメーターは利用できません。
  • 同時接続数はプロトコルタイプ/モジュールタイプに適用されている値に準じます。
  • プロトコルタイプ/モジュールタイプで取引登録を行った取引に対してOpenAPIタイプで処理を行った場合、従来の「結果通知」仕様に則り通知がされます。
  • プロトコルタイプ/モジュールタイプのカード登録/更新(SaveCard)では、物理モードで登録連番を指定せずに登録済みのカード番号を指定した場合、同一のカード番号を「新規登録」ではなく「更新」として処理しますが、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でも回数の制限なく利用でき、一定の時間で失効します。
    これにより、万が一アクセストークンが漏洩した場合でも、リスクを最小限に抑えられます。
    本方式を利用する場合、パスワード方式を無効にすることで、セキュリティをさらに強化できます。
    無効化の方法はこちらのFAQページを参照ください。

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

IPアドレス制限

加盟店様が許可した特定の接続元IPアドレスからのみAPIにアクセスできる機能です。
本機能を利用することで、第三者による悪用や不正取引の被害を防止します。
許可されていないIPアドレスからアクセスした場合は、unauthorized_requestエラーになります。
IPアドレスはAPIエンドポイントごとに分けて設定することが可能です。
設定方法はドキュメント一覧(マルペイDocs)の「セキュリティ関連 - 912_OpenAPIタイプ管理画面操作マニュアル」を参照ください。
※マルペイDocsの利用方法はこちら


セッション管理

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

偽装通信への対策

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

パラメーターの設定

フォーマット

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

必須パラメーター

必須パラメーターには、requiredがついています。
設定をしないとmissing_parameterエラーになります。

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

親オブジェクトと必須パラメーターの関係

requiredがついていても、以下の場合は省略可能です。

  • 親オブジェクトのパラメーターにrequiredがついていない
  • 親オブジェクト自体を設定していない

例として、order.shippingAddress.nameは設定必須ですが、親オブジェクトorder.shippingAddress自体を設定しなければエラーにはなりません。
反対に親オブジェクトorder.shippingAddressを設定した場合、order.shippingAddress.nameは必ず設定してください。

決済手段によって必須になるパラメーター

requiredがついてないパラメーターであっても、決済手段によっては設定が必要です。
詳細は各パラメーター説明欄の「決済手段ごとの制限事項」を確認してください。

任意パラメーター

必須ではないパラメーターに値を設定しない場合、以下のいずれの方式でも受け付けます。

  • 値に「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 冪等キー
リクエスト毎にユニークな
最大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の認証は、ショップIDとショップパスワードを使ったパスワード方式で行います。
当APIにリクエスト可能なアクセス元IPアドレスを制限することが可能です。
設定方法はドキュメント一覧(マルペイDocs)の「セキュリティ関連 - 912_OpenAPIタイプ管理画面操作マニュアル」を参照ください。
※マルペイDocsの利用方法はこちら


有効範囲

アクセストークンは有効期間内であれば、いずれの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は冪等性をサポートしており、安全にリトライが可能です。

1回目のリクエストが成功した場合の処理シーケンス
%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
participant mer as 加盟店様
participant psp as 当サービス
mer ->>+ psp: リクエスト 冪等キー'AAA'
Note right of psp: 処理成功
psp--xmer: レスポンス 'OK'
Note left of mer: 通信エラー等により<br>レスポンスの受け取りに失敗
mer ->>+ psp: リクエストのリトライ 冪等キー'AAA'
Note right of psp: 再処理はせずに1回目と同じ<br>レスポンスを返却
psp-->>mer: レスポンス 'OK'

1回目のリクエストが失敗していた場合は、同じ冪等キーでのリトライは冪等にならず再処理されます。
1回目のHTTPステータスコード409429500502エラーであれば、再処理の結果、成功することがあります。
上記以外のエラーは、リトライをしても1回目と同じエラーになる可能性が高いです。

1回目のリクエストが失敗した場合の処理シーケンス
%%{
 init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#f0f2f5',
    'primaryTextColor': '#001C40',
    'noteBkgColor': '#d9f4fc',
    'noteTextColor': '#001C40',
    'noteBorderColor': '#54C5E8'
  }
 }
}%%
sequenceDiagram
participant mer as 加盟店様
participant psp as 当サービス
mer ->>+ psp: リクエスト 冪等キー'BBB'
Note right of psp: 処理失敗
psp--xmer: レスポンス 'ERROR'
Note left of mer: 通信エラー等により<br>レスポンスの受け取りに失敗
mer ->>+ psp: リクエストのリトライ 冪等キー'BBB'
Note right of psp: 1回目が失敗しているため再処理
psp-->>mer: レスポンス 'OK'<br>※必ず成功するわけではありません

冪等性をサポートするAPI

主に更新処理を伴うAPIが冪等性をサポートします。
対象となるAPIは、詳細仕様のHEADER PARAMETERSに、Idempotency-Keyが定義されています。


利用方法

冪等にするためには、リクエストのHTTPヘッダーに冪等キーを設定します。
冪等キーには、リクエスト毎にユニークな最大36桁の任意の文字列を割り当ててください。
ランダムにユニークな値を生成するUUID v4の利用を推奨します。
以下はHTTPリクエストヘッダーの設定例です。

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

有効範囲

リクエストの開始から24時間以内は冪等性が有効です。
有効期限が切れた冪等キーは、新規のリクエストとして扱われます。


同時接続数の制限

全ての加盟店様が安定して当サービスを利用できるよう、APIの同時接続数には上限があります。
同時接続数はショップIDかつAPIエンドポイントごとに管理され、上限値を超えたリクエストはtoo_many_requestsエラーになります。


同時接続数の数え方

以下の期間を接続状態として、接続数1と数えます。

  • 開始:加盟店様サーバーからのAPIリクエストが当サービスに到達
  • 終了:処理が完了して当サービスからレスポンスを送信

一定時間内のリクエスト数を制限するAPIレート制限とは異なり、当サービス内の処理実行時間によって、1秒あたりにリクエストできる数が変わります。
例えば、同時接続数の上限値が5で、1リクエストの処理実行時間が0.1秒の場合、1秒間に最大50件のリクエストを送信できます。
1リクエストの処理実行時間が5秒の場合は、1~5秒の間は最大5件のリクエストしか送信できません。


同時接続数の上限値

上限値はAPIエンドポイントごとに決められており、各環境での値は以下の通りです。
実際の値はショップ管理画面から確認ができます。
確認方法はドキュメント一覧(マルペイDocs)の「セキュリティ関連 - 912_OpenAPIタイプ管理画面操作マニュアル」を参照ください。
※マルペイDocsの利用方法はこちら

APIの分類 エンドポイント 同時接続数の上限値
本番環境 テスト環境
認証API アクセストークン /token 5 5
支払いAPI クレカ払い /credit/charge 5 5
/credit/on-file/charge 5 5
/tds2/finalizeCharge 5 5
/credit/verifyCard 5 5
/tds2/finalizeVerification 5 5
/credit/storeCard 5 5
/credit/getCardDetails 5 5
Pay払い /wallet/charge 5 5
/wallet/on-file/charge 5 5
/wallet/authorizeAccount 5 5
/wallet/getCustomerData 5 5
現金払い /cash/charge 5 5
取引管理 /order/capture 10 10
/order/update 10 10
/order/cancel 10 10
/order/inquiry 10 10
会員管理 /member/create 5 5
/member/inquiry 5 5
/member/delete 5 5
/member/deleteItem 5 5
本人確認API 本人確認 /verification/start 5 5
/verification/inquiry 5 5

上限値を増やす場合

上記の上限値を超えてリクエストを行いたい場合、営業担当もしくはカスタマーサポートへご連絡ください。
代理店を通した契約の店子様は、代理店へご相談ください。


テスト環境での負荷テスト

テスト環境での負荷テストは実施しないでください。
負荷テストにより当サービスに影響が出た場合、予告なく利用を制限します。


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

リダイレクト

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払いの利用承諾にて返します。取引照会にて状態を確認し決済成否を判断してください。
VERIFICATION_FINISHED
本人確認の認証開始にて返します。照会にて状態を確認し認証成否を判断してください。
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にHTTPで送信されます。
加盟店様のシステムで通知を受け取れるようWebhookエンドポイントをご用意ください。

通知の対象

通知対象の処理は以下です。
通常は数秒から2時間程度以内に通知します。
通知内容は各リンク先を参照ください。


通知APIの仕様

Webhook通知APIの接続仕様です。

項目 仕様
HTTPメソッド POST
HTTPリクエストヘッダーの
Content-Type
application/json
リクエストボディー JSON形式

以下のIPアドレスから送信されます。
加盟店様システムにて接続制限をしている場合は、許可設定をお願いします。

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

受信する加盟店様システムのSSLサーバー証明書によっては通信エラーになる可能性があります。
動作確認済みのSSLサーバー証明書は結果通知 SSL証明書(マルペイDocs)を参照ください。
※マルペイDocsの利用方法はこちら

通知への応答

Webhookを受信して正常に処理をした後は、HTTPステータス200番台を返してください。
レスポンスのボディは不要です。
200番台以外が返された場合は通知失敗と扱われ、リトライの対象になります。
リトライは一定間隔で正常応答をするまで最大5回送信されます。
間隔の初期設定は60分で、後述のとおり変更できます。

通知の設定

Webhookの通知を受けるためには、APIリクエスト時に加盟店様のWebhook URLをパラメーターmerchant.webhookUrlに設定します。
従来の「結果通知」とは異なり、事前にショップ管理画面から有効化する必要はありません。

ショップ管理画面にて以下の設定を変更可能です。

  • リトライ間隔: デフォルト60分である通知失敗時のリトライ間隔を変更
  • 結果通知停止時間: 加盟店様システムのメンテナンスにより結果通知を受け取れない時間帯を設定し、終了時刻後にまとめて通知

変更の方法は結果通知 管理画面操作マニュアル(マルペイDocs)を参照ください。
※マルペイDocsの利用方法はこちら
「基本設定」、「SNI設定」など、上記以外の設定はOpenAPIタイプのWebhookには適用されません。

環境と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 サービス利用不可 当サービスがメンテナンス中のため、リクエストは受け付けられません。
このコードを返すメンテナンス情報は、6ヶ月前に加盟店様に通知します。

エラーの情報

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 認証情報が正しくないか、許可されないIPアドレスのため、リクエストは受け付けられません。 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です。
認証の詳細は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

テストカード番号

テスト環境で利用可能なカード番号は、テストカード一覧(マルペイDocs)を参照ください。
※マルペイDocsの利用方法はこちら
上記ページの「正常カード扱いテスト手順」は、OpenAPIタイプでも利用可能です。

仮売上と確定

「仮売上」については、こちらの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>or<br>カード登録
brw->>+mer: 支払い<br>or<br>カード登録
mer->>+psp: /charge<br>or<br>/verifyCard<br>リクエスト
Note right of psp: 3Dセキュア利用なし<br>または未対応カード
psp->>+acq: オーソリ(信用照会)
acq-->>-psp: オーソリ結果
psp-->>-mer: /charge<br>or<br>/verifyCard<br>結果
mer-->>-brw: 結果画面
brw-->>-pyr: 結果表示

3Dセキュア認証・自動オーソリあり
3Dセキュア認証後に、自動でオーソリ(信用照会)をする"autoAuthorization":true場合のシーケンスです。
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>or<br>カード登録
brw->>+mer: 支払い<br>or<br>カード登録
mer->>+psp: /charge<br>or<br>/verifyCard<br>リクエスト
psp->>+tds: 認証初期化
tds-->>-psp: 認証URL
psp-->>-mer: リダイレクト<br>情報
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: /order/inquiry<br>リクエスト
psp-->>-mer: /order/inquiry<br>結果
mer-->>-brw: 結果画面
brw-->>-pyr: 結果表示      

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

%%{
 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>or<br>カード登録
brw->>+mer: 支払い<br>or<br>カード登録
mer->>+psp: /charge<br>or<br>/verifyCard<br>リクエスト
psp->>+tds: 認証初期化
tds-->>-psp: 認証URL
psp-->>-mer: リダイレクト<br>情報
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: /finalizeCharge<br>or<br>/finalizeVerification<br>リクエスト
alt 認証失敗、チャレンジ失敗の場合
  psp-->>mer: 3Dセキュア結果
else 認証成功の場合
  psp->>+acq: オーソリ(信用照会)
  acq-->>-psp: オーソリ結果
  psp-->>-mer: /finalizeCharge<br>or<br>/finalizeVerification<br>結果
end
mer-->>-brw: 結果画面
brw-->>-pyr: 結果表示

不正検知・同期モード
不正検知・同期モード"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: 支払い
brw->>+mer: 支払い
mer->>+psp: /charge<br>リクエスト
psp->>+acq: オーソリ(信用照会)
acq-->>-psp: オーソリ結果
psp->>+frd: 不正検知リクエスト
frd-->>-psp: 審査結果
psp-->>-mer: /charge<br>結果
mer-->>-brw: 結果画面
brw-->>-pyr: 結果表示

不正検知・非同期モード
不正検知・非同期モード"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: 支払い
brw->>+mer: 支払い
mer->>+psp: /charge<br>リクエスト
psp->>+acq: オーソリ(信用照会)
acq-->>-psp: オーソリ結果
psp->>+frd: 不正検知リクエスト<br>(非同期)
psp-->>-mer: /charge<br>結果
mer-->>-brw: 結果画面
brw-->>-pyr: 結果表示
frd-->>-psp: 審査結果
mer-->>+psp: /order/inquiry<br>リクエスト
psp-->>-mer: /order/inquiry<br>結果<br>不正検知結果を含む

都度支払い

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

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

冪等キー
リクエスト毎にユニークな最大36桁の任意の文字列。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

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

  1. トークン化して設定

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

    • Apple Payトークン
      Apple Payに対応した端末で取得したApple PayのPayment tokenをbase64エンコードした値です。
      詳細はBT01_ApplePay開発ガイドを参照ください。
      ※マルペイDocsの利用方法はこちら

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

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

3Dセキュア認証利用時には、以下のカード会員の情報を必ず設定してください。
未設定でもエラーにはなりませんが、変更になる可能性があります。

  • カード会員の名前
    • トークン化して設定
      MPクレカトークンの「カード名義人」が利用されます。
    • 直接設定
      creditInformation.card.cardholderNameが利用されます。
  • カード会員のメールアドレスまたは電話番号
    payerに設定した値が利用されます。
    詳細は共通パラメーター対応表 - クレカ払いを参照ください。
required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

name
required
string <= 30 characters

表示用の加盟店様名
設定できる最大長はUTF-8で45byteです。

nameKana
required
string^[ァ-ヶー ]+$

表示用の加盟店様名(全角カナのみ)
設定できる最大長はUTF-8で60byteです。

nameAlphabet
required
string <= 25 characters ^[a-zA-Z0-9 \x2c-\x2f]+$

表示用の加盟店様名(英名)

nameShort
required
string <= 30 characters

表示用の加盟店様名(略称)
設定できる最大長はUTF-8で45byteです。

contactName
required
string <= 42 characters

加盟店様の問い合わせ先名称
設定できる最大長はUTF-8で63byteです。

contactEmail
required
string <email> <= 254 characters

加盟店様の問い合わせ先メールアドレス
RFC 5322の仕様に沿った形式のみ許可されます。

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactUrl
string <uri> <= 256 characters

加盟店様の問い合わせ先ページURL

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactPhone
required
string <= 13 characters ^[0-9-]+$

加盟店様の問い合わせ先電話番号

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactOpeningHours
required
string <= 11 characters ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]-([0-1]?[0-9]...

加盟店様の問い合わせ窓口の営業時間(HH:MM-HH:MM形式)

callbackUrl
string <uri> <= 256 characters

コールバックURL
リダイレクトが発生するリクエスト時は必ず設定してください。
リダイレクト後に加盟店様のサーバーに処理の遷移を戻すためのURLです。
詳細はリダイレクトとコールバックを参照ください。

webhookUrl
string <uri> <= 256 characters

Webhook URL
現金払いの支払いなど、処理が非同期で行われた場合に、その結果を通知するための加盟店様側のURLです。
httpsから始まるURLを設定してください。
※テスト環境ではhttpの指定が可能です。
詳細はWebhookを参照ください。

csrfToken
string <= 36 characters ^[0-9a-zA-Z-]+$

CSRFトークン
コールバックやWebhookの呼び出し時につける任意のパラメーターです。
CSRF対策のために利用してください。
詳細はリダイレクトとコールバックを参照ください。

required
object (Order)

取引情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

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

この取引に対する任意のオーダーID
加盟店様にてユニークな値を発行してください。

amount
required
string <= 15 characters

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

currency
string^[A-Z]{3}$
Default: "JPY"

通貨コード
ISO 4217のアルファベット3文字を設定します。
例えば日本円の場合JPYです。
省略時はJPYです。
※現時点ではJPYのみ利用可能です。

object (ClientFields)

加盟店自由項目

clientField1
string <= 100 characters

加盟店自由項目1
この取引に関する任意情報を紐づけます。
決済の情報としては利用されません。
またお客様には表示されません。
照会API、管理画面、取引配信ファイルで値を確認できます。
設定できる最大長はEUC-JPで100byteです。

clientField2
string <= 100 characters

加盟店自由項目2
「加盟店自由項目1」の説明を参照ください。
最大長はEUC-JPで100byteです。

clientField3
string <= 100 characters

加盟店自由項目3
「加盟店自由項目1」の説明を参照ください。
設定できる最大長はEUC-JPで100byteです。

Array of objects (Item)

商品情報の一覧

Array
name
required
string <= 128 characters

商品の名称
設定できる最大長はUTF-8で192byteです。

description
string <= 120 characters

商品の説明
設定できる最大長はUTF-8で180byteです。

quantity
required
integer <= 9999

商品の購入数

type
required
string
Enum: "DIGITAL" "PHYSICAL" "SERVICE"

商品のタイプ

  • DIGITAL:デジコン
  • PHYSICAL:物販
  • SERVICE:役務
price
required
string <= 15 characters

商品の単価
order.amount以下の値を設定してください。

決済手段ごとの制限事項

  • クレジットカード(ReD Shield利用時): <= 12 characters
  • メルペイ: <= 7 characters
category
string^[0-9]{4}$

商品のMerchant category code(MCC)
MCCはISO 18245で定められた加盟店様の業種カテゴリです。
一般的には加盟店様の業種カテゴリと商品のカテゴリは同じですが、この商品により適したものがあれば個別に設定できます。

決済手段ごとの制限事項

  • メルペイ: required
productId
string <= 30 characters

商品の識別番号
加盟店様が商品ごとに一意に採番した番号です。
半角のみ設定可能です。

決済手段ごとの制限事項

  • クレジットカード(ReD Shield利用時): <= 18 characters
productCode
string <= 13 characters

商品の識別コード
JANコードUPCコードを設定します。 半角のみ設定可能です。

transactionType
required
string (TransactionType)
Enum: "CIT" "MIT" "OTHER"

取引タイプ
この取引がお客様操作によって開始されたか、自動チャージのように加盟店様操作で行われたかを示します。
現時点では設定する値によって当サービス内の処理は変わりません。

  • CIT: Customer Initiated Transaction(お客様操作起点)
  • MIT: Merchant Initiated Transaction(加盟店様操作起点)
  • OTHER: 上記以外
object (Address)

配送先住所情報

name
required
string <= 40 characters

住所の宛名
設定できる最大長はUTF-8で60byteです。

line1
required
string <= 50 characters

住所の町域・丁目番地
設定できる最大長はUTF-8で75byteです。

line2
string <= 50 characters

住所の建物・号室
設定できる最大長はUTF-8で75byteです。

line3
string <= 50 characters

住所情報に関する予備項目
設定できる最大長はUTF-8で75byteです。

city
required
string <= 50 characters

住所の市区町村
「渋谷区」「横浜市」などの市区町村名です。
日本語・漢字でなくても構いません。
設定できる最大長はUTF-8で75byteです。

state
required
string^[0-9]{3}$

住所の都道府県番号
都道府県コード表を参照ください。
日本の場合は「001」から「047」からなる先頭ゼロ埋め3桁の形式です。

postCode
required
string <= 16 characters ^[0-9-]+$

住所の郵便番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード ReD Shield: <= 9 characters
country
string^[0-9]{3}$

住所の国番号
ISO3166-1の数字3桁を設定します。
ITU-E.164ではないのでご注意ください。例えば日本の場合「392」です。

addressMatch
boolean
Default: false

配送先住所と請求先住所が同じ場合はtrueを設定します。
住所はいずれかのみ設定してください。

object (Address)

請求先住所情報

name
required
string <= 40 characters

住所の宛名
設定できる最大長はUTF-8で60byteです。

line1
required
string <= 50 characters

住所の町域・丁目番地
設定できる最大長はUTF-8で75byteです。

line2
string <= 50 characters

住所の建物・号室
設定できる最大長はUTF-8で75byteです。

line3
string <= 50 characters

住所情報に関する予備項目
設定できる最大長はUTF-8で75byteです。

city
required
string <= 50 characters

住所の市区町村
「渋谷区」「横浜市」などの市区町村名です。
日本語・漢字でなくても構いません。
設定できる最大長はUTF-8で75byteです。

state
required
string^[0-9]{3}$

住所の都道府県番号
都道府県コード表を参照ください。
日本の場合は「001」から「047」からなる先頭ゼロ埋め3桁の形式です。

postCode
required
string <= 16 characters ^[0-9-]+$

住所の郵便番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード ReD Shield: <= 9 characters
country
string^[0-9]{3}$

住所の国番号
ISO3166-1の数字3桁を設定します。
ITU-E.164ではないのでご注意ください。例えば日本の場合「392」です。

required
object (Payer)

購入者情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

name
required
string <= 40 characters

購入者の氏名(フルネーム)
設定できる最大長はUTF-8で60byteです。

nameKana
string^[ァ-ヶー ]+$

購入者の氏名(全角カナのみ)
設定できる最大長はUTF-8で60byteです。

決済手段ごとの制限事項

  • コンビニ: required
  • Pay-easy: required
nameAlphabet
string <= 30 characters ^[a-zA-Z0-9 \x2c-\x2f]+$

購入者の氏名(英名)

gender
string
Enum: "MALE" "FEMALE" "OTHER"

購入者の性別

dateOfBirth
string

購入者の誕生日
YYYYMMDD形式

email
string <email> <= 254 characters

購入者のメールアドレス
RFC 5322の仕様に沿った形式のみ許可されます。

deliveryEmail
string <email> <= 254 characters

取引内容がWebチケットなどの電子デリバリーの場合、配信先のメールアドレスを設定します。
RFC 5322の仕様に沿った形式のみ許可されます。

Array of objects (Phone)

購入者の電話情報一覧

Array
type
string
Enum: "MOBILE" "HOME" "WORK" "OTHER"

電話のタイプ
携帯、家、職場、その他から選択します。

  • MOBILE:携帯電話
  • HOME:固定電話
  • WORK:勤務先
  • OTHER:その他

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): requiredOTHER以外
countryCode
string^[0-9]{1,3}$

電話の国コード
ITU-E.164の1~3桁の数字を設定します。
ISO3166-1ではないのでご注意ください。
プラス記号(+)はつけないでください。
例として日本の場合は「81」です。

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): required
number
string <= 13 characters ^[0-9-]+$

電話番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): required
  • コンビニ: required
  • Pay-easy: required
accountId
string <= 60 characters ^[a-zA-Z0-9@_.-]{1,60}$

加盟店様サイト上における購入者のアカウントIDなど、一意に識別するためのID

ip
string <= 39 characters

購入者の発信元IPアドレス

deviceType
string
Enum: "PC_WEB" "PC_APP" "MOBILE_WEB"

購入者のデバイス情報をWeb、アプリから選択

  • PC_WEB:PC(Web)
  • PC_APP:PC(アプリ)
  • MOBILE_WEB:モバイル(Web)
httpUserAgent
string <= 512 characters

購入者のブラウザのUserAgent
半角英数字記号が設定可能です。

required
トークン化して設定 (object) or 直接設定 (object) (CreditInformation)
One of
required
object (TokenizedCard)

トークン化されたカード情報

type
required
string
Enum: "MP_TOKEN" "APPLE_PAY_TOKEN" "GOOGLE_PAY_TOKEN"

カード情報トークンのタイプ
カード情報トークンtokenと合わせて設定してください。

  • MP_TOKEN: MPクレカトークン
  • APPLE_PAY_TOKEN: Apple Payトークン
  • GOOGLE_PAY_TOKEN: Google Payトークン
token
required
string

カード情報トークン
カード情報トークンのタイプtypeと合わせて設定してください。

  • MPクレカトークン
    カード情報をトークン化した値です。

  • Apple Payトークン
    Apple Payに対応した端末で取得したApple PayのPayment tokenをbase64エンコードした値です。

  • Google Payトークン
    Google Pay APIで取得したPayment tokenをbase64エンコードした値です。


カード情報トークンとカード情報を両方設定した場合は以下の通りです。

  • PCI DSSの認定を得ている加盟店様
    カード情報トークンが優先的に利用されます。
  • PCI DSSの認定を得ていない加盟店様
    契約不備のエラーになります。
required
object (CreditChargeOptions)

クレカ払いオプション情報

authorizationMode
required
string
Default: "AUTH"
Enum: "AUTH" "CAPTURE"

支払い要求のタイプ

  • AUTH:仮売上
  • CAPTURE:即時売上
useTds2
boolean
Default: true

3Dセキュア認証の利用有無

  • true: 3Dセキュア認証を利用します。
  • false: 3Dセキュア認証を利用しません。この取引が不正利用によりチャージバックとなった場合、加盟店様が支払いの責任を負う可能性があります。 Apple Payは利用できません。
useFraudDetection
boolean
Default: false

不正検知の利用有無
Apple Payは利用できません。

itemCode
string (ItemCode) ^0000[0-9]{3}$

商品番号
加盟店様とカード会社との契約で定められた場合のみ設定します。
省略時はデフォルトで「0000990」が設定されます。

paymentMethod
string
Default: "ONE_TIME"
Enum: "ONE_TIME" "INSTALLMENT" "BONUS_ONE_TIME" "REVOLVING"

支払方法
Apple Payは一括払い固定になります。

  • ONE_TIME:一括
  • INSTALLMENT:分割
  • BONUS_ONE_TIME:ボーナス一括
  • REVOLVING:リボ
installments
string^[0-9]{1,2}$

分割回数
支払方法が分割の場合に設定します。
設定可能な分割回数は契約により異なります。

object (Tds2Information)

3Dセキュア情報

object (Tds2Options)

3Dセキュアオプション情報

skipNotEnrolledCard
boolean
Default: false

未対応時の認証スキップ
仕向先カード会社が3Dセキュア認証に未対応の場合、エラーにするか、認証をスキップしてオーソリ(信用照会)するかを選択します。

  • false: リクエストはエラーになります。
  • true: 3Dセキュア認証をスキップしてオーソリ(信用照会)します。この取引が不正利用によりチャージバックとなった場合、加盟店様が支払いの責任を負う可能性があります。
allowAttempt
string
Default: "FOLLOW"
Enum: "FOLLOW" "ALLOW" "NOT_ALLOW"

認証結果Attempt時の挙動
3Dセキュア認証の結果、カード会社からECI 06(Mastercard以外)または01(Mastercard)が返された場合の処理を選択します。
ECI06/01は、カード発行会社が3Dセキュアに対応していない場合やサーバー障害などの時に、認証プロセス自体はできていませんが認証成功と扱うことを意味します。
通常、この取引が不正利用によりチャージバックとなった場合、支払いの責任はカード発行会社となり加盟店様には請求されません。
それでもECI06/01の支払いを受け付けたくない場合は、NOT_ALLOWを設定してください。
FOLLOWを設定した場合、3Dセキュア必須化の契約に従います。

  • FOLLOW:ショップ契約の「3Dセキュア必須化」の内容に従う
  • ALLOW:認証成功と扱う
  • NOT_ALLOW:認証失敗と扱う
requiresChallenge
boolean
Default: false

認証チャレンジ必須
リスク判定の結果によらず3Dセキュア認証チャレンジを要求する場合にtrueを設定します。
ただし、カード発行会社が対応していない場合があります。

autoAuthorization
boolean
Default: true

自動オーソリ有無
3Dセキュア認証後に自動でオーソリ(信用照会)をせずに、加盟店様から明示的に3Dセキュア後APIを呼び出してオーソリを実施したい場合にはfalseを設定します。
「自動オーソリあり」の場合、オーソリが実行されてもお客様がブラウザを閉じる、通信エラーが発生するなどして処理が中断し、貴社にコールバックがされず状態不整合になる可能性があります。
「自動オーソリなし」は、オーソリのリクエストを加盟店様にて制御できるため上記のリスクを低減できます。

object (Tds2Data)

3Dセキュアデータ情報

chAccChange
string

カード会員情報の最終更新日
YYYYMMDD形式

chAccDate
string

カード会員の作成日
YYYYMMDD形式

chAccPwChange
string

カード会員のパスワード変更日
YYYYMMDD形式

nbPurchaseAccount
number <= 9999

過去6ヶ月間にこのカード会員が購入した回数

paymentAccAge
string

カード登録日
カード会員にカード情報が登録された日付を設定します。
YYYYMMDD形式

provisionAttemptsDay
number <= 999

過去24時間に行われたカード情報追加の試行回数

shipAddressUsage
string

配送先住所の初回使用日
取引で使用される配送先住所が加盟店様で最初に使用された日付を設定します。
YYYYMMDD形式

shipNameInd
string^(01|02)$

カード会員名と配送先名の一致/不一致
カード会員の会員名と取引に使用される配送先名の一致/不一致を設定します。

  • 01: カード会員名と配送先名が一致
  • 02: カード会員名と配送先名が不一致
suspiciousAccActivity
string^(01|02)$

カード会員の不審行為情報
カード会員で、不審な行動(過去の不正行為を含む)を加盟店様が発見したかどうかを設定します。

  • 01: 不審な行動は見られなかった
  • 02: 不審な行動が見られた
txnActivityDay
number <= 999

過去24時間の取引回数
過去24時間に行われた、カード会員と加盟店様との取引の回数を設定します。

txnActivityYear
number <= 999

前年の取引回数
前年に行われた、カード会員と加盟店様との取引の回数を設定します。

threeDSReqAuthData
string <= 2048 characters

ログイン証跡
カード会員が特定の方法でログインしたことを裏付けるデータを設定します。
設定できる最大長はUTF-8で2048byteです。

threeDSReqAuthMethod
string^(01|02|03|04|05|06)$

ログイン方法
カード会員の加盟店様システムへのログイン方法を設定します。

  • 01: 認証なし(ゲストとしてログイン)
  • 02: 加盟店様自身の認証情報
  • 03: SSO(シングルサインオン)
  • 04: イシュアーの認証情報
  • 05: サードパーティ認証
  • 06: FIDO認証
threeDSReqAuthTimestamp
string

ログイン日時
カード会員のログイン日時を設定します。
YYYYMMDDHHMM形式

deliveryTimeframe
string^(01|02|03|04)$

商品納品時間枠

  • 01: 電子デリバリー
  • 02: 当日出荷
  • 03: 翌日出荷
  • 04: 2日目以降の出荷
giftCardAmount
number <= 999999999999999

プリペイドカードまたはギフトカードを購入の場合、総購入金額の値を設定します。

giftCardCount
number <= 99

プリペイドカードまたはギフトカードを購入の場合、購入された総数を設定します。

giftCardCurr
string^[0-9]{3}$

購入されたプリペイドカードまたはギフトカードの通貨コード
プリペイドカードまたはギフトカードを購入の場合、カードの通貨を表す、ISO 4217で定義されている通貨コードを設定します。
※以下のコードは対象外です。
955, 956, 957, 958, 959, 960, 961, 962, 963, 964, 999

preOrderDate
string

商品の発売予定日
先行予約購入の場合は、商品の発売予定日を設定します。
YYYYMMDD形式

preOrderPurchaseInd
string^(01|02)$

商品の販売時期情報
先行予約購入か、発売済み商品の購入かを設定します。

  • 01: 発売済み商品
  • 02: 先行予約商品
reorderItemsInd
string^(01|02)$

商品の注文情報
カード会員が以前購入した商品を再び注文しているかどうかを設定します。

  • 01: 初回注文
  • 02: 再注文
shipInd
string^(01|02|03|04|05|06|07)$

取引の配送方法

  • 01: カード会員の請求先住所に配送する
  • 02: 加盟店様が保持している別の、確認済み住所に配送する
  • 03: カード会員の請求先住所と異なる住所に配送する
  • 04: 店舗へ配送 / 近所の店舗での受け取り(店舗の住所は配送先住所で設定する)
  • 05: デジタル商品(オンラインサービス、電子ギフトカードおよび償還コードを含む)
  • 06: 配送なし(旅行およびイベントのチケット)
  • 07: その他(ゲーム、配送されないデジタルサービス、電子メディアの購読料など)
object (FraudDetectionInformation)

不正検知情報

required
object (FraudDetectionOptions)

不正検知オプション情報

screeningType
required
string
Value: "RED_SHIELD"

審査タイプ

stopAuthorizationThreshold
string^DENY|CHALLENGE$

オーソリ中断閾値
当パラメーターを設定した場合はオーソリ(信用照会)前に不正審査を実施し、審査結果が設定した閾値以上である場合はオーソリ(信用照会)を中断します。
例) CHALLENGEを設定した場合、審査結果がCHALLENGEまたはDENYの際はオーソリを中断します。

asyncMode
boolean
Default: false

非同期モード
trueを設定した場合は不正審査を非同期で実行します。 この際レスポンスに審査結果は含まれませんので、任意のタイミングで取引照会API(/order/inquiry)を実行し取得してください。

required
object (FraudDetectionData)

不正検知データ情報

userId
required
string <= 60 characters ^[a-zA-Z0-9@_.-]+$

ユーザーID

identityDocType
string
Enum: "PASSPORT" "TAXSTATEMENT"

本人確認書類タイプ
本人確認書類IDに設定する書類タイプを設定します。
本人確認書類IDを設定する場合は省略できません。

  • PASSPORT:パスポート
  • TAXSTATEMENT:納税証明書
identityDocId
string <= 20 characters ^[0-9a-zA-Z-]+$

本人確認書類ID
設定する場合は本人確認書類タイプも設定する必要があります。

shippingCorporationName
string <= 60 characters

配送先会社名

shippingPhone
string <= 13 characters ^[0-9-]+$

配送先電話番号

shippingEmail
string <email> <= 254 characters

配送先メールアドレス

shippingMethod
string
Enum: "NEXT_DAY_OVERNIGHT" "TWO_DAY_SERVICE" "THREE_DAY_SERVICE" "LOWEST_COST" "CARRIER_DESIGNATED_BY_CUSTOMER" "ELECTRONIC_DELIVERY" "GROUND" "INTERNATIONAL" "MILITARY" "STORE_PICKUP" "SAME_DAY_SERVICE" "OTHER" "PUDO" "EXPEDITED"

配送方法

  • NEXT_DAY_OVERNIGHT: 翌日発送
  • TWO_DAY_SERVICE: 2日以内発送
  • THREE_DAY_SERVICE: 3日以内発送
  • LOWEST_COST: 最安値の配送方法
  • CARRIER_DESIGNATED_BY_CUSTOMER: お客様指定の運送会社
  • ELECTRONIC_DELIVERY: 電子郵便
  • GROUND: 陸上輸送
  • INTERNATIONAL: 国際郵便
  • MILITARY: 軍事郵便
  • STORE_PICKUP: 店舗受け取り
  • SAME_DAY_SERVICE: 即日配送
  • OTHER: その他
  • PUDO: PUDOステーション
  • EXPEDITED: 速達郵便
shippingAmount
string <= 15 characters ^[0-9]+$

送料
審査タイプ(screeningType)がRED_SHIELDの場合、12桁以下で設定してください。

shippingTrackingNumber
string <= 19 characters ^[0-9a-zA-Z-]+$

トラッキング番号

shippingComment
string <= 160 characters

発送時コメント

shippingSalutation
string <= 5 characters ^[ -~。-゚]+$

配送先敬称

deviceInformation
string <= 65535 characters ^[ -~]+$

デバイス情報

repeater
boolean
Default: false

リピータフラグ

userRegistrationElapsedDays
string <= 7 characters ^[0-9]+$

ユーザーID登録後経過日数

promotionCode
string <= 36 characters ^[0-9a-zA-Z-]+$

プロモーションコード

giftCardMessage
string <= 160 characters

ギフトカードメッセージ

giftCardType
string
Enum: "ANNIVERSARY" "APRIL_FOOLS_DAY" "BABY_SHOWER" "BIRTHDAY" "BOSSES_DAY" "CELEBRATE_FALL" "CHINESE_NEW_YEAR" "CHRISTMAS" "CONGRATULATIONS" "EASTER" "FATHERS_DAY" "GRADUATION" "GRANDPARENTS_DAY" "HALLOWEEN" "HANUKKAH" "HOLIDAY" "INDEPENDENCE_DAY" "KWANZAA" "MOTHERS_DAY" "NEW_YEARS_DAY" "OTHER" "PASSOVER" "SEASONS_GREETINGS" "SECRETARYS_DAY" "ST_PATRICKS_DAY" "SWEETEST_DAY" "THANKSGIVING" "VALENTINES_DAY" "WEDDING"

ギフトカードタイプ

  • ANNIVERSARY: 記念日
  • APRIL_FOOLS_DAY: エイプリルフール
  • BABY_SHOWER: ベビーシャワー
  • BIRTHDAY: 誕生日
  • BOSSES_DAY: ボスの日
  • CELEBRATE_FALL: セレブレイト・フォール
  • CHINESE_NEW_YEAR: 春節
  • CHRISTMAS: クリスマス
  • CONGRATULATIONS: お祝い
  • EASTER: イースター
  • FATHERS_DAY: 父の日
  • GRADUATION: 卒業
  • GRANDPARENTS_DAY: 祖父母の日
  • HALLOWEEN: ハロウィン
  • HANUKKAH: ハヌカー
  • HOLIDAY: 祝日
  • INDEPENDENCE_DAY: 独立記念日
  • KWANZAA: クワンザ
  • MOTHERS_DAY: 母の日
  • NEW_YEARS_DAY: 元日
  • OTHER: その他
  • PASSOVER: 過越
  • SEASONS_GREETINGS: 季節の挨拶
  • SECRETARYS_DAY: 秘書の日
  • ST_PATRICKS_DAY: 聖パトリックの祝日
  • SWEETEST_DAY: スウィーテスト・デー
  • THANKSGIVING: 感謝祭
  • VALENTINES_DAY:バレンタインデー
  • WEDDING: 結婚式
object (FraudDetectionCustomData)

不正検知カスタム情報

customData1
string <= 255 characters

カスタム項目1
現在未使用

customData2
string <= 255 characters

カスタム項目2
現在未使用

customData3
string <= 255 characters

カスタム項目3
現在未使用

customData4
string <= 255 characters

カスタム項目4
現在未使用

customData5
string <= 255 characters

カスタム項目5
現在未使用

customData6
string <= 255 characters

カスタム項目6
現在未使用

customData7
string <= 255 characters

カスタム項目7
現在未使用

customData8
string <= 256 characters

カスタム項目8
設定できる最大長はUTF-8で256byteです。

customData9
string <= 256 characters

カスタム項目9
設定できる最大長はUTF-8で256byteです。

customData10
string <= 255 characters

カスタム項目10
現在未使用

customData11
string <= 9 characters ^[0-9]+$

カスタム項目11

customData12
string <= 9 characters ^[0-9]+$

カスタム項目12

customData13
string <= 255 characters

カスタム項目13
現在未使用

customData14
string <= 255 characters

カスタム項目14
現在未使用

customData15
boolean

カスタム項目15

customData16
string <= 30 characters

カスタム項目16
設定できる最大長はUTF-8で30byteです。

customData17
string <= 9 characters ^[0-9]+$

カスタム項目17

customData18
string <= 9 characters ^[0-9]+$

カスタム項目18

customData19
string <= 30 characters

カスタム項目19
設定できる最大長はUTF-8で30byteです。

customData20
string <= 9 characters ^[0-9]+$

カスタム項目20

customData21
string <= 30 characters

カスタム項目21
設定できる最大長はUTF-8で30byteです。

customData22
string <= 30 characters

カスタム項目22
設定できる最大長はUTF-8で30byteです。

customData23
string <= 30 characters

カスタム項目23
設定できる最大長はUTF-8で30byteです。

customData24
string <= 30 characters

カスタム項目24
設定できる最大長はUTF-8で30byteです。

customData25
string <= 30 characters

カスタム項目25
設定できる最大長はUTF-8で30byteです。

customData26
string <= 255 characters

カスタム項目26
設定できる最大長はUTF-8で255byteです。

customData27
string <= 255 characters

カスタム項目27
設定できる最大長はUTF-8で255byteです。

customData28
string <= 255 characters

カスタム項目28
設定できる最大長はUTF-8で255byteです。

customData29
string <= 255 characters

カスタム項目29
設定できる最大長はUTF-8で255byteです。

customData30
string <= 255 characters

カスタム項目30
設定できる最大長はUTF-8で255byteです。

customData31
string <= 255 characters

カスタム項目31
設定できる最大長はUTF-8で255byteです。

customData32
string <= 255 characters

カスタム項目32
設定できる最大長はUTF-8で255byteです。

customData33
string <= 255 characters

カスタム項目33
設定できる最大長はUTF-8で255byteです。

customData34
string <= 255 characters

カスタム項目34
設定できる最大長はUTF-8で255byteです。

customData35
string <= 255 characters

カスタム項目35
設定できる最大長はUTF-8で255byteです。

customData36
string <= 255 characters

カスタム項目36
設定できる最大長はUTF-8で255byteです。

customData37
string <= 255 characters

カスタム項目37
設定できる最大長はUTF-8で255byteです。

customData38
string <= 255 characters

カスタム項目38
設定できる最大長はUTF-8で255byteです。

customData39
string <= 255 characters

カスタム項目39
設定できる最大長はUTF-8で255byteです。

customData40
string <= 255 characters

カスタム項目40
設定できる最大長はUTF-8で255byteです。

customData41
string <= 255 characters

カスタム項目41
設定できる最大長はUTF-8で255byteです。

customData42
string <= 255 characters

カスタム項目42
設定できる最大長はUTF-8で255byteです。

customData43
string <= 255 characters

カスタム項目43
設定できる最大長はUTF-8で255byteです。

customData44
string <= 255 characters

カスタム項目44
設定できる最大長はUTF-8で255byteです。

customData45
string <= 255 characters

カスタム項目45
設定できる最大長はUTF-8で255byteです。

customData46
string <= 255 characters

カスタム項目46
設定できる最大長はUTF-8で255byteです。

customData47
string <= 255 characters

カスタム項目47
設定できる最大長はUTF-8で255byteです。

customData48
string <= 255 characters

カスタム項目48
設定できる最大長はUTF-8で255byteです。

customData49
string <= 255 characters

カスタム項目49
設定できる最大長はUTF-8で255byteです。

customData50
string <= 255 characters

カスタム項目50
設定できる最大長はUTF-8で255byteです。

object (AdditionalOptions)

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

property name*
additional property
any

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 <= 36 characters

冪等キー
リクエスト毎にユニークな最大36桁の任意の文字列。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

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

3Dセキュア認証利用時には、以下のカード会員の情報を必ず設定してください。
未設定でもエラーにはなりませんが、変更になる可能性があります。

  • カード会員の名前
    リクエストパラメーターcreditOnfileInformation.onfileCard.cardholderNameが設定されている場合は、その値が利用されます。
    設定されていない場合は、登録されているカード情報の「カード名義人」が利用されます。
    カードの登録については、有効性確認(/credit/verifyCard)カード登録(/credit/storeCard)を参照ください。
  • カード会員のメールアドレスまたは電話番号
    payerに設定した値が利用されます。
    詳細は共通パラメーター対応表 - クレカ払いを参照ください。
required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

name
required
string <= 30 characters

表示用の加盟店様名
設定できる最大長はUTF-8で45byteです。

nameKana
required
string^[ァ-ヶー ]+$

表示用の加盟店様名(全角カナのみ)
設定できる最大長はUTF-8で60byteです。

nameAlphabet
required
string <= 25 characters ^[a-zA-Z0-9 \x2c-\x2f]+$

表示用の加盟店様名(英名)

nameShort
required
string <= 30 characters

表示用の加盟店様名(略称)
設定できる最大長はUTF-8で45byteです。

contactName
required
string <= 42 characters

加盟店様の問い合わせ先名称
設定できる最大長はUTF-8で63byteです。

contactEmail
required
string <email> <= 254 characters

加盟店様の問い合わせ先メールアドレス
RFC 5322の仕様に沿った形式のみ許可されます。

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactUrl
string <uri> <= 256 characters

加盟店様の問い合わせ先ページURL

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactPhone
required
string <= 13 characters ^[0-9-]+$

加盟店様の問い合わせ先電話番号

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactOpeningHours
required
string <= 11 characters ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]-([0-1]?[0-9]...

加盟店様の問い合わせ窓口の営業時間(HH:MM-HH:MM形式)

callbackUrl
string <uri> <= 256 characters

コールバックURL
リダイレクトが発生するリクエスト時は必ず設定してください。
リダイレクト後に加盟店様のサーバーに処理の遷移を戻すためのURLです。
詳細はリダイレクトとコールバックを参照ください。

webhookUrl
string <uri> <= 256 characters

Webhook URL
現金払いの支払いなど、処理が非同期で行われた場合に、その結果を通知するための加盟店様側のURLです。
httpsから始まるURLを設定してください。
※テスト環境ではhttpの指定が可能です。
詳細はWebhookを参照ください。

csrfToken
string <= 36 characters ^[0-9a-zA-Z-]+$

CSRFトークン
コールバックやWebhookの呼び出し時につける任意のパラメーターです。
CSRF対策のために利用してください。
詳細はリダイレクトとコールバックを参照ください。

required
object (Order)

取引情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

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

この取引に対する任意のオーダーID
加盟店様にてユニークな値を発行してください。

amount
required
string <= 15 characters

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

currency
string^[A-Z]{3}$
Default: "JPY"

通貨コード
ISO 4217のアルファベット3文字を設定します。
例えば日本円の場合JPYです。
省略時はJPYです。
※現時点ではJPYのみ利用可能です。

object (ClientFields)

加盟店自由項目

clientField1
string <= 100 characters

加盟店自由項目1
この取引に関する任意情報を紐づけます。
決済の情報としては利用されません。
またお客様には表示されません。
照会API、管理画面、取引配信ファイルで値を確認できます。
設定できる最大長はEUC-JPで100byteです。

clientField2
string <= 100 characters

加盟店自由項目2
「加盟店自由項目1」の説明を参照ください。
最大長はEUC-JPで100byteです。

clientField3
string <= 100 characters

加盟店自由項目3
「加盟店自由項目1」の説明を参照ください。
設定できる最大長はEUC-JPで100byteです。

Array of objects (Item)

商品情報の一覧

Array
name
required
string <= 128 characters

商品の名称
設定できる最大長はUTF-8で192byteです。

description
string <= 120 characters

商品の説明
設定できる最大長はUTF-8で180byteです。

quantity
required
integer <= 9999

商品の購入数

type
required
string
Enum: "DIGITAL" "PHYSICAL" "SERVICE"

商品のタイプ

  • DIGITAL:デジコン
  • PHYSICAL:物販
  • SERVICE:役務
price
required
string <= 15 characters

商品の単価
order.amount以下の値を設定してください。

決済手段ごとの制限事項

  • クレジットカード(ReD Shield利用時): <= 12 characters
  • メルペイ: <= 7 characters
category
string^[0-9]{4}$

商品のMerchant category code(MCC)
MCCはISO 18245で定められた加盟店様の業種カテゴリです。
一般的には加盟店様の業種カテゴリと商品のカテゴリは同じですが、この商品により適したものがあれば個別に設定できます。

決済手段ごとの制限事項

  • メルペイ: required
productId
string <= 30 characters

商品の識別番号
加盟店様が商品ごとに一意に採番した番号です。
半角のみ設定可能です。

決済手段ごとの制限事項

  • クレジットカード(ReD Shield利用時): <= 18 characters
productCode
string <= 13 characters

商品の識別コード
JANコードUPCコードを設定します。 半角のみ設定可能です。

transactionType
required
string (TransactionType)
Enum: "CIT" "MIT" "OTHER"

取引タイプ
この取引がお客様操作によって開始されたか、自動チャージのように加盟店様操作で行われたかを示します。
現時点では設定する値によって当サービス内の処理は変わりません。

  • CIT: Customer Initiated Transaction(お客様操作起点)
  • MIT: Merchant Initiated Transaction(加盟店様操作起点)
  • OTHER: 上記以外
object (Address)

配送先住所情報

name
required
string <= 40 characters

住所の宛名
設定できる最大長はUTF-8で60byteです。

line1
required
string <= 50 characters

住所の町域・丁目番地
設定できる最大長はUTF-8で75byteです。

line2
string <= 50 characters

住所の建物・号室
設定できる最大長はUTF-8で75byteです。

line3
string <= 50 characters

住所情報に関する予備項目
設定できる最大長はUTF-8で75byteです。

city
required
string <= 50 characters

住所の市区町村
「渋谷区」「横浜市」などの市区町村名です。
日本語・漢字でなくても構いません。
設定できる最大長はUTF-8で75byteです。

state
required
string^[0-9]{3}$

住所の都道府県番号
都道府県コード表を参照ください。
日本の場合は「001」から「047」からなる先頭ゼロ埋め3桁の形式です。

postCode
required
string <= 16 characters ^[0-9-]+$

住所の郵便番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード ReD Shield: <= 9 characters
country
string^[0-9]{3}$

住所の国番号
ISO3166-1の数字3桁を設定します。
ITU-E.164ではないのでご注意ください。例えば日本の場合「392」です。

addressMatch
boolean
Default: false

配送先住所と請求先住所が同じ場合はtrueを設定します。
住所はいずれかのみ設定してください。

object (Address)

請求先住所情報

name
required
string <= 40 characters

住所の宛名
設定できる最大長はUTF-8で60byteです。

line1
required
string <= 50 characters

住所の町域・丁目番地
設定できる最大長はUTF-8で75byteです。

line2
string <= 50 characters

住所の建物・号室
設定できる最大長はUTF-8で75byteです。

line3
string <= 50 characters

住所情報に関する予備項目
設定できる最大長はUTF-8で75byteです。

city
required
string <= 50 characters

住所の市区町村
「渋谷区」「横浜市」などの市区町村名です。
日本語・漢字でなくても構いません。
設定できる最大長はUTF-8で75byteです。

state
required
string^[0-9]{3}$

住所の都道府県番号
都道府県コード表を参照ください。
日本の場合は「001」から「047」からなる先頭ゼロ埋め3桁の形式です。

postCode
required
string <= 16 characters ^[0-9-]+$

住所の郵便番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード ReD Shield: <= 9 characters
country
string^[0-9]{3}$

住所の国番号
ISO3166-1の数字3桁を設定します。
ITU-E.164ではないのでご注意ください。例えば日本の場合「392」です。

required
object (Payer)

購入者情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

name
required
string <= 40 characters

購入者の氏名(フルネーム)
設定できる最大長はUTF-8で60byteです。

nameKana
string^[ァ-ヶー ]+$

購入者の氏名(全角カナのみ)
設定できる最大長はUTF-8で60byteです。

決済手段ごとの制限事項

  • コンビニ: required
  • Pay-easy: required
nameAlphabet
string <= 30 characters ^[a-zA-Z0-9 \x2c-\x2f]+$

購入者の氏名(英名)

gender
string
Enum: "MALE" "FEMALE" "OTHER"

購入者の性別

dateOfBirth
string

購入者の誕生日
YYYYMMDD形式

email
string <email> <= 254 characters

購入者のメールアドレス
RFC 5322の仕様に沿った形式のみ許可されます。

deliveryEmail
string <email> <= 254 characters

取引内容がWebチケットなどの電子デリバリーの場合、配信先のメールアドレスを設定します。
RFC 5322の仕様に沿った形式のみ許可されます。

Array of objects (Phone)

購入者の電話情報一覧

Array
type
string
Enum: "MOBILE" "HOME" "WORK" "OTHER"

電話のタイプ
携帯、家、職場、その他から選択します。

  • MOBILE:携帯電話
  • HOME:固定電話
  • WORK:勤務先
  • OTHER:その他

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): requiredOTHER以外
countryCode
string^[0-9]{1,3}$

電話の国コード
ITU-E.164の1~3桁の数字を設定します。
ISO3166-1ではないのでご注意ください。
プラス記号(+)はつけないでください。
例として日本の場合は「81」です。

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): required
number
string <= 13 characters ^[0-9-]+$

電話番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): required
  • コンビニ: required
  • Pay-easy: required
accountId
string <= 60 characters ^[a-zA-Z0-9@_.-]{1,60}$

加盟店様サイト上における購入者のアカウントIDなど、一意に識別するためのID

ip
string <= 39 characters

購入者の発信元IPアドレス

deviceType
string
Enum: "PC_WEB" "PC_APP" "MOBILE_WEB"

購入者のデバイス情報をWeb、アプリから選択

  • PC_WEB:PC(Web)
  • PC_APP:PC(アプリ)
  • MOBILE_WEB:モバイル(Web)
httpUserAgent
string <= 512 characters

購入者のブラウザのUserAgent
半角英数字記号が設定可能です。

required
object (CreditOnfileInformation)

登録済みクレカ払い情報

required
object (OnfileCard)

登録されているカード情報

memberId
required
string (MemberId) ^[a-zA-Z0-9@_.-]{1,60}$

会員のID

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

登録されているカードのタイプ

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

登録されているカードのうち、今回利用するカードのID(物理連番)
cardIdindexの両方を省略した場合はデフォルトカードが使われます。

index
string (OnfileCardIndex) ^[0-4]$

登録されているカードのうち、今回利用するカードのインデックス(論理連番)
cardIdが設定されている場合はcardIdが優先されます。
cardIdindexの両方を省略した場合はデフォルトカードが使われます。

cardholderName
string^[a-zA-Z0-9- ]+$

カード名義人
typeAPPLE_PAYの場合は設定しても無視されます。

  • 省略した場合:登録済みのカード情報に保存されているカード名義人を使用します。
  • 指定した場合:設定したカード名義人を、既存のカード情報に保存されているカード名義人よりも優先して使用します。随時支払いまたは有効性確認が完了後、既存のカード情報のカード名義人も、この新しく設定したカード名義人で更新します。
required
object (CreditChargeOptions)

クレカ払いオプション情報

authorizationMode
required
string
Default: "AUTH"
Enum: "AUTH" "CAPTURE"

支払い要求のタイプ

  • AUTH:仮売上
  • CAPTURE:即時売上
useTds2
boolean
Default: true

3Dセキュア認証の利用有無

  • true: 3Dセキュア認証を利用します。
  • false: 3Dセキュア認証を利用しません。この取引が不正利用によりチャージバックとなった場合、加盟店様が支払いの責任を負う可能性があります。 Apple Payは利用できません。
useFraudDetection
boolean
Default: false

不正検知の利用有無
Apple Payは利用できません。

itemCode
string (ItemCode) ^0000[0-9]{3}$

商品番号
加盟店様とカード会社との契約で定められた場合のみ設定します。
省略時はデフォルトで「0000990」が設定されます。

paymentMethod
string
Default: "ONE_TIME"
Enum: "ONE_TIME" "INSTALLMENT" "BONUS_ONE_TIME" "REVOLVING"

支払方法
Apple Payは一括払い固定になります。

  • ONE_TIME:一括
  • INSTALLMENT:分割
  • BONUS_ONE_TIME:ボーナス一括
  • REVOLVING:リボ
installments
string^[0-9]{1,2}$

分割回数
支払方法が分割の場合に設定します。
設定可能な分割回数は契約により異なります。

object (Tds2Information)

3Dセキュア情報

object (Tds2Options)

3Dセキュアオプション情報

skipNotEnrolledCard
boolean
Default: false

未対応時の認証スキップ
仕向先カード会社が3Dセキュア認証に未対応の場合、エラーにするか、認証をスキップしてオーソリ(信用照会)するかを選択します。

  • false: リクエストはエラーになります。
  • true: 3Dセキュア認証をスキップしてオーソリ(信用照会)します。この取引が不正利用によりチャージバックとなった場合、加盟店様が支払いの責任を負う可能性があります。
allowAttempt
string
Default: "FOLLOW"
Enum: "FOLLOW" "ALLOW" "NOT_ALLOW"

認証結果Attempt時の挙動
3Dセキュア認証の結果、カード会社からECI 06(Mastercard以外)または01(Mastercard)が返された場合の処理を選択します。
ECI06/01は、カード発行会社が3Dセキュアに対応していない場合やサーバー障害などの時に、認証プロセス自体はできていませんが認証成功と扱うことを意味します。
通常、この取引が不正利用によりチャージバックとなった場合、支払いの責任はカード発行会社となり加盟店様には請求されません。
それでもECI06/01の支払いを受け付けたくない場合は、NOT_ALLOWを設定してください。
FOLLOWを設定した場合、3Dセキュア必須化の契約に従います。

  • FOLLOW:ショップ契約の「3Dセキュア必須化」の内容に従う
  • ALLOW:認証成功と扱う
  • NOT_ALLOW:認証失敗と扱う
requiresChallenge
boolean
Default: false

認証チャレンジ必須
リスク判定の結果によらず3Dセキュア認証チャレンジを要求する場合にtrueを設定します。
ただし、カード発行会社が対応していない場合があります。

autoAuthorization
boolean
Default: true

自動オーソリ有無
3Dセキュア認証後に自動でオーソリ(信用照会)をせずに、加盟店様から明示的に3Dセキュア後APIを呼び出してオーソリを実施したい場合にはfalseを設定します。
「自動オーソリあり」の場合、オーソリが実行されてもお客様がブラウザを閉じる、通信エラーが発生するなどして処理が中断し、貴社にコールバックがされず状態不整合になる可能性があります。
「自動オーソリなし」は、オーソリのリクエストを加盟店様にて制御できるため上記のリスクを低減できます。

object (Tds2Data)

3Dセキュアデータ情報

chAccChange
string

カード会員情報の最終更新日
YYYYMMDD形式

chAccDate
string

カード会員の作成日
YYYYMMDD形式

chAccPwChange
string

カード会員のパスワード変更日
YYYYMMDD形式

nbPurchaseAccount
number <= 9999

過去6ヶ月間にこのカード会員が購入した回数

paymentAccAge
string

カード登録日
カード会員にカード情報が登録された日付を設定します。
YYYYMMDD形式

provisionAttemptsDay
number <= 999

過去24時間に行われたカード情報追加の試行回数

shipAddressUsage
string

配送先住所の初回使用日
取引で使用される配送先住所が加盟店様で最初に使用された日付を設定します。
YYYYMMDD形式

shipNameInd
string^(01|02)$

カード会員名と配送先名の一致/不一致
カード会員の会員名と取引に使用される配送先名の一致/不一致を設定します。

  • 01: カード会員名と配送先名が一致
  • 02: カード会員名と配送先名が不一致
suspiciousAccActivity
string^(01|02)$

カード会員の不審行為情報
カード会員で、不審な行動(過去の不正行為を含む)を加盟店様が発見したかどうかを設定します。

  • 01: 不審な行動は見られなかった
  • 02: 不審な行動が見られた
txnActivityDay
number <= 999

過去24時間の取引回数
過去24時間に行われた、カード会員と加盟店様との取引の回数を設定します。

txnActivityYear
number <= 999

前年の取引回数
前年に行われた、カード会員と加盟店様との取引の回数を設定します。

threeDSReqAuthData
string <= 2048 characters

ログイン証跡
カード会員が特定の方法でログインしたことを裏付けるデータを設定します。
設定できる最大長はUTF-8で2048byteです。

threeDSReqAuthMethod
string^(01|02|03|04|05|06)$

ログイン方法
カード会員の加盟店様システムへのログイン方法を設定します。

  • 01: 認証なし(ゲストとしてログイン)
  • 02: 加盟店様自身の認証情報
  • 03: SSO(シングルサインオン)
  • 04: イシュアーの認証情報
  • 05: サードパーティ認証
  • 06: FIDO認証
threeDSReqAuthTimestamp
string

ログイン日時
カード会員のログイン日時を設定します。
YYYYMMDDHHMM形式

deliveryTimeframe
string^(01|02|03|04)$

商品納品時間枠

  • 01: 電子デリバリー
  • 02: 当日出荷
  • 03: 翌日出荷
  • 04: 2日目以降の出荷
giftCardAmount
number <= 999999999999999

プリペイドカードまたはギフトカードを購入の場合、総購入金額の値を設定します。

giftCardCount
number <= 99

プリペイドカードまたはギフトカードを購入の場合、購入された総数を設定します。

giftCardCurr
string^[0-9]{3}$

購入されたプリペイドカードまたはギフトカードの通貨コード
プリペイドカードまたはギフトカードを購入の場合、カードの通貨を表す、ISO 4217で定義されている通貨コードを設定します。
※以下のコードは対象外です。
955, 956, 957, 958, 959, 960, 961, 962, 963, 964, 999

preOrderDate
string

商品の発売予定日
先行予約購入の場合は、商品の発売予定日を設定します。
YYYYMMDD形式

preOrderPurchaseInd
string^(01|02)$

商品の販売時期情報
先行予約購入か、発売済み商品の購入かを設定します。

  • 01: 発売済み商品
  • 02: 先行予約商品
reorderItemsInd
string^(01|02)$

商品の注文情報
カード会員が以前購入した商品を再び注文しているかどうかを設定します。

  • 01: 初回注文
  • 02: 再注文
shipInd
string^(01|02|03|04|05|06|07)$

取引の配送方法

  • 01: カード会員の請求先住所に配送する
  • 02: 加盟店様が保持している別の、確認済み住所に配送する
  • 03: カード会員の請求先住所と異なる住所に配送する
  • 04: 店舗へ配送 / 近所の店舗での受け取り(店舗の住所は配送先住所で設定する)
  • 05: デジタル商品(オンラインサービス、電子ギフトカードおよび償還コードを含む)
  • 06: 配送なし(旅行およびイベントのチケット)
  • 07: その他(ゲーム、配送されないデジタルサービス、電子メディアの購読料など)
object (FraudDetectionInformation)

不正検知情報

required
object (FraudDetectionOptions)

不正検知オプション情報

screeningType
required
string
Value: "RED_SHIELD"

審査タイプ

stopAuthorizationThreshold
string^DENY|CHALLENGE$

オーソリ中断閾値
当パラメーターを設定した場合はオーソリ(信用照会)前に不正審査を実施し、審査結果が設定した閾値以上である場合はオーソリ(信用照会)を中断します。
例) CHALLENGEを設定した場合、審査結果がCHALLENGEまたはDENYの際はオーソリを中断します。

asyncMode
boolean
Default: false

非同期モード
trueを設定した場合は不正審査を非同期で実行します。 この際レスポンスに審査結果は含まれませんので、任意のタイミングで取引照会API(/order/inquiry)を実行し取得してください。

required
object (FraudDetectionData)

不正検知データ情報

userId
required
string <= 60 characters ^[a-zA-Z0-9@_.-]+$

ユーザーID

identityDocType
string
Enum: "PASSPORT" "TAXSTATEMENT"

本人確認書類タイプ
本人確認書類IDに設定する書類タイプを設定します。
本人確認書類IDを設定する場合は省略できません。

  • PASSPORT:パスポート
  • TAXSTATEMENT:納税証明書
identityDocId
string <= 20 characters ^[0-9a-zA-Z-]+$

本人確認書類ID
設定する場合は本人確認書類タイプも設定する必要があります。

shippingCorporationName
string <= 60 characters

配送先会社名

shippingPhone
string <= 13 characters ^[0-9-]+$

配送先電話番号

shippingEmail
string <email> <= 254 characters

配送先メールアドレス

shippingMethod
string
Enum: "NEXT_DAY_OVERNIGHT" "TWO_DAY_SERVICE" "THREE_DAY_SERVICE" "LOWEST_COST" "CARRIER_DESIGNATED_BY_CUSTOMER" "ELECTRONIC_DELIVERY" "GROUND" "INTERNATIONAL" "MILITARY" "STORE_PICKUP" "SAME_DAY_SERVICE" "OTHER" "PUDO" "EXPEDITED"

配送方法

  • NEXT_DAY_OVERNIGHT: 翌日発送
  • TWO_DAY_SERVICE: 2日以内発送
  • THREE_DAY_SERVICE: 3日以内発送
  • LOWEST_COST: 最安値の配送方法
  • CARRIER_DESIGNATED_BY_CUSTOMER: お客様指定の運送会社
  • ELECTRONIC_DELIVERY: 電子郵便
  • GROUND: 陸上輸送
  • INTERNATIONAL: 国際郵便
  • MILITARY: 軍事郵便
  • STORE_PICKUP: 店舗受け取り
  • SAME_DAY_SERVICE: 即日配送
  • OTHER: その他
  • PUDO: PUDOステーション
  • EXPEDITED: 速達郵便
shippingAmount
string <= 15 characters ^[0-9]+$

送料
審査タイプ(screeningType)がRED_SHIELDの場合、12桁以下で設定してください。

shippingTrackingNumber
string <= 19 characters ^[0-9a-zA-Z-]+$

トラッキング番号

shippingComment
string <= 160 characters

発送時コメント

shippingSalutation
string <= 5 characters ^[ -~。-゚]+$

配送先敬称

deviceInformation
string <= 65535 characters ^[ -~]+$

デバイス情報

repeater
boolean
Default: false

リピータフラグ

userRegistrationElapsedDays
string <= 7 characters ^[0-9]+$

ユーザーID登録後経過日数

promotionCode
string <= 36 characters ^[0-9a-zA-Z-]+$

プロモーションコード

giftCardMessage
string <= 160 characters

ギフトカードメッセージ

giftCardType
string
Enum: "ANNIVERSARY" "APRIL_FOOLS_DAY" "BABY_SHOWER" "BIRTHDAY" "BOSSES_DAY" "CELEBRATE_FALL" "CHINESE_NEW_YEAR" "CHRISTMAS" "CONGRATULATIONS" "EASTER" "FATHERS_DAY" "GRADUATION" "GRANDPARENTS_DAY" "HALLOWEEN" "HANUKKAH" "HOLIDAY" "INDEPENDENCE_DAY" "KWANZAA" "MOTHERS_DAY" "NEW_YEARS_DAY" "OTHER" "PASSOVER" "SEASONS_GREETINGS" "SECRETARYS_DAY" "ST_PATRICKS_DAY" "SWEETEST_DAY" "THANKSGIVING" "VALENTINES_DAY" "WEDDING"

ギフトカードタイプ

  • ANNIVERSARY: 記念日
  • APRIL_FOOLS_DAY: エイプリルフール
  • BABY_SHOWER: ベビーシャワー
  • BIRTHDAY: 誕生日
  • BOSSES_DAY: ボスの日
  • CELEBRATE_FALL: セレブレイト・フォール
  • CHINESE_NEW_YEAR: 春節
  • CHRISTMAS: クリスマス
  • CONGRATULATIONS: お祝い
  • EASTER: イースター
  • FATHERS_DAY: 父の日
  • GRADUATION: 卒業
  • GRANDPARENTS_DAY: 祖父母の日
  • HALLOWEEN: ハロウィン
  • HANUKKAH: ハヌカー
  • HOLIDAY: 祝日
  • INDEPENDENCE_DAY: 独立記念日
  • KWANZAA: クワンザ
  • MOTHERS_DAY: 母の日
  • NEW_YEARS_DAY: 元日
  • OTHER: その他
  • PASSOVER: 過越
  • SEASONS_GREETINGS: 季節の挨拶
  • SECRETARYS_DAY: 秘書の日
  • ST_PATRICKS_DAY: 聖パトリックの祝日
  • SWEETEST_DAY: スウィーテスト・デー
  • THANKSGIVING: 感謝祭
  • VALENTINES_DAY:バレンタインデー
  • WEDDING: 結婚式
object (FraudDetectionCustomData)

不正検知カスタム情報

customData1
string <= 255 characters

カスタム項目1
現在未使用

customData2
string <= 255 characters

カスタム項目2
現在未使用

customData3
string <= 255 characters

カスタム項目3
現在未使用

customData4
string <= 255 characters

カスタム項目4
現在未使用

customData5
string <= 255 characters

カスタム項目5
現在未使用

customData6
string <= 255 characters

カスタム項目6
現在未使用

customData7
string <= 255 characters

カスタム項目7
現在未使用

customData8
string <= 256 characters

カスタム項目8
設定できる最大長はUTF-8で256byteです。

customData9
string <= 256 characters

カスタム項目9
設定できる最大長はUTF-8で256byteです。

customData10
string <= 255 characters

カスタム項目10
現在未使用

customData11
string <= 9 characters ^[0-9]+$

カスタム項目11

customData12
string <= 9 characters ^[0-9]+$

カスタム項目12

customData13
string <= 255 characters

カスタム項目13
現在未使用

customData14
string <= 255 characters

カスタム項目14
現在未使用

customData15
boolean

カスタム項目15

customData16
string <= 30 characters

カスタム項目16
設定できる最大長はUTF-8で30byteです。

customData17
string <= 9 characters ^[0-9]+$

カスタム項目17

customData18
string <= 9 characters ^[0-9]+$

カスタム項目18

customData19
string <= 30 characters

カスタム項目19
設定できる最大長はUTF-8で30byteです。

customData20
string <= 9 characters ^[0-9]+$

カスタム項目20

customData21
string <= 30 characters

カスタム項目21
設定できる最大長はUTF-8で30byteです。

customData22
string <= 30 characters

カスタム項目22
設定できる最大長はUTF-8で30byteです。

customData23
string <= 30 characters

カスタム項目23
設定できる最大長はUTF-8で30byteです。

customData24
string <= 30 characters

カスタム項目24
設定できる最大長はUTF-8で30byteです。

customData25
string <= 30 characters

カスタム項目25
設定できる最大長はUTF-8で30byteです。

customData26
string <= 255 characters

カスタム項目26
設定できる最大長はUTF-8で255byteです。

customData27
string <= 255 characters

カスタム項目27
設定できる最大長はUTF-8で255byteです。

customData28
string <= 255 characters

カスタム項目28
設定できる最大長はUTF-8で255byteです。

customData29
string <= 255 characters

カスタム項目29
設定できる最大長はUTF-8で255byteです。

customData30
string <= 255 characters

カスタム項目30
設定できる最大長はUTF-8で255byteです。

customData31
string <= 255 characters

カスタム項目31
設定できる最大長はUTF-8で255byteです。

customData32
string <= 255 characters

カスタム項目32
設定できる最大長はUTF-8で255byteです。

customData33
string <= 255 characters

カスタム項目33
設定できる最大長はUTF-8で255byteです。

customData34
string <= 255 characters

カスタム項目34
設定できる最大長はUTF-8で255byteです。

customData35
string <= 255 characters

カスタム項目35
設定できる最大長はUTF-8で255byteです。

customData36
string <= 255 characters

カスタム項目36
設定できる最大長はUTF-8で255byteです。

customData37
string <= 255 characters

カスタム項目37
設定できる最大長はUTF-8で255byteです。

customData38
string <= 255 characters

カスタム項目38
設定できる最大長はUTF-8で255byteです。

customData39
string <= 255 characters

カスタム項目39
設定できる最大長はUTF-8で255byteです。

customData40
string <= 255 characters

カスタム項目40
設定できる最大長はUTF-8で255byteです。

customData41
string <= 255 characters

カスタム項目41
設定できる最大長はUTF-8で255byteです。

customData42
string <= 255 characters

カスタム項目42
設定できる最大長はUTF-8で255byteです。

customData43
string <= 255 characters

カスタム項目43
設定できる最大長はUTF-8で255byteです。

customData44
string <= 255 characters

カスタム項目44
設定できる最大長はUTF-8で255byteです。

customData45
string <= 255 characters

カスタム項目45
設定できる最大長はUTF-8で255byteです。

customData46
string <= 255 characters

カスタム項目46
設定できる最大長はUTF-8で255byteです。

customData47
string <= 255 characters

カスタム項目47
設定できる最大長はUTF-8で255byteです。

customData48
string <= 255 characters

カスタム項目48
設定できる最大長はUTF-8で255byteです。

customData49
string <= 255 characters

カスタム項目49
設定できる最大長はUTF-8で255byteです。

customData50
string <= 255 characters

カスタム項目50
設定できる最大長はUTF-8で255byteです。

object (AdditionalOptions)

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

property name*
additional property
any

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 <= 36 characters

冪等キー
リクエスト毎にユニークな最大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個までの要素を設定可能です。

property name*
additional property
any

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 <= 36 characters

冪等キー
リクエスト毎にユニークな最大36桁の任意の文字列。
詳細は冪等処理を参照ください。

Request Body schema: application/json
required

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

  1. トークン化して設定

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

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

3Dセキュア認証利用時には、以下のカード会員の情報を必ず設定してください。
未設定でもエラーにはなりませんが、変更になる可能性があります。

  • カード会員の名前
    • トークン化して設定
      MPクレカトークンの「カード名義人」が利用されます。
    • 登録済み情報を設定
      リクエストパラメーターcreditVerificationInformation.onfileCard.cardholderNameが設定されている場合は、その値が利用されます。
      設定されていない場合は、登録されているカード情報の「カード名義人」が利用されます。
    • 直接設定
      creditVerificationInformation.card.cardholderNameが利用されます。
  • カード会員のメールアドレスまたは電話番号
    payerに設定した値が利用されます。 詳細は共通パラメーター対応表 - クレカ払いを参照ください。

有効性確認後にカード情報を会員に紐づけて登録した場合、設定した「カード名義人」が登録されます。

required
object (Merchant)

加盟店(ショップ)情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

name
required
string <= 30 characters

表示用の加盟店様名
設定できる最大長はUTF-8で45byteです。

nameKana
required
string^[ァ-ヶー ]+$

表示用の加盟店様名(全角カナのみ)
設定できる最大長はUTF-8で60byteです。

nameAlphabet
required
string <= 25 characters ^[a-zA-Z0-9 \x2c-\x2f]+$

表示用の加盟店様名(英名)

nameShort
required
string <= 30 characters

表示用の加盟店様名(略称)
設定できる最大長はUTF-8で45byteです。

contactName
required
string <= 42 characters

加盟店様の問い合わせ先名称
設定できる最大長はUTF-8で63byteです。

contactEmail
required
string <email> <= 254 characters

加盟店様の問い合わせ先メールアドレス
RFC 5322の仕様に沿った形式のみ許可されます。

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactUrl
string <uri> <= 256 characters

加盟店様の問い合わせ先ページURL

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactPhone
required
string <= 13 characters ^[0-9-]+$

加盟店様の問い合わせ先電話番号

決済手段ごとの制限事項

  • d払い: contactEmail,contactUrl,contactPhoneの合計が96byte以下
    /(半角スラッシュ)は4byteとしてカウント
contactOpeningHours
required
string <= 11 characters ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]-([0-1]?[0-9]...

加盟店様の問い合わせ窓口の営業時間(HH:MM-HH:MM形式)

callbackUrl
string <uri> <= 256 characters

コールバックURL
リダイレクトが発生するリクエスト時は必ず設定してください。
リダイレクト後に加盟店様のサーバーに処理の遷移を戻すためのURLです。
詳細はリダイレクトとコールバックを参照ください。

webhookUrl
string <uri> <= 256 characters

Webhook URL
現金払いの支払いなど、処理が非同期で行われた場合に、その結果を通知するための加盟店様側のURLです。
httpsから始まるURLを設定してください。
※テスト環境ではhttpの指定が可能です。
詳細はWebhookを参照ください。

csrfToken
string <= 36 characters ^[0-9a-zA-Z-]+$

CSRFトークン
コールバックやWebhookの呼び出し時につける任意のパラメーターです。
CSRF対策のために利用してください。
詳細はリダイレクトとコールバックを参照ください。

required
object (OrderWithoutAmount)

取引情報

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

この取引に対する任意のオーダーID
加盟店様にてユニークな値を発行してください。

object (ClientFields)

加盟店自由項目

clientField1
string <= 100 characters

加盟店自由項目1
この取引に関する任意情報を紐づけます。
決済の情報としては利用されません。
またお客様には表示されません。
照会API、管理画面、取引配信ファイルで値を確認できます。
設定できる最大長はEUC-JPで100byteです。

clientField2
string <= 100 characters

加盟店自由項目2
「加盟店自由項目1」の説明を参照ください。
最大長はEUC-JPで100byteです。

clientField3
string <= 100 characters

加盟店自由項目3
「加盟店自由項目1」の説明を参照ください。
設定できる最大長はEUC-JPで100byteです。

Array of objects (Item)

商品情報の一覧

決済手段ごとの制限事項

  • 楽天ペイ(オンライン決済)V2 利用承諾: required
Array
name
required
string <= 128 characters

商品の名称
設定できる最大長はUTF-8で192byteです。

description
string <= 120 characters

商品の説明
設定できる最大長はUTF-8で180byteです。

quantity
required
integer <= 9999

商品の購入数

type
required
string
Enum: "DIGITAL" "PHYSICAL" "SERVICE"

商品のタイプ

  • DIGITAL:デジコン
  • PHYSICAL:物販
  • SERVICE:役務
price
required
string <= 15 characters

商品の単価
order.amount以下の値を設定してください。

決済手段ごとの制限事項

  • クレジットカード(ReD Shield利用時): <= 12 characters
  • メルペイ: <= 7 characters
category
string^[0-9]{4}$

商品のMerchant category code(MCC)
MCCはISO 18245で定められた加盟店様の業種カテゴリです。
一般的には加盟店様の業種カテゴリと商品のカテゴリは同じですが、この商品により適したものがあれば個別に設定できます。

決済手段ごとの制限事項

  • メルペイ: required
productId
string <= 30 characters

商品の識別番号
加盟店様が商品ごとに一意に採番した番号です。
半角のみ設定可能です。

決済手段ごとの制限事項

  • クレジットカード(ReD Shield利用時): <= 18 characters
productCode
string <= 13 characters

商品の識別コード
JANコードUPCコードを設定します。 半角のみ設定可能です。

transactionType
required
string (TransactionType)
Enum: "CIT" "MIT" "OTHER"

取引タイプ
この取引がお客様操作によって開始されたか、自動チャージのように加盟店様操作で行われたかを示します。
現時点では設定する値によって当サービス内の処理は変わりません。

  • CIT: Customer Initiated Transaction(お客様操作起点)
  • MIT: Merchant Initiated Transaction(加盟店様操作起点)
  • OTHER: 上記以外
object (Address)

配送先住所情報

name
required
string <= 40 characters

住所の宛名
設定できる最大長はUTF-8で60byteです。

line1
required
string <= 50 characters

住所の町域・丁目番地
設定できる最大長はUTF-8で75byteです。

line2
string <= 50 characters

住所の建物・号室
設定できる最大長はUTF-8で75byteです。

line3
string <= 50 characters

住所情報に関する予備項目
設定できる最大長はUTF-8で75byteです。

city
required
string <= 50 characters

住所の市区町村
「渋谷区」「横浜市」などの市区町村名です。
日本語・漢字でなくても構いません。
設定できる最大長はUTF-8で75byteです。

state
required
string^[0-9]{3}$

住所の都道府県番号
都道府県コード表を参照ください。
日本の場合は「001」から「047」からなる先頭ゼロ埋め3桁の形式です。

postCode
required
string <= 16 characters ^[0-9-]+$

住所の郵便番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード ReD Shield: <= 9 characters
country
string^[0-9]{3}$

住所の国番号
ISO3166-1の数字3桁を設定します。
ITU-E.164ではないのでご注意ください。例えば日本の場合「392」です。

addressMatch
boolean
Default: false

配送先住所と請求先住所が同じ場合はtrueを設定します。
住所はいずれかのみ設定してください。

object (Address)

請求先住所情報

name
required
string <= 40 characters

住所の宛名
設定できる最大長はUTF-8で60byteです。

line1
required
string <= 50 characters

住所の町域・丁目番地
設定できる最大長はUTF-8で75byteです。

line2
string <= 50 characters

住所の建物・号室
設定できる最大長はUTF-8で75byteです。

line3
string <= 50 characters

住所情報に関する予備項目
設定できる最大長はUTF-8で75byteです。

city
required
string <= 50 characters

住所の市区町村
「渋谷区」「横浜市」などの市区町村名です。
日本語・漢字でなくても構いません。
設定できる最大長はUTF-8で75byteです。

state
required
string^[0-9]{3}$

住所の都道府県番号
都道府県コード表を参照ください。
日本の場合は「001」から「047」からなる先頭ゼロ埋め3桁の形式です。

postCode
required
string <= 16 characters ^[0-9-]+$

住所の郵便番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード ReD Shield: <= 9 characters
country
string^[0-9]{3}$

住所の国番号
ISO3166-1の数字3桁を設定します。
ITU-E.164ではないのでご注意ください。例えば日本の場合「392」です。

required
object (Payer)

購入者情報
決済手段ごとの設定要否や各パラメーターの用途は、詳細は共通パラメーター対応表を参照ください。

name
required
string <= 40 characters

購入者の氏名(フルネーム)
設定できる最大長はUTF-8で60byteです。

nameKana
string^[ァ-ヶー ]+$

購入者の氏名(全角カナのみ)
設定できる最大長はUTF-8で60byteです。

決済手段ごとの制限事項

  • コンビニ: required
  • Pay-easy: required
nameAlphabet
string <= 30 characters ^[a-zA-Z0-9 \x2c-\x2f]+$

購入者の氏名(英名)

gender
string
Enum: "MALE" "FEMALE" "OTHER"

購入者の性別

dateOfBirth
string

購入者の誕生日
YYYYMMDD形式

email
string <email> <= 254 characters

購入者のメールアドレス
RFC 5322の仕様に沿った形式のみ許可されます。

deliveryEmail
string <email> <= 254 characters

取引内容がWebチケットなどの電子デリバリーの場合、配信先のメールアドレスを設定します。
RFC 5322の仕様に沿った形式のみ許可されます。

Array of objects (Phone)

購入者の電話情報一覧

Array
type
string
Enum: "MOBILE" "HOME" "WORK" "OTHER"

電話のタイプ
携帯、家、職場、その他から選択します。

  • MOBILE:携帯電話
  • HOME:固定電話
  • WORK:勤務先
  • OTHER:その他

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): requiredOTHER以外
countryCode
string^[0-9]{1,3}$

電話の国コード
ITU-E.164の1~3桁の数字を設定します。
ISO3166-1ではないのでご注意ください。
プラス記号(+)はつけないでください。
例として日本の場合は「81」です。

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): required
number
string <= 13 characters ^[0-9-]+$

電話番号
ハイフンの有無は問いません。

決済手段ごとの制限事項

  • クレジットカード(3Dセキュア認証利用時のみ): required
  • コンビニ: required
  • Pay-easy: required
accountId
string <= 60 characters ^[a-zA-Z0-9@_.-]{1,60}$

加盟店様サイト上における購入者のアカウントIDなど、一意に識別するためのID

ip
string <= 39 characters

購入者の発信元IPアドレス

deviceType
string
Enum: "PC_WEB" "PC_APP" "MOBILE_WEB"

購入者のデバイス情報をWeb、アプリから選択

  • PC_WEB:PC(Web)
  • PC_APP:PC(アプリ)
  • MOBILE_WEB:モバイル(Web)
httpUserAgent
string <= 512 characters

購入者のブラウザのUserAgent
半角英数字記号が設定可能です。

required
トークン化して設定 (object) or 登録済み情報を設定 (object) or 直接設定 (object) (CreditVerificationInformation)
One of
object (TokenizedCard)

トークン化されたカード情報
有効性確認(/credit/verifyCard)においては、Apple Payトークンは利用できません。

type
required
string
Enum: "MP_TOKEN" "APPLE_PAY_TOKEN" "GOOGLE_PAY_TOKEN"

カード情報トークンのタイプ
カード情報トークンtokenと合わせて設定してください。

  • MP_TOKEN: MPクレカトークン
  • APPLE_PAY_TOKEN: Apple Payトークン
  • GOOGLE_PAY_TOKEN: Google Payトークン
token
required
string

カード情報トークン
カード情報トークンのタイプtypeと合わせて設定してください。

  • MPクレカトークン
    カード情報をトークン化した値です。

  • Apple Payトークン
    Apple Payに対応した端末で取得したApple PayのPayment tokenをbase64エンコードした値です。

  • Google Payトークン
    Google Pay APIで取得したPayment tokenをbase64エンコードした値です。


カード情報トークンとカード情報を両方設定した場合は以下の通りです。

  • PCI DSSの認定を得ている加盟店様
    カード情報トークンが優先的に利用されます。
  • PCI DSSの認定を得ていない加盟店様
    契約不備のエラーになります。
object (CreditVerificationOptions)

カード有効性確認オプション情報

useTds2
boolean
Default: true

3Dセキュア認証の利用有無
true、または設定なしの場合は、3Dセキュア認証が行われます。

itemCode
string (ItemCode) ^0000[0-9]{3}$

商品番号
加盟店様とカード会社との契約で定められた場合のみ設定します。
省略時はデフォルトで「0000990」が設定されます。

object (OnfileCardOptions)

カード登録オプション情報
カード情報を会員に紐づけて登録する必要がない場合は、このパラメーターを設定しないでください。

memberId
required
string (MemberId) ^[a-zA-Z0-9@_.-]{1,60}$

カード情報を登録する対象の会員ID
該当する会員IDが存在しない場合は登録できませんが、createNewMemberパラメーターをtrueにすることで会員IDを新規登録します。

memberName
string (MemberName) <= 255 characters

新規登録する会員の名称
会員を新規登録する場合にのみ設定できます。
カードの追加・更新時に設定してもエラーにはなりませんが、会員の名称は更新されません。

cardId
string (OnfileCardId) ^[0-9]{1,4}$

更新するカードのID(物理連番)
登録済みのカード情報を上書きして保存する場合に該当のカードIDを設定します。
新規で追加保存する場合は設定不要です。
最大で5枚のカードを登録できます。

createNewMember
boolean
Default: false

会員ID未登録時の新規作成
trueにすると、指定した会員IDが存在しない場合に新規登録します。

setDefault
boolean
Default: false

デフォルト設定
trueにすると、このカードがデフォルトカードとして登録されます。
デフォルトカードにした場合、随時支払い時にカードのID(物理連番)cardId、またインデックス(論理連番)indexの設定が不要です。
また、洗替や一括決済サービス時に「カード登録連番」を設定することなく利用できます。

object (DuplicationCheckOptions)

重複チェック情報
成功取引、直接、トークン化の場合に指定が可能です。
トークン化の場合、MPクレカトークンのみ利用可能です。

enableDuplicationCheck
boolean
Default: false

カード番号重複チェック
同じカード番号の登録を許可しない場合はtrueにします。
有効期限が同一かはチェックしません。
チェックの結果、すでに同じカード番号が登録されている場合はinvalid_requestエラーを返却します。

includeDeletedCards
boolean
Default: false

重複チェックに削除カードを含めるか
カード番号重複チェック時の対象に削除済みカードを含める場合はtrueにします。

excludedMemberIds
Array of strings

重複チェック除外会員ID
設定した会員IDの一覧は、カード番号重複チェックの対象外にします。
最大20個まで設定可能です。

object (Tds2Information)

3Dセキュア情報

object (Tds2Options)

3Dセキュアオプション情報

skipNotEnrolledCard
boolean
Default: false

未対応時の認証スキップ
仕向先カード会社が3Dセキュア認証に未対応の場合、エラーにするか、認証をスキップしてオーソリ(信用照会)するかを選択します。

  • false: リクエストはエラーになります。
  • true: 3Dセキュア認証をスキップしてオーソリ(信用照会)します。この取引が不正利用によりチャージバックとなった場合、加盟店様が支払いの責任を負う可能性があります。
allowAttempt
string
Default: "FOLLOW"
Enum: "FOLLOW" "ALLOW" "NOT_ALLOW"

認証結果Attempt時の挙動
3Dセキュア認証の結果、カード会社からECI 06(Mastercard以外)または01(Mastercard)が返された場合の処理を選択します。
ECI06/01は、カード発行会社が3Dセキュアに対応していない場合やサーバー障害などの時に、認証プロセス自体はできていませんが認証成功と扱うことを意味します。
通常、この取引が不正利用によりチャージバックとなった場合、支払いの責任はカード発行会社となり加盟店様には請求されません。
それでもECI06/01の支払いを受け付けたくない場合は、NOT_ALLOWを設定してください。
FOLLOWを設定した場合、3Dセキュア必須化の契約に従います。

  • FOLLOW:ショップ契約の「3Dセキュア必須化」の内容に従う
  • ALLOW:認証成功と扱う
  • NOT_ALLOW:認証失敗と扱う
requiresChallenge
boolean
Default: false

認証チャレンジ必須
リスク判定の結果によらず3Dセキュア認証チャレンジを要求する場合にtrueを設定します。
ただし、カード発行会社が対応していない場合があります。

autoAuthorization
boolean
Default: true

自動オーソリ有無
3Dセキュア認証後に自動でオーソリ(信用照会)をせずに、加盟店様から明示的に3Dセキュア後APIを呼び出してオーソリを実施したい場合にはfalseを設定します。
「自動オーソリあり」の場合、オーソリが実行されてもお客様がブラウザを閉じる、通信エラーが発生するなどして処理が中断し、貴社にコールバックがされず状態不整合になる可能性があります。
「自動オーソリなし」は、オーソリのリクエストを加盟店様にて制御できるため上記のリスクを低減できます。

object (Tds2Data)

3Dセキュアデータ情報

chAccChange
string

カード会員情報の最終更新日
YYYYMMDD形式

chAccDate
string

カード会員の作成日
YYYYMMDD形式

chAccPwChange
string

カード会員のパスワード変更日
YYYYMMDD形式

nbPurchaseAccount
number <= 9999

過去6ヶ月間にこのカード会員が購入した回数

paymentAccAge
string

カード登録日
カード会員にカード情報が登録された日付を設定します。
YYYYMMDD形式

provisionAttemptsDay
number <= 999

過去24時間に行われたカード情報追加の試行回数

shipAddressUsage
string

配送先住所の初回使用日
取引で使用される配送先住所が加盟店様で最初に使用された日付を設定します。
YYYYMMDD形式

shipNameInd
string^(01|02)$

カード会員名と配送先名の一致/不一致
カード会員の会員名と取引に使用される配送先名の一致/不一致を設定します。

  • 01: カード会員名と配送先名が一致
  • 02: カード会員名と配送先名が不一致
suspiciousAccActivity
string^(01|02)$

カード会員の不審行為情報
カード会員で、不審な行動(過去の不正行為を含む)を加盟店様が発見したかどうかを設定します。

  • 01: 不審な行動は見られなかった
  • 02: 不審な行動が見られた
txnActivityDay
number <= 999

過去24時間の取引回数
過去24時間に行われた、カード会員と加盟店様との取引の回数を設定します。

txnActivityYear
number <= 999

前年の取引回数
前年に行われた、カード会員と加盟店様との取引の回数を設定します。

threeDSReqAuthData
string <= 2048 characters

ログイン証跡
カード会員が特定の方法でログインしたことを裏付けるデータを設定します。
設定できる最大長はUTF-8で2048byteです。

threeDSReqAuthMethod
string^(01|02|03|04|05|06)$

ログイン方法
カード会員の加盟店様システムへのログイン方法を設定します。

  • 01: 認証なし(ゲストとしてログイン)
  • 02: 加盟店様自身の認証情報
  • 03: SSO(シングルサインオン)
  • 04: イシュアーの認証情報
  • 05: サードパーティ認証
  • 06: FIDO認証
threeDSReqAuthTimestamp
string

ログイン日時
カード会員のログイン日時を設定します。
YYYYMMDDHHMM形式

deliveryTimeframe
string^(01|02|03|04)$

商品納品時間枠

  • 01: 電子デリバリー
  • 02: 当日出荷
  • 03: 翌日出荷
  • 04: 2日目以降の出荷
giftCardAmount
number <= 999999999999999

プリペイドカードまたはギフトカードを購入の場合、総購入金額の値を設定します。

giftCardCount
number <= 99

プリペイドカードまたはギフトカードを購入の場合、購入された総数を設定します。

giftCardCurr
string^[0-9]{3}$

購入されたプリペイドカードまたはギフトカードの通貨コード
プリペイドカードまたはギフトカードを購入の場合、カードの通貨を表す、ISO 4217で定義されている通貨コードを設定します。
※以下のコードは対象外です。
955, 956, 957, 958, 959, 960, 961, 962, 963, 964, 999

preOrderDate
string

商品の発売予定日
先行予約購入の場合は、商品の発売予定日を設定します。
YYYYMMDD形式

preOrderPurchaseInd
string^(01|02)$

商品の販売時期情報
先行予約購入か、発売済み商品の購入かを設定します。

  • 01: 発売済み商品
  • 02: 先行予約商品
reorderItemsInd
string^(01|02)$

商品の注文情報
カード会員が以前購入した商品を再び注文しているかどうかを設定します。

  • 01: 初回注文
  • 02: 再注文
shipInd
string^(01|02|03|04|05|06|07)$

取引の配送方法

  • 01: カード会員の請求先住所に配送する
  • 02: 加盟店様が保持している別の、確認済み住所に配送する
  • 03: カード会員の請求先住所と異なる住所に配送する
  • 04: 店舗へ配送 / 近所の店舗での受け取り(店舗の住所は配送先住所で設定する)
  • 05: デジタル商品(オンラインサービス、電子ギフトカードおよび償還コードを含む)
  • 06: 配送なし(旅行およびイベントのチケット)
  • 07: その他(ゲーム、配送されないデジタルサービス、電子メディアの購読料など)
object (AdditionalOptions)

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

property name*
additional property
any

Responses