Enabling advanced payment scenarios

With the billing agreement, you can easily handle a variety of post-purchase and other advanced payments scenarios. The following scenarios are covered:

Upgrading or downgrading service

If a buyer asks to upgrade or downgrade their subscription or service plan, you might want to charge the buyer a different amount going forward corresponding to the upgrade or downgrade. Also, if the buyer contacts you midway during their billing cycle, you might want to prorate the charges at the end of your billing period.

The billing agreement offers you the flexibility to handle this scenario. After you have updated your billing system with the necessary information, you can simply initiate a request to charge the buyer by calling the Capture operation for the appropriate amount.

Note: Amazon imposes a $1000 limit per calendar month on the amount of funds you can charge a buyer. If you expect to exceed this limit because of an upgrade or the buyer's usage, contact Amazon Pay.

Canceling or suspending service

If a buyer contacts you to suspend their service, you can just stop submitting the payment request to Amazon until the service is resumed. If a buyer contacts you to cancel their service, we recommend that you close the billing agreement by calling the CloseBillingAgreement operation. The billing agreement status is then updated in the Account Activities section of the Amazon Pay website.

The following code sample shows how to request the CloseBillingAgreement operation:

 
https://mws.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&AmazonBillingAgreementId=C01-8824045-7416542 
&ClosureReason=Closing OR for Test 
&Action=CloseBillingAgreement 
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256 
&SignatureVersion=2 
&Timestamp=2013-12-11T12:32:42.000Z 
&Version=2013-01-01 
&Signature=yrpMpoDfGLu567t611z27v4yJ8SURIVMKcy26sJrwYc=

Buyers can also terminate their billing agreement from the Amazon Pay website or by contacting Amazon Pay customer service. In that case, Amazon marks the billing agreement as closed on behalf of the buyer.

When the billing agreement is closed, the buyer receives a Merchant agreement canceled email.

Note: Amazon Pay lets you specify various pieces of information in the emails sent by Amazon Pay, like your customer service email address, phone number, or note from the seller. For more information about these details, see Buyer-facing email content that you can provide.

In all of these cases, you receive an Instant Payment Notification (IPN). For more information about IPN, see Synchronizing your systems with Amazon Pay.

Changing the payment method

If a buyer wants to update the payment method associated with their billing agreement because the previous payment method was declined or for any other reason, they can update the payment method from the Amazon Pay website or from your website.

Note: Do not show the Authorize Recurring Payments widget when the buyer changes the payment method. The buyer doesn't need to confirm consent when changing their selection. Buyers can edit the billing agreement consent on the Amazon Pay website.

Update the payment method from the Amazon Pay website

Buyers can update their payment method when the billing agreement is in the Open or Suspended state from the Account Activities section of the Amazon Pay website. When the buyer updates the payment method, you receive an Instant Payment Notification (IPN). For more information about IPNs, see Synchronizing your systems with Amazon Pay. Any subsequent authorizations are processed using the updated payment method. The payment method associated with any previous authorizations is not updated.

Update the payment method from your website

If you prefer that the buyer update the payment method from your website, you can use the Wallet widget.

  • Ask the buyer to sign in by placing the Login with Amazon button on your site. If the user is signing in using their credentials on your site, you need to have them authenticate with Amazon. To do so, you can use the Amazon Edit/Update button described in Step 1: Add a Button widget for buyer authentication.
  • Show the Amazon Wallet widget where you want the buyer to update the payment method. For an example, see Step 2: Add the AddressBook and Wallet widgets. Make sure that you are passing the amazonBillingAgreementId as an input to the widget to identify the billing agreement that the buyer wants to edit.
  • Each time the buyer chooses a payment method from the Wallet widget, Amazon triggers the onPaymentSelect callback.
  • The buyer can choose several payment methods in the widget before making the final selection. After the buyer has made the final selection by clicking the Place Order, Update, or similar button, call the ConfirmBillingAgreement.

Do not call the SetBillingAgreementDetails operation because the billing agreement object is not in a Draft state and you can no longer set additional attributes.

You receive an Instant Payment Notification indicating the updated payment method, and the buyer receives a Merchant agreement updated email.

Changing the shipping address

If a buyer wants to update the shipping address associated with their billing agreement, they can use the Amazon AddressBook widget from your website. Currently, buyers can't update the shipping address from the Amazon Pay website.

Update the shipping address

  • Ask the buyer to sign in by placing the Login with Amazon button on your site.
  • Show the Amazon AddressBook widget where you want the buyer to update the address. For an example, see Step 2: Add the AddressBook and Wallet widgets.
  • Each time the buyer chooses an address from the AddressBook widget, Amazon triggers the onAddressSelect callback.
  • Amazon requires that each time a buyer chooses an address, you render the Amazon Wallet widget and let the buyer choose the allowed payment method for that address. Each time the buyer chooses a payment method, Amazon triggers the onPaymentSelect callback from the Wallet widget. Make sure that you always wait for onPaymentSelect before proceeding to the next step of confirming the billing agreement. If you attempt to confirm the billing agreement before the buyer has chosen the payment method, the ConfirmBillingAgreement operation returns a PaymentMethodNotUpdated error. If the buyer has updated the payment method, you also receive an IPN for payment method update.
  • The buyer might click several addresses in the widget before making the final selection. After the buyer has made the final selection by clicking the Update or similar button, call the ConfirmBillingAgreement operation.

Don't call the SetBillingAgreementDetails operation as the billing agreement object is not in a Draft state, and you can no longer set additional attributes.

You receive an Instant Payment Notification indicating the updated address. If the buyer has updated the payment method, you also receive another Instant Payment Notification for payment method update.

  • Note that the BillingAgreement is updated with the new address and payment method only after you call the ConfirmBillingAgreement operation. You are able to get the new address using the GetBillingAgreement operation only after you call the ConfirmBillingAgreement operation.
  • The buyer receives an email from Amazon, similar to the email they receive when they update the payment method.

Simultaneous one-time and recurring purchases

The billing agreement enables you to process payments for one-time as well as recurring purchases. For example, you might sell a book (one-time payment) along with a magazine subscription (for which a buyer pays an amount each month for the next 24 months). If the buyer purchases both items, the integration experience is the same as described above. When you have a billing agreement, you can charge the buyer for both recurring payment and one-time purchases.

It's possible that at the last step of your checkout flow, the buyer changes their mind and doesn't want to purchase the subscription. In this case, it's likely that the buyer won't authorize recurring payments from the Authorize Recurring Payments widget. Therefore, you won't be able to confirm the Billing Agreement object in the Draft state. Under this circumstance, Amazon Pay and Login with Amazon enables you to create an Order Reference for a one-time purchase. To do so, call the CreateOrderReferenceForId operation and specify the value of ConfirmNow parameter to be true. This operation creates and confirms the Order Reference with the payment and shipping information from the draft billing agreement. Note that Amazon lets you create only one Order Reference object from a draft billing agreement. For more information about the CreateOrderReferenceForId operation, see the Amazon Pay API reference guide.

Note: The Amazon Pay widgets typically return the same billing agreement ID while the billing agreement is in the Draft state. But after an Order Reference object is created off of a draft billing agreement, the billing agreement is considered used and is not returned in future widget render requests. If the same billing agreement needs to be used for future renders, you must explicitly bind the widget to the billing agreement by passing it via the amazonBillingAgreementId parameter.

See also