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のいずれか） |
| chargeInitiator Type: string |
請求の指示者を示します。
サポートされている値: 'CITU', 'MITU', 'CITR', 'MITR' CITU: これは、customer-initiated unscheduled(購入者の指示によるタイミングの決まっていない請求)の場合に利用します。購入者の操作に寄って事業者が課金をする場合にはこの値を設定して下さい。Amazon Payは購入者の意図によりこの取引が行われたと判断します。 MITU: これは、merchant-initiated unscheduled(事業者の指示によるタイミングの決まっていない請求)の場合に利用します。購入者の具体的な決済操作がなく、事業者が決済方法の確認を行わない場合にこの値を設定して下さい。 Amazon Payは、全ての支払い取引において、事業者と購入者の間で購入者が事業者からの不定期な請求に同意したものとみなします。 このケースでは様々なユースケースが考えられます。例えば、
MITR: これは、merchant-initiated transaction(定期的な決済に対する２回目以降の事業者の指示による請求)の場合に利用します。 定期的な請求を行うサービスの場合に２回目以降の請求を行う場には、この値を設定して下さい。 |
| channel Type: string |
請求時のチャネルを指します。
サポートされている値: 'Web', 'Phone', 'App', 'Alexa', 'PointOfSale', 'Firetv', 'Offline' 下記のケースに応じて値を設定して下さい。
|
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 |
事業者名。このパラメータを設定すると、セラーセントラル（US 、 EU 、 JP）で構成されたデフォルト値が上書きされます。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 DELETE 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 - Cancel ChargeでChargeをキャンセルした、または Complete Checkout Sessionを呼び出さなかった為、Chargeはキャンセルとなりました ChargePermissionCanceled - cancelPendingChargesをtrueに設定したClose Charge PermissionでCharge Permissionをクローズした為、紐づく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 Charge、Create RefundのためにIDを格納する必要があります。またリクエストが失敗した場合は購入者に再度連絡して、もう一度決済するように依頼する必要があります。
リクエスト
リクエストボディ
{
"chargePermissionId": "P21-1111111-1111111",
"chargeAmount": {
"amount": "14.00",
"currencyCode": "USD"
},
"chargeInitiator":"CITU",
"channel":"Web",
"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
|
請求金額
|
| chargeInitiator (必須) Type: string |
Body
|
請求の指示者を示します。
サポートされている値: 'CITU', 'MITU', 'CITR', 'MITR' CITU: これは、customer-initiated unscheduled(購入者の指示によるタイミングの決まっていない請求)の場合に利用します。購入者の操作に寄って事業者が課金をする場合にはこの値を設定して下さい。Amazon Payは購入者の意図によりこの取引が行われたと判断します。 MITU: これは、merchant-initiated unscheduled(事業者の指示によるタイミングの決まっていない請求)の場合に利用します。購入者の具体的な決済操作がなく、事業者が決済方法の確認を行わない場合にこの値を設定して下さい。 Amazon Payは、全ての支払い取引において、事業者と購入者の間で購入者が事業者からの不定期な請求に同意したものとみなします。 このケースでは様々なユースケースが考えられます。例えば、
MITR: これは、merchant-initiated transaction(定期的な決済に対する２回目以降の事業者の指示による請求)の場合に利用します。 定期的な請求を行うサービスの場合に２回目以降の請求を行う場には、この値を設定して下さい。 * ChargePermissionType が PaymentMethodOnFile の場合のみ設定が必要です。
|
| channel Type: string |
Body
|
請求時のチャネルを指します。
サポートされている値: 'Web', 'Phone', 'App', 'Alexa', 'PointOfSale', 'Firetv', 'Offline' 下記のケースに応じて値を設定して下さい。
|
| 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",
"chargeInitiator":"CITU",
"channel":"Web",
"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 Permissionに対して許可されている最大請求金額を超えました
|
| 400 BAD_REQUEST
|
PeriodicAmountExceeded
|
Recurring Charge Permissionに対して許可されている月間最大請求額を超えました。 購入者ごとの制限は月ごとにリセットされます。詳細については、毎月の定期的な請求制限を参照してください
|
| 400 BAD_REQUEST
|
InvalidParameterValue
|
APIコールのパラメータのうち、少なくとも1つに無効な値を送信しました。
詳しくはAPIレスポンスのmessage要素をご確認ください。 |
| 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",
"chargeInitiator":"CITU",
"channel":"Web",
"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",
"chargeInitiator":"CITU",
"channel":"Web",
"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をキャンセルした理由 最大長: 255 文字/バイト |
レスポンス
処理が成功した場合、 HTTP 200 ステータスコードを返します。
{
"chargeId": "P21-1111111-1111111-C111111",
"chargePermissionId": "P21-1111111-1111111",
"chargeInitiator":"CITU",
"channel":"Web",
"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で処理を実行しようとしました
|
その他エラーはこちらを参照してください。