Set purchase details and confirm the purchase
Before you can request payment, you need to set and confirm the order using the orderReferenceId provided in the AddressBook or Wallet widget step.
Procedure
- Make a call to the SetOrderReferenceDetails API. In the request, set the following attributes in the OrderReferenceAttributes:
Required:
- Amazon Order Reference ID
- Order Total (the order amount and currency code)
- Store Name
- Seller Order ID
- Seller Note
Note: If you cannot provide Store Name, Seller Order ID, Seller Note, Platform ID, or Customer Information before the order is placed, you can set this data after the purchase is completed by using the SetOrderAttributes API call. For more information, see Adding order attributes after purchase. - Make a call to the ConfirmOrderReference API. If the SetOrderReferenceDetails API call was successful, confirm the Order Reference object by making a call to the ConfirmOrderReference API call.
This step informs Amazon that the buyer has placed the order on your site. If the call to ConfirmOrderReference was successful, the Order Reference object is set to an Open state and Amazon will send the buyer a Payment initated email to confirm that they have initiated payment for a purchase using Amazon Pay. If the response returns a constraint, make attempts to remedy it. For example, in the case of a PaymentPlanNotSet constraint, inform the buyer that they must make a different payment selection. You can do this either by showing an on-screen message or by redirecting the buyer to an appropriate page to make the selection.
Note: The Payment initiated email is not sent in two cases:
- When the merchant cancels the transaction (CancelOrderReference) within 5 minutes of confirmation (ConfirmOrderReference).
- When OrderReference is closed within 5 minutes of confirmation of the OrderReference (ConfirmOrderReference).
- Make a call to the GetOrderReferenceDetails. After you successfully confirm the order reference, you should call the GetOrderReferenceDetails API to get the remaining buyer information, like name and shipping address, to ensure that you have retrieved the latest address.
Note: You must implement error handling with your API calls, and you must test the results of the API response. For more information, see Handling errors.
Making a call to the SetOrderReferenceDetails API
from pay_with_amazon.client import PayWithAmazonClient
client = PayWithAmazonClient(
mws_access_key='YOUR_ACCESS_KEY',
mws_secret_key='YOUR_SECRET_KEY',
merchant_id='YOUR_MERCHANT_ID',
region='na',
currency_code='USD')
response = client.set_order_reference_details(
amazon_order_reference_id='AMAZON_ORDER_REFERENCE_ID',
order_total='1.00',
seller_note='My seller note.',
seller_order_id='MY_UNIQUE_ORDER_ID',
store_name='My store name.',
custom_information='My custom information.')
from pay_with_amazon.client import PayWithAmazonClient
client = PayWithAmazonClient(
mws_access_key='YOUR_ACCESS_KEY',
mws_secret_key='YOUR_SECRET_KEY',
merchant_id='YOUR_MERCHANT_ID',
region='na',
currency_code='USD')
response = client.confirm_order_reference(
amazon_order_reference_id='AMAZON_ORDER_REFERENCE_ID')
from pay_with_amazon.client import PayWithAmazonClient
client = PayWithAmazonClient(
mws_access_key='YOUR_ACCESS_KEY',
mws_secret_key='YOUR_SECRET_KEY',
merchant_id='YOUR_MERCHANT_ID',
region='na',
currency_code='USD')
response = client.get_order_reference_details(
amazon_order_reference_id='AMAZON_ORDER_REFERENCE_ID',
address_consent_token='ADDRESS_CONSENT_TOKEN')
Making a call to the SetOrderReferenceDetails API
require 'pay_with_amazon'
merchant_id = 'YOUR_MERCHANT_ID'
access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY'
client = PayWithAmazon::Client.new(
merchant_id,
access_key,
secret_key,
sandbox: true,
currency_code: :usd,
region: :na
)
amazon_order_reference_id = 'AMAZON_ORDER_REFERENCE_ID'
amount = 106
client.set_order_reference_details(
amazon_order_reference_id,
amount,
seller_note: 'Lorem ipsum dolor',
seller_order_id: '5678-23',
store_name: 'CourtAndCherry.com',
mws_auth_token: 'amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE'
)
Making a call to the ConfirmOrderReference API
client.confirm_order_reference(
amazon_order_reference_id,
mws_auth_token: 'amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE'
)
require 'pay_with_amazon'
merchant_id = 'YOUR_MERCHANT_ID'
access_key = 'YOUR_ACCESS_KEY'
secret_key = 'YOUR_SECRET_KEY'
client = PayWithAmazon::Client.new(
merchant_id,
access_key,
secret_key,
sandbox: true,
currency_code: :usd,
region: :na
)
amazon_order_reference_id = 'AMAZON_ORDER_REFERENCE_ID'
address_consent_token = 'ADDRESS_CONSENT_TOKEN'
client.get_order_reference_details(
amazon_order_reference_id,
address_consent_token: address_consent_token,
mws_auth_token: 'amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE'
)
Making a call to the SetOrderReferenceDetails API
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Action=SetOrderReferenceDetails
&AmazonOrderReferenceId=S23-1234567-1234567
&OrderReferenceAttributes.OrderTotal.Amount=106
&OrderReferenceAttributes.OrderTotal.CurrencyCode=USD
&OrderReferenceAttributes.SellerNote=For your order of Casad
'2Jours Bonheur' Satchel in Sandstorm
&OrderReferenceAttributes.SellerOrderAttributes.SellerOrderId=5678-23
&OrderReferenceAttributes.SellerOrderAttributes.StoreName=CourtAndCherry.com
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-11-16T19:01:11Z
&Version=2013-01-01
&Signature=2RPzkOgQmDybUjk0dA54maCEXAMPLE
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&Action=ConfirmOrderReference
&AmazonOrderReferenceId=S23-1234567-1234567
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2013-11-16T19:01:11Z
&Version=2013-01-01
&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE
https://mws-eu.amazonservices.com/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&Action=GetOrderReferenceDetails
&AddressConsentToken=IQEBLzAtAhUAjagYW4Jrgw84pCaaIDjrKoEhZXsEXAMPLE
&AmazonOrderReferenceId=S23-1234567-1234567
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-10-03T19:01:11Z
&Version=2013-01-01
&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE
Order reference constraints
Amazon Pay might not always allow all payment methods for a given transaction. Depending on various factors, some payment methods might not be available. To determine the available payment methods, the amount of the transaction must be passed to the SetOrderReferenceDetails operation.
To ensure that only allowed payment methods are shown to a buyer, Amazon Pay requires that you set the OrderTotal using the SetOrderReferenceDetails operation before showing the Wallet widget, as described in the Displaying read-only AddressBook and Wallet Widgets section. Performing this operation enables Amazon Pay to determine which payment methods are allowed for this Order Reference.
If you set the OrderTotal after the buyer has chosen the payment method from the Wallet widget, you must inspect the result of the SetOrderReferenceDetails operation for the presence of the PaymentMethodNotAllowed constraint. If this constraint is returned, it means that the payment method chosen by the buyer is not allowed for this Order Reference, and you will not be able to confirm the Order Reference until this constraint is resolved. To resolve this constraint, re-render the Wallet widget and request the buyer to choose a different payment method.
See also
Order Reference States and Reason Codes in the Amazon Pay API reference guide