リクエスト仕様

APIエンドポイントの原則

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

パラメーターの設定

フォーマット

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タイプでは以下のデータを送信してください。

項目	値	備考
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

冪等処理

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

1回目のリクエストが成功した場合の処理シーケンス

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

1回目のリクエストが失敗した場合の処理シーケンス

冪等性をサポートするAPI

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

利用方法

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

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

有効範囲

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

APIエンドポイントの原則​

パラメーターの設定​

フォーマット​

必須パラメーター​

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

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

任意パラメーター​

レスポンスパラメーター​

リクエストのHTTPヘッダー​

冪等処理​

冪等性をサポートするAPI​

利用方法​

有効範囲​