基本ルール
基本情報
すべてのAPIリクエストはHTTPSを使用する必要があります。
リクエスト時にサーバー証明書の検証エラーを無視しないでください。不正なハイジャックを防ぐためです。
データフォーマット
すべてのAPIリクエストはJSONを使用する必要があります。
メッセージボディのデータ交換形式としてJSONを使用し、リクエストには以下のHTTPヘ ッダーを設定してください：
Content-Type: application/json
Accept: application/json
画像アップロードAPIを除きます。
APIレスポンス内のデータ には、加盟店からの入力データが含まれる場合があります。これらは未検証のユーザー入力である可能性があるため、XSS（クロスサイトスクリプティング）攻撃を防ぐために、レスポンスデータを使用する前に適切なエスケープまたはフィルタリングを行ってください。
パラメータの互換性
- リクエストの成功は、リクエストパラメータの順序に依存しません。
- リクエストの成功は、JSONオブジェクト内のキーと値の順序に依存しません。
- レスポンスを処理する際、JSONオブジェクト内のキーと値の順序を仮定しないでください。
- APIの新しいバージョンでは、リクエストやレスポンスに新しいパラメータやJSONキー/値のペアが追加される可能性があります。
- 新しいバージョンでは、既存の必須パラメータやキー/値のペアを削除しません。
- 値がnullのJSONキー/値のペアは省略可能です。
文字エンコーディング
UTF-8の1～3バイトでエンコードされる文字のみをサポートします。つまり、4～6バイトのUnicode補助平面文字はサポートされません。
日付形式
すべての日付オブジェクトには以下の形式を使用します。例：
yyyy-MM-DD HH:mm:ss
yyyy-MM-DD
時刻のタイムゾーンは常にUTC0で固定されています。リクエスト時には、ローカルタイムゾーンを+00:00に変換して送信する必要があります。レスポンス時には+00:00のタイムゾーンの時刻が返されますので、必要に応じてローカルタイムゾーンに変換して記録や表示を行ってください。
リクエストの一意識別子
PayCloudはすべてのリクエストに一意の識別子を割り当てます。この識別子はレスポンスのHTTPボディ内の psn パラメータとして返されます。PayCloudサポートが必要な場合は、このリクエスト識別子を提供いただくと、特定のリクエストを迅速に特定できます。
エラー情報
PayCloud APIは、HTTPステータスコードを使用してリクエスト処理の結果を示します。
リクエストが正常に処理された場合、HTTPレスポンスコードは200を返します。HTTPレスポンスコードは通信状態のみを示し、ビジネス操作の成功や支払いの成功を示すものではありません。例えば、HTTPコード200は通信が正常であることを意味しますが、支払い成功を示すものではありません。
エラーコードとエラーメッセージ
リクエストの処理が失敗した場合、HTTPステータスコードに加えて、エラーの詳細を示すJSON形式のレスポンスが返されます。具体的なエラー内容は次のフィールドで提供されます。
code: 詳細なエラーコード。msg: エラーの理由を示す分かりやすい説明。
{
"code":"E07303",
"msg":"The API is not authorized or does not exist",
"psn":"06100624379047675280",
"sign":"Ck2+5+lQ7tVGXEVcwYiZDLXQ1m6VIItlYEogCRtPBwKtIUbW3vRnZznl/cB0u//q8rTRiq+u4UFhOiFB8MWMC3ukzkb35zkDsWNygsftvx3sXSqOnIYBMEVXDKn91BnE/DXxZ3V76E67HCk6Cp5E2ujLwzawonVzWLxT4RLZjocu7U6rywz8UAS37+PAvqJA3v4H1IF3YbgaX62NOQyn2jEuzxe0BnHQKg92uMt0I64RZFBSKpOahwtQNlW0/4Hwv/Nu30vJju6N3ikYXzUfpH0KwTWoZUq/6mS8XaLayQb46WSECUZ+KuCg/GJKAMCIgnqGRS5rFlAex4iCwktlkA=="
}
レスポンスの言語
PayCloud APIは、レスポンス 内のエラー説明に使用する自然言語のロケールを指定する機能を提供します。必要に応じて、HTTPヘッダー Accept-Language を設定してください。現在サポートされている言語は以下の通りです。
- en-US
- zh-CN
- ja-JP
- fr-FR
設定されていない場合、または指定された値がサポートされていない場合は、デフォルトでアメリカ英語（en-US）が使用されます。