Skip to main content

Direct Implementation

Amazon Pay transactions require you to display an Amazon Pay Checkout to your Customer as part of the transaction flow. The transaction must be done in two stages, with the Checkout page being displayed between the stages. They can also optionally be done in three stages, allowing you to display an order confirmation after the Checkout page and before authorising the transaction. You can change the amount at this stage to allow for shipping costs when you know the confirmed delivery address the Customer selected as part of the Amazon Pay Checkout.

Amazon Pay do not provide a ready built Checkout page and require you to create one on y our servers using the JavaScript widget toolkit they provide.

Amazon Pay supports the normal payment and management actions. This section explains how to make payment requests. Management requests are performed as detailed in the Management Request section.

To customise the Amazon Pay Checkout experience, you may send various options in the checkoutOptions field in your initial request aas detailed in the Checkout Options (Hosted and Direct Integration) section.

Additional information available from Amazon Pay will be made available in the checkoutDetails and acquirerResponseDetails response fields.

The direct integration uses two complex fields to pass data between the Amazon Pay JavaScript widgets and the and the Gateway, the checkoutRequest and checkoutResponse fields.

The checkoutRequest field will be provided by the Gateway and is a record whose name/value properties should be used to help initialise the widgets.

The corresponding checkoutResponse field should be returned to the Gateway and must be a record containing name/value properties received from the widgets on completion of the Checkout.

The contents of the checkoutOptions, checkoutDetails, checkoutRequest, checkoutResponse and acquirerResponseDetails fields are formatted using the record format, the field also supports being provided using the serialised record format.

Initial Request (Checkout Preparation)​

To request that a transaction be processed via Amazon Pay, the request must contain a paymentMethod of ‘amazonpay’ In addition, you may send checkoutOptions to customise the Checkout experience.

When the Gateway receives this paymentMethod, assuming there are no other errors with the request, it will attempt to find a suitable Amazon Pay Merchant Account in the current account routing group (refer to the Merchant Account Routing section).

If the Gateway is unable to find a suitable account, then the transaction will be aborted, and it will respond with a responseCode of 66364 (INVALID PAYMENTMETHOD).

Otherwise, the Gateway will respond with a responseCode of 65826 (CHECKOUT REQUIRED) and the response will include a checkoutURL field containing the URL required to load the Amazon Pay JavaScript Widgets; and a checkoutRequest containing any data required by those Widgets. The response will also contain a unique checkoutRef that must be echoed back in the continuation requests.

At this point, your server must create an Amazon Pay Checkout page using their JavaScript Widgets. Further details on how to use the Widgets are provided in the Amazon Pay guide at https://developer.amazonpay.com/docs/classic/express-checkout/in-context/enable_in_context_checkout/.

Continuation Request (Checkout Details and Authorise)​

On completion of the Amazon Pay Checkout, the Merchant should send new request to the Gateway to finalise the transaction. This new request must contain the checkoutRef received in the initial response and a checkoutResponse records containing the information provided by the Amazon Pay Widgets along with a status value. If the checkout was successful, the status value must be ‘success’, alternatively if the Checkout was cancelled its value will be ‘cancel’.

Any accessToken generated by the Amazon Pay Login Widget; orderReferenceID, generated by the Wallet or Address Widgets; and billingAgreementID generated by the optional Billing Widget, must be included in the checkoutResponse field.

Separate Checkout Details and Authorisation Requests​

You can choose to obtain the Checkout details before actually sending the transaction for authorisation by sending the checkoutOnly field in the above continuation request. If this field is sent with a value of ‘Y’ then the Gateway will load the Checkout details and then return them to you without sending the request for authorisation. You can then display them and/or adjust the amount, for example, according to delivery charges appropriate to the received delivery address. You should then send a new request containing the checkoutRef received to continue the transaction and authorise it.

info

This stage can be repeated multiple times by including the checkoutOnly field with a value of ‘Y’ each time. To complete the transaction, the final request must not contain the checkoutOnly field or it must not have a value of ‘Y’.