API概要
オブジェクト
Amazon Payでの支払いを完了するために使用できる4つの主要なオブジェクトがあります： CheckoutSession、 ChargePermission、 Charge およびRefund 。それぞれが別個の支払い処理または合意を表しており、それぞれに関連性と使用期間が異なります。
Checkout Session
Checkout Sessionは、Webサイトの購入者に対する単一のアクティブなセッション（またはエンゲージメント）を表します。Checkout Sessionは、 OneTimeの請求、複数回の請求、またはオーソリ失敗からのリカバリーを容易にするために使用できます。
Checkout Sessionは、Open状態で開始されます。Open状態では、Checkout Sessionを使用して、配送先住所などの決済の詳細情報を取得し、注文金額などの関連する支払いの詳細を設定できます。Checkout Sessionを使用して、購入者にすぐに請求するか、後で購入者に請求するために使用できるCharge Permissionを生成することもできます。
トランザクション処理が成功した場合、 Complete Checkout Session を実行し後、>Complete Checkout SessionはCompleted状態に移行します。Completed状態では、Authorizationが要求された場合はCharge PermissionとChargeへの参照を取得するためにCheckout Sessionを使用することができます。
Checkout Sessionが24時間Open状態になった後、またはトランザクション処理が失敗した場合、Checkout SessionはCanceled状態に移行します。Canceled状態では Checkout Sessionを使用して、決済が失敗した理由を取得できます。
Amazon Payは、30日後にCheckout Sessionオブジェクトと関連情報を完全に削除することに注意してください。
Charge Permission
Charge Permissionオブジェクトは、請求される購入者との同意を表します。 OneTimeまたはRecurringのCharge Permissionオブジェクトをリクエストできます。
OneTime Charge Permissionを使用して、Charge PermissionがChargeable状態のときに、注文金額を売上請求できます。Charge PermissionがNon-Chargeable 状態の場合は、購入者に請求できない理由を理由コードを確認して特定する必要があります。注文総額の売上請求された、キャンセルされた、またはそれが180日後に期限が切れた後、OneTimeのCharge PermissionはClosed 状態に移行します。
RecurringのCharge Permissionを使用して、Charge PermissionがChargeable状態にある間、定期的に購入者に請求することができます。理由コードを確認して、Charge PermissionがNon-Chargeable 状態の場合に購入者できない理由を特定する必要があります。Recurring Charge Permissionは、キャンセルされた後、または有効期限が切れた後、Closed 状態に移行します。
いずれかのCharge Permissionタイプを使用して、購入者の名前、購入者のemail、配送先住所など、注文を完了するために必要な関連する決済の詳細を取得できます。決済の詳細を取得できるのは、 OneTime Charge Permissionが作成されてから30日後のみであることに注意してください。
Charge
Chargeは、単一の支払いトランザクションを表します。Chargeを使用して、金額のオーソリを確保し後で売上請求するか、あるいは、オーソリ確保時にすぐに売上請求することができます。
インテグレーションに応じて、いずれかの有効なCharge Permissionを使用してChargeを作成することができます。または成功したCheckout Sessionの結果として、Chargeを作成します。Chargeが成功すると、AuthorizedからCaptureInitiated、 Completed状態に移行します。canHandlePendingAuthorization trueに設定されている場合はオーソリ、またはオーソリ後7日以上に売上請求されたものは保留状態になります。詳細については、 非同期処理を参照してください。失敗したChargeは支払いが拒否された場合はDeclined状態に遷移し、Chargeが明示的にキャンセルされた場合はCanceled状態に遷移、またはChargeがAuthorized状態で30日後に期限切れになります。
Refund
Refundにより事業者は以前に獲得したChargeの一部またはすべてを購入者に返金することができます。返金は、以前に売上請求されたChargeにて開始することができ、１つのChargeに対して複数の払い戻しをすることができます。
Refundは非同期で処理します。払い戻しは、処理が成功したかどうかに応じて、Completed状態またはDeclined状態に移行する前にRefundinitiated状態で開始されます。支払い通知（IPN）を設定するか、Get Refundでのポーリングメカニズムを実装して更新を確認する必要があります。詳細については、 非同期処理を参照してください。
APIの基本
エンドポイント
| URLパラメータ
|
説明
|
| environment
|
Amazon Payが動作する環境 可能な値: "sandbox" or "live" |
| version
|
Amazon Pay API version 可能な値: "v1" or "v2" |
ヘッダー
少なくとも、Amazon Payに対して行うすべてのリクエストで、x-amz-pay-date、 content-type、およびauthorizationヘッダーを設定する必要があります。さらに、新しいリソースを作成するすべてのリクエストで x-amz-pay-idempotency-keyheaderを設定する必要があります。
| Header key
|
説明
|
| x-amz-pay-date
|
要求がISO8601形式で行われたときのUTCタイムスタンプ。このヘッダーはすべてのリクエストに必要です。 例：「20190805T051457Z」 |
| x-amz-pay-idempotency-key
|
idempotency Header keyは、リクエストを安全に再試行するために使用されます。詳細については、 冪等キー を参照してください。このヘッダーは、次のPOSTリクエストに必要です。
例：「LfOgvmFXJvfGLpLP」
|
| content-type
|
リクエストボディのコンテンツタイプ。 「application /json」である必要があります。このヘッダーはすべてのリクエストに必要です。
|
| authorization
|
authorization Header keyは、リクエストの送信者を確認するために使用されます。このヘッダーはすべてのリクエストに必要です。 例： "AMZN-PAY-RSASSA-PSS PublicKeyId=AHEGSJCM3L2S637RBGABLAFW, SignedHeaders=accept;content-type;x-amz-pay-date;x-amz-pay-host;x-amz-pay-region, Signature=lDCyYfDN7ni7zfWQz/KvC89qSrZZidsYmZqqORBye/7zHCAR26svJh5DDZnEHkTvcJI/H/NyxzmPyAJpLEGaD7G3NKboIXLxuZYLUY2uS1NLkUMGAkP18NSie0AwuRuD2dngHw6ZIYJWtYBUCbDfAcsH6aCZjjRP+MjKqaIc6Pdwqcch/jXkDKhC0NhlCRQr1v50sI1cFK6rWhzc3qIQ/OGPdb5Oi+NfKWzg7oCxZrbvS6qpSi8u+Wr1qxIf51atWWtkbZH/ZWB6e6Q8V+ssOez/+0apXkOIc+Y2wPMP4SV7xqHDnvqTWOfZpRp/mFo7m/P9ayc730jrwQ65lalj5w==" |
| x-amz-simulation-code
|
simulation-codeヘッダーは、特定の応答をトリガーするために使用されます。詳細については、SANDBOXシミュレーションの使用 を参照してください。これはオプションのヘッダーです。 例： "AmazonCanceled" |
リクエストの検証
Amazon Payは、authorization headerを使用してリクエストの送信者を確認します。リクエストヘッダーの生成方法の詳細については、 リクエストへの署名を参照してください
APIスロットル制限
Amazon Pay APIには、バーストトラフィックから保護し、サービスの可用性を確保するためのスロットル制限 があります。抑制されたリクエストはHTTPステータスコード429を返します。抑制されたリクエストの処理方法については、 エラー処理 を参照してください。
通信プロトコル
Amazon Payは、安全な通信を確保するためにTLS1.0を使用して行われたリクエストをブロックします。 TLS 1.2の使用をお勧めしますが、Amazon Payへのリクエストには少なくともTLS1.1以降を使用する必要があります。
SDK
Amazon Pay SDKを使用して、インテグレーションを簡素化します。
# Install using Composer
composer require amzn/amazon-pay-api-sdk-php
# Install using Visual Studio Package Manager Console
PM> Install-Package Amazon.Pay.API.SDK -Version 2.3.2
# Install using .NET Core CLI
> dotnet add package Amazon.Pay.API.SDK --version 2.3.2
# Install using Maven
<dependency>
<groupId>software.amazon.pay</groupId>
<artifactId>amazon-pay-api-sdk-java</artifactId>
<version>2.2.2</version>
</dependency>
# Install using Gradle
implementation 'software.amazon.pay:amazon-pay-api-sdk-java:2.2.2'
// Install module as a dependency
npm i @amazonpay/amazon-pay-api-sdk-nodejs