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

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

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つに分類されます。

決済手段

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

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

本人確認の認証手段

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

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

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

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

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

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

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

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

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

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

• OpenAPIタイプでは、一部の決済手段を除いて従来の「結果通知」はサポートしていません。
  タイムアウトなどでレスポンスが返らない場合は、同一の冪等キーを設定してリトライをお願いします。
  詳細についてはWebhook通知、従来の結果通知 概要（マルペイDocs）^※を参照ください。
  ※マルペイDocsの利用方法はこちら
• モバイルEdy決済、モバイルSuica決済など、支払い処理に記載のない決済手段は現時点で提供の予定はありません。
• 金額と税送料は統合しました。税送料は個別に設定できません。
• 個別の加盟店様向けの特殊機能やオプションパラメーターは利用できません。
• 同時接続数はプロトコルタイプ/モジュールタイプに適用されている値に準じます。
• プロトコルタイプ/モジュールタイプで取引登録を行った取引に対してOpenAPIタイプで処理を行った場合、従来の「結果通知」仕様に則り通知がされます。
• プロトコルタイプ/モジュールタイプのカード登録/更新(SaveCard)では、物理モードで登録連番を指定せずに登録済みのカード番号を指定した場合、同一のカード番号を「新規登録」ではなく「更新」として処理しますが、OpenAPIタイプでは「新規登録」として扱います。
• 登録済みカード情報のデフォルトフラグを付け替える機能は提供していません。

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

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

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

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

TLS通信の暗号スイート

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

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

パスワード方式で冪等キーと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

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

パスワード方式

ショップ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が異なります。

設定方法

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

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

Authorization: Bearer M2NlNjE1ZjYtMzc1Yy00ZGQ5LTg0OTAtOGEwNzliMzYyMjUzOjAwMDAwMDAwMDAwMDA=

冪等性(べきとうせい)とは、同じ操作を何度繰り返しても、同じ結果が得られるという性質です。
OpenAPIタイプの対象APIは冪等性をサポートしており、安全にリトライが可能です。

%%{
 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ステータスコードが409、429、500、502エラーであれば、再処理の結果、成功することがあります。
上記以外のエラーは、リトライをしても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の利用方法はこちら

上限値を増やす場合

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

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

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

リダイレクト

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

HTTPヘッダーを使って302リダイレクト

HTTP/1.1 302 Found
Location: {redirectUrl}

<html>
  <head>
    <meta http-equiv="refresh" content="0; URL={redirectUrl}" />
  </head>
</html>

コールバック

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

例を以下に示します。

取引リクエスト時に加盟店様が設定したコールバック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 URLwebhookUrlにHTTPで送信されます。
加盟店様のシステムで通知を受け取れるようWebhookエンドポイントをご用意ください。

通知の対象

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

• 現金払いの支払い完了
• 支払い完了済みのAmazon Pay V2をキャンセルした結果
• 都度支払い（フロントエンド方式）の決済結果通知

通知APIの仕様

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

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

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

通知への応答

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

通知の設定

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

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

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

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

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

• HTTPヘッダーの「認証情報」を本番アカウントのものに更新
• 接続先のAPIエンドポイントのFQDNを以下のものに更新

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

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

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

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

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

APIバージョン

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

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

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

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

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

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

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

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

{
  "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です。

ご利用可能なカード

以下の国際ブランドがついたクレジットカード・デビットカード、およびそのカード情報を登録した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の呼び出し前に行ってください。

%%{
 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: 結果表示

%%{
 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: 結果表示      

%%{
 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: 結果表示

%%{
 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: 結果表示

%%{
 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>不正検知結果を含む