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 for future purchases and manage cancellations.
At the end of this step, you will be able to charge the buyer and manage cancellations.
- 1. Managing Charge Permission state
- 2. Managing charges and handling declines
- 3. Changing the Payment Method
- 4. Saved Wallet Expiration
1. Managing Charge Permission state
Before proceeding with Create Charge, call Get Charge Permission to confirm that the Charge Permission is in a Chargeable state. If not, follow the below steps to get a Chargeable Charge Permission
If the Charge Permission is NonChargeable with any of the following reasonCodes
- PaymentMethodInvalid
- PaymentMethodDeleted
- BillingAddressDeleted
- PaymentMethodExpired
- PaymentMethodNotAllowed
- PaymentMethodNotSet
- MFAFailed
Then guide the buyer to change their payment method 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.
- If the Charge Permission is Closed due to any reason, then guide the buyer to go through Amazon Pay’s hosted Setup Only page to setup a new charge permission. For details on how to integrate with solution, please refer to Steps to integrate with Amazon Pay’s Setup only flow.
2. 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 information).
If Create Charge returns a 201 response, the 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.
- 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, then ask the buyer to update their payment instrument 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. and then:- Call Get Charge Permission to confirm that the Charge Permission is in a Chargeable state
- Call Create Charge to charge the buyer
3. Changing the Payment Method
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 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.