Important: This integration has been deprecated. Amazon Pay will continue to support this version but it will not be updated with new features. New integrations should use Amazon Pay Checkout.

Step 4: Set billing agreement details and confirm the agreement

The Billing Agreement object

By default, when a buyer authenticates with Amazon Pay, as shown in Step 1: Add a Button widget for buyer authentication or when you render the address or wallet widget without specifying the Billing Agreement Id, Amazon Pay creates a system object, called the billing agreement. This object stores all the attributes associated with the payment that the buyer is going to make using Amazon Pay.

At this point in the Amazon Pay checkout process, the Billing Agreement object has been populated with the buyer's shipping address, payment method selections, and consent for recurring payment. Now, you must set additional attributes in the Billing Agreement object that help associate the billing agreement with any other details that you are tracking. For example, you can set details like the order or subscription number that you have specified for the transaction and a note that is shown to the buyer in emails sent by Amazon Pay.

After you set these attributes by calling the SetBillingAgreementDetails operation, you must confirm the purchase to Amazon Pay by calling the ConfirmBillingAgreement operation. After you confirm the billing agreement, Amazon Pay informs the buyer that you authorized a payment method to be used for this billing agreement. You must confirm the billing agreement before you process the payment for the order.

Setting the billing agreement details

To set the specifics of the Billing Agreement object, you call the SetBillingAgreementDetails operation. It enables you to provide any additional information about the recurring payment that you would like included in the Billing Agreement object. This additional information is used in both buyer-facing communications from Amazon Pay as well as in payment processing information returned to you.

Amazon Pay limits the maximum charge to €1000 per calendar month for each billing agreement. You can check this limit by calling the GetBillingAgreementDetails operation.

The following example shows how to call the SetBillingAgreementDetails operation:

 
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01?
AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&AmazonBillingAgreementId=C01-8824045-7416542
&Action=SetBillingAgreementDetails
&BillingAgreementAttributes.PlatformId=PLATFORM_ID_HERE
&BillingAgreementAttributes.SellerNote=APPROVE%20LITE%20APPROVE%20HEAVY
&BillingAgreementAttributes.SellerBillingAgreementAttributes.CustomInformati
on=Example%20Customer%20Info
&BillingAgreementAttributes.SellerBillingAgreementAttributes.StoreName=Test%20Store%20Name
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-12-11T10%3A57%3A18.000Z
&Version=2013-01-01
&Signature=Z0ZVgWu0ICF4FLxt1mTjyK%2BjdYG6Kmm8JxLTfsQtKRY%3D

For more information about the SetBillingAgreementDetails operation including the request parameters and response elements, see SetBillingAgreementDetails in the Amazon Pay API reference guide.

Confirming the billing agreement details

After setting the attributes for the Billing Agreement object (including any additional attributes that you want to add through the SetBillingAgreementDetails operation call), you must confirm the Billing Agreement object. This step informs Amazon Pay that the buyer has placed the order on your site. Confirming the Billing Agreement object doesn't guarantee funds or put funds on hold. For this, you need to submit a request to Amazon Pay to authorize the payment and capture funds.

Note: You can't confirm a billing agreement if the buyer has not been able to choose an address or payment method or if the buyer has not authorized recurring payments from the Authorize Recurring Payment widget.

When a billing agreement can't be confirmed, it has constraints on it. If you are using an order review page, call the GetBillingAgreementDetails operation before rendering the order review page to check for constraints.

If there are constraints related to address, payment, or buyer consent, you should disable the confirm button on your website until the buyer has chosen an address and/or payment instrument.

If you attempt to confirm a billing agreement that has constraints on it, you get an error response showing the specific constraint violations.

You should not show the order confirmation page to your buyers unless the ConfirmBillingAgreement operation was successful and without constraints.

For more information about constraints, see the GetBillingAgreementDetails and Billing agreement constraints sections in the Amazon Pay API reference guide.

You confirm the Billing Agreement object by calling the ConfirmBillingAgreement operation.

The following example shows how to call the ConfirmBillingAgreement operation:

 
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&AmazonBillingAgreementId=C01-8824045-7416542
&Action=ConfirmBillingAgreement
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-12-11T11%3A37%3A19.000Z
&Version=2013-01-01
&Signature=ET6V00R4fr2inSDky4olLrlS1XrQfdrV9Bj%2BiWebz1c%3D

For more information about the ConfirmBillingAgreement operation including the request parameters and response elements, see ConfirmBillingAgreement in the Amazon Pay API reference guide.

After successfully calling the ConfirmBillingAgreement operation, the Billing Agreement object moves from the Draft state to the Open state. For more information on state transitions, see Synchronizing your systems with Amazon Pay.

If you are using the Amazon Pay button (guest checkout) option, only the partial shipping address is shared with you until you confirm the Billing Agreement object by calling the ConfirmBillingAgreement operation. You can use this partial address to compute taxes and shipping costs. Amazon Pay recognizes that you need further details about the customer and the full shipping address to process your order and offer customer service. After you confirm a Billing Agreement object by calling the ConfirmBillingAgreement operation, you should get the full shipping address by calling the GetBillingAgreementDetails operation, and you should verify that you can ship to that address.

When using the Amazon Pay button (guest checkout) option, the following customer information is made available to you after the Billing Agreement object is confirmed:

Buyer detail	How and when to obtain
Buyer name	Call the GetBillingAgreementDetails operation after you successfully call the ConfirmBillingAgreement operation.
Buyer email address	Call the GetBillingAgreementDetails operation after you successfully call the ConfirmBillingAgreement operation.
Buyer phone number (if available)	Call the GetBillingAgreementDetails operation after you successfully call the ConfirmBillingAgreement operation.
Recipient name	Call the GetBillingAgreementDetails operation after you successfully call the ConfirmBillingAgreement operation.
Shipping address	Partial address information (City, StateOrRegion, PostalCode, and CountryCode) can be obtained by calling the GetBillingAgreementDetails operation immediately after an address is chosen in the AddressBook widget. Full address information (including street information) is obtained by calling the GetBillingAgreementDetails operation after you successfully call the ConfirmBillingAgreement operation. Note: If you want to access full shipping address before confirming the billing agreement, you should use the payments:shipping_address scope. For more details, refer to Step 1: Add a Button widget for buyer authentication in this guide.
Recipient phone number (if available)	Call the GetBillingAgreementDetails operation after you successfully call the ConfirmBillingAgreement operation.

At this point, if you are using the asynchronous mode of authorization we strongly recommend that you proceed with your existing buyer-facing order confirmation business processes (confirmation email, confirmation landing page, etc.), as the following steps of authorizing and capturing the payment method take additional time to process.

After the Billing Agreement object is in the Open state, you can proceed with processing your buyer's payment.

Buyer email to confirm recurring payments setup

As soon as the Billing Agreement object is in the Open state, Amazon Pay sends a New merchant agreement email to the buyer notifying them that they have authorised you to automatically charge their Amazon account.

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