設定されたお支払い方法を用いて支払いを管理する
[ステップ 4/7] 購入者がお支払い方法設定の保存を完了すると、Complete Checkout Sessionのレスポンスに、お支払い方法設定にで生成されたCharge PermissionオブジェクトのChargePermissionIdが含まれて返却されます。このIdをもとに購入者への請求とキャンセルの管理に行うことができます。
このステップを完了すると、購入者への請求とキャンセルの管理が可能になります。
1. 請求とオーソリ失敗のハンドリング
購入者に請求する必要がある場合は、毎回 Create Charge APIを実行します。CaptureNowパラメーターをtrueに設定すると売上請求も同時に実施されます。falseに設定する場合は、別途売上請求処理を実施する必要があります。
注意：Amazon Payでは、各月に購入者に請求できる金額の上限が設定されていることに注意してください。詳細については、PaymentMethodOnFileの月額上限を参照してください。
Create Chargeが201 レスポンスを返却した場合、オーソリは正常に取得されています。canHandlePendingAuthorizationがtrueの場合は、非同期オーソリのリクエストが正常に受け付けられています。 もし、Create Chargeがそれ以外のHTTPステータスコードを返却した場合は、以下のようにレスポンスの理由コード(ReasonCode)を確認してCreate Chargeを再試行すべきか購入者に別の支払い方法を利用してもらうべきかを判断します。
- もし
reasonCodeが SoftDeclined または ProcessingFailure の場合、以下のことを行います：- Get Charge Permissionを実行して、ChargePermissionがChargeableステータスにあることを確認します
- Create Chargeを実行し、購入者への請求を再試行します。
- もし
reasonCodeが HardDeclined がHardDeclinedの場合、次のリンクを使用して支払い方法を更新するように購入者に依頼してください： https://pay.amazon.com/jp/jr/your-account/ba/{ChargePermissionId}。※{ChargePermissionId}の部分を購入者のPMOF ChargePermissionIdに置き換えます。 支払い方法が更新されたら通知を受け取るようにIPNを設定し、以下のことを行います：- Get Charge Permissionを実行して、ChargePermissionがChargeableステータスにあることを確認します
- Create Chargeを実行し、購入者への請求を再試行します。
- 上記以外の
reasonCodeだった場合、購入者に連絡し、別の決済方法で再度決済を行ってもらうようご案内します
リクエスト
curl "https://pay-api.amazon.com/:environment/:version/charges/" \
-X POST
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"
-d @request_body
リクエストボディ
{
"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
|
ChargePermission識別子
|
| chargeAmount (必須) Type: price |
Body
|
請求金額
|
| captureNow Type: boolean |
Body
|
オーソリが成功した直後に売上請求をする必要があるかどうかを示すブール値 デフォルト: false |
| softDescriptor Type: string |
Body
|
CaptureNowをtrueに設定している場合、購入者のお支払い方法ステートメントに表示される説明。CaptureNowがfalseに設定されている場合は、この値を設定しないでください。この項目には、購入者や取引に関する機密データを保存しないでください(例えば、政府発行の身分証明書、銀行口座番号、クレジットカード番号などが含まれますが、これらに限定されません)※日本では利用できません。固定値が表示されます。 このsoft descriptorは以下の形式で連携されます。: "AMZ* <soft descriptor specified here>" Default: "AMZ*<SELLER_NAME> pay.amazon.com" 最大長: 16 文字 |
| canHandlePendingAuthorization Type: boolean |
Body
|
事業者が保留のレスポンスを処理できるかどうかを示すブール値 falseに設定すると、US,EU,UK地域では最大15秒以内、JP地域では最大30秒以内にレスポンスが返されます。trueに設定すると、Amazon Payはオーソリを非同期で処理し、24時間以内にレスポンスを返します。詳細については、非同期処理を参照してください |
| merchantMetadata Type: merchantMetadata |
Body
|
事業者が設定する注文の詳細情報
|
| providerMetadata Type: providerMetadata |
Body
|
決済サービスプロバイダー（PSP）が設定する注文の詳細情報 PSPのみがこれらのフィールドを使用します |
| chargeInitiator Type: string |
Body
|
請求の指示者を示します。
サポートされている値: 'CITU', 'MITU', 'CITR', 'MITR' CITU: これは、customer-initiated unscheduled(購入者の指示によるタイミングの決まっていない請求)の場合に利用します。購入者の操作に寄って事業者が課金をする場合にはこの値を設定して下さい。Amazon Payは購入者の意図によりこの取引が行われたと判断します。 MITU: これは、merchant-initiated unscheduled(事業者の指示によるタイミングの決まっていない請求)の場合に利用します。購入者の具体的な決済操作がなく、事業者が決済方法の確認を行わない場合にこの値を設定して下さい。 Amazon Payは、全ての支払い取引において、事業者と購入者の間で購入者が事業者からの不定期な請求に同意したものとみなします。 このケースでは様々なユースケースが考えられます。例えば、
MITR: これは、merchant-initiated transaction(定期的な決済に対する２回目以降の事業者の指示による請求)の場合に利用します。 定期的な請求を行うサービスの場合に２回目以降の請求を行う場には、この値を設定して下さい。 |
| channel Type: string |
Body
|
請求時のチャネルを指します。
サポートされている値: 'Web', 'App', 'Firetv', 'Offline' 下記のケースに応じて値を設定して下さい。
|
| checkoutResultReturnUrl Type: string |
Body
|
(EU/UKの事業者のみ)事業者から提供された決済結果のURL。トランザクションの完了後、Amazon PayはこのURLにリダイレクトします。 このパラメーターは、購入者が多要素認証を求められた場合に請求処理をハンドリングするために必須となります。 |
レスポンス
{
"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"
}
購入者が多要素認証を求められた場合のハンドリング (EU/UKの事業者のみ)
chargeInitiatorが"CITU"か"CITR"で請求を実施する場合, 購入者は設定しているお支払い方法への認証を求められるケースがあります。この場合、Create Charge は、202 ステータスコードをレスポンスで返します。この際、chargeのstate: "ActionRequired"、reasonCode: "BuyerActionRequired"となります。
請求を完了させるには、
- chargeレスポンスに返却された
amazonPayRedirectUrlに購入者をリダイレクトします。Amazon Payは購入者に多要素認証を実施するためのページを表示します。多要素認証が完了したら、checkoutResultReturnUrlにリダイレクトを行います。 - 購入者が事業者のサイトに戻ってきたことの確認として、Complete Checkout Sessionを実行します。
リクエスト
curl "https://pay-api.amazon.com/:version/charges/" \
-X POST
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-H "x-amz-pay-idempotency-key:AVLo5tI10BHgEk2jEXAMPLEKEY"
-d @request_body
リクエストボディ
{
"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
"webCheckoutDetails": {
"checkoutResultReturnUrl": "URL"
}
}
レスポンス
{
"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": "ActionRequired",
"reasonCode": "BuyerActionRequired",
"reasonDescription": "Charge requires buyer action to proceed.",
"lastUpdatedTimestamp": "20190714T155300Z"
},
"webCheckoutDetails": {
"checkoutResultReturnUrl": "URL",
"amazonPayRedirectUrl": "URL" // post-order URL to complete MFA
}
"creationTimestamp": "20190714T155300Z",
"expirationTimestamp": "20190715T155300Z",
"releaseEnvironment": "Sandbox"
}
購入者が多要素認証を完了すると、Amazon PayはcheckoutResultReturnUrlにリダイレクトを行います。checkout session ID はクエリパラメータに含まれて事業者に連携されます。 購入者が認証を完了して事業者のサイトに戻ってきたことの確認として、Complete Checkout Sessionを実行します。
Notes: Amazon Payは、 Complete Checkout Sessionによって事業者による確認がされるまで処理を確定しません。24時間以内に確認がされない場合、Checkout Sessionはキャンセルされ、オーソリもキャンセルされます。
成功のレスポンス:
トランザクションが正常に処理された場合、 Complete Checkout Session は成功レスポンスを返します。
エラーレスポンス:
Complete Checkout Session は、失敗したトランザクションに対しては、エラーレスポンスを返します。購入者は多要素認証を途中でキャンセルしたか、正常に完了できませんでした。この場合は、次の手順を実施してください。
- 購入者を決済の開始時点にリダイレクトします
- 「Amazon Payでのお支払いに失敗しました。別のお支払い方法をお試しください。」などのメッセージを表示します。
2. キャンセルの管理
PaymentMethodOnFile利用者が保存をキャンセル/解除した場合は、Close Charge Permissionを使用してAmazon Payに連携します。 ChargePermissionを閉じた後、お支払い方法設定の保存を新たに行わない限り、PaymentMethodOnFile利用者に請求することはできなくなります。
PaymentMethodOnFile利用者は、https://pay.amazon.comにサインインして、PMOF ChargePermissionを閉じることもできます。ChargePermissionが閉じられた場合に通知を受信するように IPNを設定します。請求不可の状況を最小限に抑えるために、次の請求サイクルの前に、新しい支払い方法の設定について利用者に積極的に連絡することをお勧めします。
3. 支払い方法の変更
購入者向けAmazon Payマイページでの支払い方法の変更
購入者は、Amazon Payのサイト https://pay.amazon.co.jp/ から、選択した支払い方法を更新できます。その後の請求は、更新された支払い方法を使用して処理されます。更新以前の請求に関連する支払い方法は変更されません。また、購入者に直接PMOF ChargePermissionに紐づく次のリンクを提供して、支払い方法を簡単に更新してもらう事もできます。URL：https://pay.amazon.com/jp/jr/your-account/ba/{ChargePermissionId}。 ※{ChargePermissionId}の部分を購入者のPMOF ChargePermissionIdに置き換えます。
4. Payment Method On Fileの有効期限
chargePermissionType： paymentMethodOnFile となっているChargePermissionの場合、有効期限はありません。ChargePermissionがクローズされるまで利用することが可能です。(expirationTimestampはnullとなります)