Charge

Chargeは、単一の支払いトランザクションを表します。 Chargeを使用して、オーソリ金額を確保して後で売上請求するか、オーソリを確保してすぐに売上請求します。

インテグレーションに応じて、いずれかの有効なCharge Permissionを使用する、またはCheckout Sessionの成功した結果としてChargeを作成します。Chargeが成功すると、AuthorizedからCaptureInitiated、Completed状態に移行します。canHandlePendingAuthorization がtrueに設定されている場合、Authorized 状態、また7日以上のオーソリ後に売上請求された際は保留状態になります。詳細については、非同期処理を参照してください。Chargeが拒否されて、失敗した場合はDeclined 状態に移動し、Chargeが明示的にキャンセルされた場合や ChargeがAuthorized状態で、30日後に期限切れした場合はCanceled状態に移行します。

サポートされている操作:


Chargeオブジェクト

パラメータ
説明
chargeId

Type: string
Charge識別子

この値は、完了したCheckout Sessionの終了時に返されます。または、Chargeable状態のCharge Permissionから新しいChargeを作成できます。
chargePermissionId

Type: string
Charge Permission識別子
chargeAmount

Type: price
売上請求/オーソリされる金額

最大金額:
US:$ 150,000
UK:£150,000
ドイツ:€150,000
日本:10,000,000円
captureAmount

Type: price
このChargeオブジェクトを使用して売上請求された合計金額
refundedAmount

Type: price
このChargeオブジェクトを使用して払い戻された合計金額
softDescriptor

Type: string
captureNowがtrueに設定されている場合、購入者のお支払い方法ステートメントに表示される説明。 captureNowがfalseに設定されている場合は、この値を設定しないでください。この項目には、購入者や取引に関する機密データを保存しないでください(例えば、政府発行の身分証明書、銀行口座番号、クレジットカード番号などが含まれますが、これらに限定されません)

日本では利用できません。固定値が表示されます。

デフォルト:「AMZ * <SELLER_NAME> pay.amazon.co.jp」
最大長:16文字/バイト
captureNow

Type: boolean
オーソリが成功した直後にChargeを売上請求された必要があるかどうかを示すブール値

デフォルト値:false
canHandlePendingAuthorization

Type: boolean
事業者が非同期レスポンスを処理できるかどうかを示すブール値。

falseに設定すると、US、EU、UKの地域では最大15秒以内、JPでは最大30秒以内に応答します。 trueに設定すると、Amazon Payはオーソリを非同期で処理し、24時間以内にレスポンスを受け取ります。詳細については、 非同期処理を参照してください
providerMetadata

Type: providerMetadata
決済サービスプロバイダー(PSP)- 提供された注文の詳細

PSPのみがこれらのフィールドを使用する必要があります
creationTimestamp

Type: dateTime
ISO8601形式でChargeが作成されたUTC日時
expirationTimestamp

Type: dateTime
ISO8601形式でChargeが期限切れになるUTC日時

merchantMetadata

Type: merchantMetadata
販売者が提供する注文の詳細。このパラメータは、RecurringのCharge Permissionオブジェクトを使用して作成された料金に対してのみ設定できます。
statusDetails

Type: statusDetails
Chargeオブジェクトの状態
convertedAmount

Type: price
支払い通貨で取得売上請求されたれた金額。これは、 chargeAmount / conversionRateを使用して計算されます。

詳細については、複数通貨のインテグレーションを参照してください
conversionRate

Type: double
convertedAmount金額の計算に使用されるレート

詳細については、複数通貨のインテグレーションを参照してください
releaseEnvironment

Type: string
Chargeオブジェクトが作成された環境(SandboxかLiveのいずれか)

Type: price

パラメータ
説明
amount

Type: string
取引金額
currencyCode

Type: string
ISO4217形式の取引通貨コード

例:JPY

Type: providerMetadata

パラメータ
説明
providerReferenceId

Type: string
決済サービスプロバイダー(PSP)- 提供された注文ID

PSPのみがこれらのフィールドを使用する必要があります

Type: merchantMetadata

パラメータ
説明
merchantReferenceId

Type: string
事業者オーダー識別子。事業者オーダーIDは、Amazon Payウェブサイト購入者とのコミュニケーションおよび購入者の取引履歴で共有されます。

最大長:256文字/バイト
merchantStoreName

Type: string
事業者名。このパラメータを設定すると、セラーセントラル(USEUJP)で構成されたデフォルト値が上書きされます。MerchantStoreNameは、 Amazon Payウェブサイト購入者とのコミュニケーションおよび購入者の取引履歴で共有されます

最大長:50文字/バイト
noteToBuyer

Type: string
購入者とのコミュニケーションで共有される注文の説明

購入者や取引に関する機密データを保存しないでください(例えば、政府発行の身分証明書、銀行口座番号、クレジットカード番号などが含まれますが、これらに限定されません)

最大長:255文字/バイト
customInformation

Type: string
注文のカスタム情報。このデータは、購入者とのコミュニケーションでは共有されません

購入者や取引に関する機密データを保存しないでください(例えば、政府発行の身分証明書、銀行口座番号、クレジットカード番号などが含まれますが、これらに限定されません)

最大長:4096文字/バイト

Type: statusDetails

パラメータ
説明
state

Type: string
現在のオブジェクトの状態
reasonCode

Type: string
現在の状態理由コード
reasonDescription

Type: string
Chargeの状態オプションの説明
lastUpdatedTimestamp

Type: dateTime
stateがISO8601形式で最後に更新されたUTC日時

状態と理由コード

状態
説明
理由コード
AuthorizationInitiated
Chargeは保留状態です。詳細については、非同期処理を参照してください

許可された処理:
GET Charge
DELETE Charge
-
Authorized
Chargeが正常にオーソリされました

許可された処理:
GET Charge
POST Capture
GET Charge
-
CaptureInitiated
Charge売上請求する処理は、結果に応じてCaptured 状態またはDeclined状態に移行します

許可された処理:
GET Charge
-
Captured
Chargeは正常に売上請求されました

許可された処理:
GET Charge
POST Refund
-
Canceled
Chargeはアマゾンまたは事業者によって取り消されました

許可された処理:
GET Charge
ExpiredUnused - ChargeはAuthorized状態から売上請求されずに30日間経過しました

AmazonCanceled - AmazonはChargeをキャンセルしました

MerchantCanceled - Chargeのキャンセル操作でChargeをキャンセルした、cancelPendingChargesがtrueに設定してChargeの作成しキャンセル操作でキャンセルした、または Complete Checkout Sessionを呼び出さなかったためにChargeが閉じられました。

BuyerCanceled -購入者が Chargeをキャンセルしました
Declined
オーソリまたは売上請求するが拒否されました

許可された処理:
GET Charge
SoftDeclined - ChargeはSoftDeclinedされました。再試行は成功する場合と成功しない場合があります。再試行を繰り返しても失敗する場合は、購入者に連絡して、別のお支払い方法を選択してもらう必要があります。

HardDeclined - Chargeは、HardDeclinedされました。再試行は成功しません。購入者に連絡して、別のお支払い方法を選択していただく必要があります。

AmazonRejected
- ChargeはAmazonにより拒否されました。関連するCharge Permissionもキャンセルされます。

ProcessingFailure
- Amazonがあるため内部処理エラーのChargeを処理できませんでした。Charge PermissionがChargeableのstateにある場合は、Chargeを再試行する必要があります。

TransactionTimedOut
- canHandlePendingAuthorizationが false場合、Amazon Payが処理するのに十分な時間でなかったので、Chargeが拒否されました。購入者に連絡して、別の支払い方法を選択してもらいます。この失敗が頻繁に発生する場合は、 canHandlePendingAuthorizationをtrueに設定することを検討してください。
canHandlePendingAuthorizationが trueの場合、Amazon Payは注文の有効性を判断することができず、Chargeが拒否されました。購入者に連絡して、別の支払い方法を選択してもらいます。詳細については、非同期処理を参照してください。

オペレーション

Create Charge

Chargeable状態のCharge Permissionがある場合は、オーソリを確保するためにChargeを作成することができます。オプションで、 captureNowをtrueに設定して売上請求することで、すぐに売上請求することができます。 OneTime のCharge Permissionごとに最大有効な25のChargeを作成できます。

Create Chargeのレスポンスには、 ChargeIDが含まれます。これは応答に含まれる唯一のタイミングとなり、後日、売上請求する Get ChargeCreate RefundのためにIDを格納する必要があります。またリクエストが失敗した場合は購入者に再度連絡して、もう一度決済するように依頼する必要があります。

リクエスト

リクエストボディ

{
    "chargePermissionId": "P21-1111111-1111111",
    "chargeAmount": {
        "amount": "14.00",
        "currencyCode": "USD"
    },
    "captureNow": true, // default is false
    "softDescriptor": "Descriptor",
    "canHandlePendingAuthorization": false //default is false
}

リクエストパラメータ

名前
ロケーション
説明
x-amz-pay-idempotency-key
(必須)

Type: string
Header
安全なリトライリクエストするための冪等キー 
chargePermissionId
(必須)

Type: string
Body
Charge Permission識別子
chargeAmount
(必須)

Type: price
Body
請求金額
captureNow

Type: boolean
Body
オーソリが成功した直後にChargeを売上請求された必要があるかどうかを示すブール値

デフォルト値:false
softDescriptor

Type: string
Body
CaptureNowがtrueに設定されている場合、購入者のお支払い方法ステートメントに表示される説明。 CaptureNowがfalseに設定されている場合は、この値を設定しないでください。

日本では利用できません。固定値が表示されます。

デフォルト:「AMZ * <SELLER_NAME> pay.amazon.co.jp」
最大長:16文字/バイト
canHandlePendingAuthorization

Type: boolean
Body
事業者が非同期レスポンスを処理できるかどうかを示すブール値

falseに設定すると、US、EU、UKの地域では最大15秒以内、JPでは最大30秒以内に応答します。 trueに設定すると、Amazon Payはオーソリを非同期で処理し、24時間以内にレスポンスを受け取ります。詳細については、 非同期処理を参照してください。
merchantMetadata

Type: merchantMetadata
Body
販売者が提供する注文の詳細。このパラメーターは、RecurringのCharge Permissionオブジェクトを使用して作成された料金に対してのみ設定できます。
providerMetadata

Type: providerMetadata
Body
決済サービスプロバイダー(PSP)- 提供された注文の詳細

PSPのみがこれらのフィールドを使用する必要があります

レスポンス

処理が成功した場合HTTP 201 ステータスコードを返します。 同じ 冪等キー を使用してその後再試行すると、新しいリソースが作成されない場合、HTTP 200 ステータスコードが返される場合があります。

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "Descriptor",
     "merchantMetadata": null,
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetails":{
         "state": "Captured",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z",
     "releaseEnvironment": "Sandbox"
}

エラーコード

HTTPステータスコード
理由コード
説明
400 BAD_REQUEST
TransactionAmountExceeded
このRecurring Chargeで許可されている月内最大請求金額を超えました
400 BAD_REQUEST
PeriodicAmountExceeded
Recurring Chargeに許可されている月間最大請求額を超えました。 購入者ごとの制限は月ごとにリセットされます。詳細については、毎月の定期的な請求制限を参照してください
422 UNPROCESSABLE_ENTITY
InvalidChargePermissionStatus
現在のCharge Permissionの状態では呼び出せない処理を呼び出そうとしました
422 UNPROCESSABLE_ENTITY
SoftDeclined
ChargeはSoftDeclinedされました。 再試行の試行は成功する場合と成功しない場合があります。 再試行を繰り返しても失敗する場合は、購入者に連絡して、別の支払い方法を選択してもらいます。
422 UNPROCESSABLE_ENTITY
HardDeclined
ChargeはHardDeclinedされました。 再試行は成功しません。 購入者に連絡して、別の支払い方法を選択してもらいます。
422 UNPROCESSABLE_ENTITY
TransactionCountExceeded
Charge Permissionごとに可能な、正常に請求済みChargeの上限を1超えました
422 UNPROCESSABLE_ENTITY
PaymentMethodNotAllowed
購入者が選択した支払い方法は、このChargeでは許可されていません
422 UNPROCESSABLE_ENTITY
AmazonRejected
Amazonによって請求が拒否されました。 関連する請求許可もキャンセルされます。
422 UNPROCESSABLE_ENTITY
MFANotCompleted
このトランザクションを処理するには、購入者が多要素認証(MFA)を完了する必要があります
422 UNPROCESSABLE_ENTITY
TransactionTimedOut
canHandlePendingAuthorizationをfalseに設定した場合、Amazon Payがオーソリを処理するための十分な時間がなかったため、拒否されました。 購入者に連絡して、別の支払い方法を選択してもらいます。 オーソリ拒否が頻繁に発生する場合は、canHandlePendingAuthorizationをtrueに設定することを検討してください。

canHandlePendingAuthorization</code>をtrueに設定して、Amazon Payが注文の有効性を判断できず、オーソリが拒否された場合は、購入者に連絡して、別の支払い方法を選択してもらいます。詳細については、非同期処理をご覧ください。
500 INTERNAL_SERVER_ERROR
ProcessingFailure
内部処理エラーのため、AmazonはChargeを処理できませんでした。 Charge PermissionがChargeable状態の場合にのみChargeを再試行する必要があります。

その他エラーはこちらを参照してください。

Get Charge

請求金額やオーソリ状態などのChargeの詳細を取得できます。この処理を使用して、オーソリまたは売上請求が成功したかどうかを判別します。

リクエスト

リクエストパラメータ

名前
ロケーション
説明
chargeId
(必須)

Type: string
Path Parameter
Charge識別子

レスポンス

処理が成功した場合、 HTTP 200 ステータスコードを返します。

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "Descriptor",
     "merchantMetadata": null,
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetails":{
         "state": "Captured",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z",
     "releaseEnvironment": "Sandbox"
}

エラーコード

その他エラーはこちらを参照してください。

Capture Charge

Authorized状態のChargeに対して売上請求します。売上請求に成功すると、ChargeはAuthorized 状態からCaptured状態に移行します。オーソリ後7日以上経ち売上請求されたれた場合、一時的にCaptureInitiated状態になる可能性があります。詳細については、 非同期処理を参照してください。オーソリに失敗した場合にはChargeはDeclined状態に移行します。

リクエスト

リクエストボディ

{
    "captureAmount": {
        "amount": "14.00",
        "currencyCode": "USD"
    },
    "softDescriptor": "Descriptor"
}

リクエストパラメータ

名前
ロケーション
説明
x-amz-pay-idempotency-key
(必須)

Type: string
Header
安全なリトライリクエストするための冪等キー 
chargeId
(必須)

Type: string
Path Parameter
Charge識別子
captureAmount
(必須)

Type: price
Body
請求金額
softDescriptor

Type: string
Body
CaptureNowがtrueに設定されている場合、購入者のお支払い方法ステートメントに表示される説明。 CaptureNowがfalseに設定されている場合は、この値を設定しないでください。

日本では利用できません。固定値が表示されます。

デフォルト:「AMZ * <SELLER_NAME> pay.amazon.co.jp」
最大長:16文字/バイト

レスポンス

処理が成功した場合、 HTTP 200 ステータスコードを返します。

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount":{
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "Descriptor",
     "merchantMetadata": null,
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetails":{
         "state": "Captured",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z",
     "releaseEnvironment": "Sandbox"
}

エラーコード

HTTPステータスコード
理由コード
説明
400 BAD_REQUEST
TransactionAmountExceeded
このChargeで許可されている最大請求金額を超えました
422 UNPROCESSABLE_ENTITY
TransactionCountExceeded
Charge Permissionごとに、正常に請求済みChargeの上限を1超えました
422 UNPROCESSABLE_ENTITY
InvalidChargePermissionStatus
現在のCharge Permissionの状態では呼び出せない処理を呼び出そうとしました
422 UNPROCESSABLE_ENTITY
InvalidChargeStatus
現在のChargeの状態では呼び出せない処理を呼び出そうとしました
422 UNPROCESSABLE_ENTITY
AmazonRejected
AmazonによってChargeが拒否されました。 関連するCharge Permissionもキャンセルされます。
500 INTERNAL_SERVER_ERROR
ProcessingFailure
内部処理エラーのため、AmazonはChargeを処理できませんでした。 Charge PermissionがChargeable状態の場合にのみChargeを再試行する必要があります。

その他エラーはこちらを参照してください。

Cancel Charge

オーソリ済みのChargeを解除してCanceled状態にします。 Chargeがキャプチャが開始されるまでの AuthorizationInitiatedまたはAuthorized状態のときにこの処理を実行することができます。

リクエスト

リクエストボディ

{
    "cancellationReason": "REASON DESCRIPTION"
}

リクエストパラメータ

名前
ロケーション
説明
chargeId
(必須)

Type: string
Path Parameter
Charge識別子
cancellationReason
(必須)

Type: string
Body
事業者が提供するChargeをキャンセルした理由

レスポンス

処理が成功した場合、 HTTP 200 ステータスコードを返します。

{
     "chargeId": "P21-1111111-1111111-C111111",
     "chargePermissionId": "P21-1111111-1111111",
     "chargeAmount":{
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "captureAmount": {
         "amount": "14.00",
         "currencyCode": "USD"
     },
     "refundedAmount": {
         "amount": "0.00",
         "currencyCode": "USD"
     },
     "convertedAmount": "14.00",
     "conversionRate": "1.00",
     "softDescriptor": "SOFT DESCRIPTOR",
     "merchantMetadata": null,
     "providerMetadata": {
         "providerReferenceId": null
     },
     "statusDetails":{
         "state": "Canceled",
         "reasonCode": null,
         "reasonDescription": null,
         "lastUpdatedTimestamp": "20190714T155300Z"
     },
     "creationTimestamp": "20190714T155300Z",
     "expirationTimestamp": "20190715T155300Z",
     "releaseEnvironment": "Sandbox"
}

エラーコード

HTTPステータスコード
理由コード
説明
422 UNPROCESSABLE_ENTITY
InvalidChargePermissionStatus
その処理が許可されていない状態にあるChargePermissionで処理を実行しようとしました
422 UNPROCESSABLE_ENTITY
InvalidChargeStatus
その処理が許可されていない状態にあるChargeで処理を実行しようとしました

その他エラーはこちらを参照してください。

関連トピック