Manage Payments Using Saved Wallet
[Step 4 of 7] After the buyer has successfully completed setup of Saved Wallet, the Complete Checkout Session response will include a ChargePermissionId for a Saved Wallet Charge Permission object that you can use to charge the buyer and manage cancellations.
At the end of this step, you will be able to charge the buyer and manage cancellations.
- 1. Managing charges and handling declines
- 2. Managing cancellations
- 3. Changing the Payment Method or Shipping Address
- 4. Saved Wallet Expiration
1. Managing charges and handling declines
Call Create Charge each time you need to charge the customer. Set CaptureNow to true to capture payment immediately, set it to false to capture later. Note that Amazon Pay limits how much you can charge the buyer for each calendar month, see monthly Saved Wallet charge limits for more info.
If Create Charge returns a 201 response, authorization was either successfully completed or successfully initiated depending on whether canHandlePendingAuthorization was set to true. If Create Charge returns a different HTTP status code, check the request response reasonCode to determine if you should retry Create Charge or ask your buyer to use a different payment method.
Request
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
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
}
Request parameters
| Name
|
Location
|
Description
|
| x-amz-pay-idempotency-key (required) Type: string |
Header
|
Idempotency key to safely retry requests
|
| chargePermissionId (required) Type: string |
Body
|
Charge Permission identifier
|
| chargeAmount (required) Type: price |
Body
|
Transaction amount
|
| captureNow Type: boolean |
Body
|
Boolean that indicates whether or not Charge should be captured immediately after a successful authorization Default: false |
| softDescriptor Type: string |
Body
|
Description shown on the buyer payment instrument statement. You can only use this parameter if CaptureNow is set to trueDo not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to: government-issued identification, bank account numbers, or credit card numbers The soft descriptor sent to the payment processor is: "AMZ* <soft descriptor specified here>" Default: "AMZ*<SELLER_NAME> pay.amazon.com" Max length: 16 characters |
| canHandlePendingAuthorization Type: boolean |
Body
|
Boolean that indicates whether or not merchant can handle pending response If set to false, you will receive a response within a maximum of 15 seconds in US, EU, and UK regions or 30 seconds in JP region. If set to true, Amazon Pay will process the authorization asynchronously and you will receive a response within 24 hours. See asynchronous processing for more info |
| merchantMetadata Type: merchantMetadata |
Body
|
Merchant-provided order details
|
| providerMetadata Type: providerMetadata |
Body
|
Payment service provider (PSP)-provided order details Only PSPs should use these fields |
| chargeInitiator Type: string |
Body
|
Represents who initiated the charge.
Supported values: 'CITU', 'MITU', 'CITR', 'MITR' CITU: A customer-initiated unscheduled transaction is a transaction where the customer is present and provides their payment credentials. This can be through a terminal in-store, or online through a checkout experience. The customer-initiated transaction is the proof that the customer and merchant entered into a relationship and that the payment credential presented was in fact a validly presented payment instrument. MITU: A merchant-initiated unscheduled transaction is a transaction where the customer is not present and is conducted without any additional cardholder validation. In all cases, a merchant-initiated transaction must refer to a customer’s original interaction where a customer and merchant have entered into an agreement for a recurring product or service or an automated billing or unscheduled transactions etc. There are many different kinds of merchant-initiated transactions. Examples include:
MITR: A merchant-initiated transaction for a recurring transaction. Use this for all subsequent recurring charges, regardless of how the first recurring charge was initiated. |
| channel Type: string |
Body
|
Represents the channel of the charge.
Supported values: 'Web', 'Phone', 'App', 'Alexa', 'PointOfSale', 'Firetv', 'Offline' When to use these channels:
|
| checkoutResultReturnUrl Type: string |
Body
|
Checkout result URL provided by the merchant. Amazon Pay will redirect to this URL after completing the transaction. The parameter is required in case you need to handle charge when MFA challenge is required to be completed by buyer (for EU and UK merchants only) Note: In the Live environment, URLs must use HTTPS protocol. In Sandbox environment, you don't need a SSL certificate and can use the HTTP protocol if you're testing on localhost (http://localhost) Max length: 1024 characters/bytes |
Response
{
"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"
}
Amazon Pay provides a decline handling flow that enables you to handle failed charges initiated via Create Charge API call while the buyer is present. Buyers can retry the transaction up to two times in order by selecting a valid payment method.
If you are a registered merchant in the EU/UK region with the chargeInitiator set as MITU or MITR, or a registered merchant in the NA/JP regions with any chargeInitiator value, and the Create Charge API returns a 4XX response, follow these steps based on the reason code received:
- If
reasonCodeis SoftDeclined or ProcessingFailure:- Call Get Charge Permission to confirm that the Charge Permission is in a Chargeable state
- Call Create Charge to charge the buyer
- If
reasonCodeis HardDeclined, ask the buyer to update their payment instrument using the following link: https://payments.amazon.com/jr/your-account/ba/{ChargePermissionId}. Replace {ChargePermissionId} with the buyer's Charge Permission Id. Set up IPNs to receive a notification once the payment instrument has been updated and then:- Call Get Charge Permission to confirm that the Charge Permission is in a Chargeable state
- Call Create Charge to charge the buyer
For any other reasonCodes or non-4XX HttpStatusCodes, please review the CreateCharge error code to determine if you should retry the Create Charge API call or ask your buyer to use a different payment method.
If you are a registered merchant in the EU/UK region with the chargeInitiator as CITU or CITR, and the Create Charge API returns a 4XX response with the amazonPayRedirectUrl and any of the reasonCodes: SoftDeclined, HardDeclined, PaymentMethodNotAllowed, or MFANotCompleted, redirect the buyer to the provided amazonPayRedirectUrl to finalize the charge.
For buyers with EU-issued payment instruments subject to PSD2 regulation, Amazon Pay will first present a Multi-Factor Authentication (MFA) challenge to the buyer.
Amazon Pay will render the decline handling page to the buyer to retry the transaction with the different payment method.
Request
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
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"
}
}
Response
{
"reasonCode": "SoftDeclined",
"message": "Charge was soft declined. Retry attempts may or may not by succesful. If repeated retry attempts are unsuccessful, please contact the buyer and have them choose a different payment method.",
"webCheckoutDetails": {
"checkoutResultReturnUrl": "URL",
"amazonPayRedirectUrl": "https:payments.amazon.co.uk/checkoutprocessing?chargeId=P02-1111111-1111111-C111111&declineAction=retryCharge"
}
}
Use Complete Checkout Session to confirm that the buyer has successfully returned to your site.
Notes: Amazon Pay will not finalize the Charge request until you confirm with Complete Checkout Session. If the request is not sent within 24 hours the payment authorization will be cancelled.
Successful response:
Complete Checkout Session will return a success response if the charge was processed successfully.
Error response:
Complete Checkout Session will return an error response for failed transactions. The buyer either canceled checkout or was unable to provide a valid payment instrument. You should:
- Redirect the buyer to the start of checkout
- Display a message such as: "Your payment was not successful. Please try another payment method."
Handling charge when MFA Challenge is required to be completed by buyer (for EU and UK merchants only)
When chargeInitiator is CITU or CITR, buyers might be required to authenticate their payment methods (like Strong Customer Authentication as part of PSD2 regulation in Europe), Create Charge will return a 202 response. Amazon Pay will move the charge to ActionRequired with reasonCode as BuyerActionRequired . To finalize the charge you need to
- Redirect the buyer to amazonPayRedirectUrl provided as part of charge. Amazon Pay will render the MFA challenge page for the buyer.
- Use Complete Checkout Session to confirm that the buyer has successfully returned to your site.
Request
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
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"
}
}
Response
{
"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"
}
The buyer is redirected to checkoutResultReturnUrl after the MFA challenge has been solved and Amazon Pay processed the transaction. The Amazon Pay checkout session ID will be included as a query parameter.
Use Complete Checkout Session to confirm that the buyer has successfully returned to your site.
Notes: Amazon Pay will not finalize the Charge request until you confirm with Complete Checkout Session. If the request is not sent within 24 hours the payment authorization will be cancelled.
Successful response:
Complete Checkout Session will return a success response if the charge was processed successfully.
Error response:
Complete Checkout Session will return an error response for failed transactions. The buyer either canceled checkout or was unable to provide a valid payment instrument. You should:
- Redirect the buyer to the start of checkout
- Display a message such as: "Your payment was not successful. Please try another payment method."
2. Managing cancellations
Use Close Charge Permission to inform Amazon Pay if a buyer cancels/removes their Saved Wallet. You will no longer be able to charge a buyer unless they consent again to setup Saved Wallet.
Buyers can also close Charge Permissions by signing in to https://pay.amazon.com.
Set up IPNs to receive notifications whenever a Charge Permission is closed. To minimize churn, we recommend that you proactively reach out to the subscriber for a new payment method before the next billing cycle.
3. Changing the Payment Method or Shipping Address
Changing the payment method with Amazon's YAUI
Buyers can update their payment method on Saved Wallet from https://pay.amazon.com section of the Amazon Pay website. Any subsequent charges are processed using the updated payment method. The payment method associated with any previous charges are not updated. A direct link can also be provided to the buyer to allow easy updates of associated payment method using the following URL: https://payments.amazon.com/jr/your-account/ba/{ChargePermissionId}. Replace {ChargePermissionId} with the buyer's Charge Permission Id.
Changing the payment method or shipping address on Amazon Pay's hosted update page
You can also allow buyers to change payment method or shipping address on Amazon Pay’s hosted Update page. For details on how to integrate this solution, please refer to Steps to integrate with Amazon Pay’s hosted Update page.
4. Saved Wallet Expiration
Charge Permissions with a type of paymentMethodOnFile do not have a set expiration and will persist until closed.