API概要


オブジェクト

Amazon Payでの支払いを完了するために使用できる4つの主要なオブジェクトがあります: CheckoutSessionChargePermissionCharge および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にて開始することができ、1つの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

ソースコード: https://github.com/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

ソースコード: https://github.com/amzn/amazon-pay-api-sdk-dotnet

# 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'

ソースコード: https://github.com/amzn/amazon-pay-api-sdk-java

// Install module as a dependency
npm i @amazonpay/amazon-pay-api-sdk-nodejs

ソースコード: https://github.com/amzn/amazon-pay-api-sdk-nodejs