Step 5: Validate the billing agreement
Authorizing determines if the payment instrument is valid, so if you plan to authorize the payment, you can skip this step.
As an optional step, you can validate the payment method chosen by the buyer and the status of the billing agreement by calling the ValidateBillingAgreement operation before you show the thank-you page to the buyer. Doing this ensures that the payment method that the buyer chose is valid at that time and will reduce the likelihood of payment failure when you try to charge the buyer later.
The following example shows how to call the ValidateBillingAgreement operation:
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&AmazonBillingAgreementId=C01-8824045-7416542
&Action=ValidateBillingAgreement
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-12-11T10%3A38%3A44.000Z
&Version=2013-01-01
&Signature=gP11oEBaaiQdASWsLDyid18Wn%2BB%2FKZQQtKgpHCtDHdc%3D
The ValidateBillingAgreement operation returns a Success or Failure value as a part of the ValidationResult parameter. If Failure is returned, you also receive a reason code. Here are suggestions to handle the various reason codes:
- InvalidPaymentMethod - Indicates that the payment method that the buyer chose is not valid (for example, it has expired, has an invalid billing address, and so on). In this case, the Billing Agreement object also moves to the Suspended state and any AuthorizeOnBillingAgreement operation is declined. You should ask the buyer to update the payment method associated with the BillingAgreement object by following the same process as described in Step 7: Prepare to handle declined authorizations.
- ValidationTimedOut - If Amazon Pay cannot validate the billing agreement within a few seconds, you receive the Failure ValidationResult. We suggest that you retry this request after some time. If the request is unsuccessful after a few retries, it is likely that there is an issue with the buyer's payment method. Ask the buyer to update the payment method from the Amazon Pay website or your website and then retry the request.