Step 6: Confirm the purchase

Before you can request payment, you need to initialize a post-checkout experience (“Confirmation Flow”) to handle Multi-Factor Authentication (MFA) when it’s required. This post-checkout procedure will redirect the buyer to an Amazon Pay hosted page and if a Multi-factor authentication is required, the Confirmation Flow shows the credit card issuer’s MFA challenge to the buyer. After the buyer interacts with the Confirmation Flow (for example, completes the MFA challenge), the buyer is returned to your site.

Procedure

  1. After the buyer initiates order completion by clicking the "buy now"-button, register the OffAmazonPayments.initConfirmationFlow function as the first call after the button click event (see example below); this enables Amazon Pay to handle MFA when it’s required. 
    
<script>
var sellerId = 'ABCDEFGHISELLERID';
var id = 'P02-1234567-1234567'; // use the AmazonOrderReferenceId
var buyNowBtn = document.getElementById("buy-now");

buyNowBtn.addEventListener('click', function () {
    OffAmazonPayments.initConfirmationFlow(sellerId, id, function(confirmationFlow) {
        placeOrder(confirmationFlow);
    });
});

// your function to initiate order processing in backend
// recommendation: use the latest version of the jQuery library for the $.ajax function
function placeOrder(confirmationFlow) {
    $.ajax({
        url: "your endpoint",
        success: function (data) {
            confirmationFlow.success(); // continue Amazon Pay hosted site
        },
        error: function (data) { // called on ajax error and timeout
            confirmationFlow.error(); // abort Amazon Pay initConfirmationFlow
            // you might want to add additional error handling
        },
        timeout: "your timeout value" //specify your timeout value (for example, 3000)
        //If the ajax request takes longer than this timeout (in ms), the error callback
        //will be called
    });
}
</script>
    2. Note: This code must include a reference to the Amazon Pay Widgets.js file. You should reference the same file you currently use for rendering the Amazon Pay widgets. Make sure you use the latest version of the jQuery library to use the $.ajax function.
  2. Call the SetOrderAttributes-operation again (see previous step) to set the final order attributes including the OrderTotal.
  3. After a successful SetOrderAttributes operation call, call the ConfirmOrderReference-operation. In the request, set the following attributes
    Required:
    • Amazon Order Reference ID
    • SuccessUrl
      The buyer is redirected to this URL if the MFA is successful.
    • FailureUrl
      The buyer is redirected to this URL if the MFA is unsuccessful.
    Ensure that the Amazon Order Reference ID is a unique value. For more information, see Handling errors from Amazon Pay API calls.

    Optional:
    • AuthorizationAmount
      The amount to authenticate during MFA completion. Use this parameter if you want to set a payment amount that is different than the OrderTotal provided in the SetOrderReferenceDetails operation call. If this parameter is not set, the amount authenticated during MFA will be equal to the OrderTotal provided in the SetOrderReferenceDetails operation call.)
    • ExpectImmediateAuthorization
      Set this flag to true if you trigger the first authorization "immediately" (that is, within 50 minutes) after confirmation of the OrderReferenceObject. If this value is set to true, the OrderReferenceObject will be closed automatically in case no authorization is triggered within the defined timespan. This will allow for automatically cleaning up transactions that are abandoned by the buyer in the last phase of checkout, for example if the buyer is unable to solve the MFA challenge and aborts the checkout. The default value is false.
    4. Making a call to the ConfirmOrderReference API 
         
$config = array (
    'merchant_id'   => 'YOUR_MERCHANT_ID', // Merchant/SellerID
    'access_key'    => 'YOUR_ACCESS_KEY', // MWS Access Key
    'secret_key'    => 'YOUR_SECRET_KEY', // MWS Secret Key
    'region'        => 'de',  
    'currency_code' => 'EUR'
);
$client = new \AmazonPay\Client($config)

$requestParameters = array();
$requestParameters['expect_immediate_authorization'] = true;
$requestParameters['success_url'] = 'http://www.test.com?status=success';
$requestParameters['failure_url'] = 'http://www.test.com?status=failure';
$requestParameters['amazon_order_reference_id'] = 'YOUR_AMAZON_ORDER_REFERENCE_ID';

$client->confirmOrderReference($requestParameters);
    Making a call to the ConfirmOrderReference 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='de',
    currency_code='EUR'
)

response = client.confirm_order_reference(
amazon_order_reference_id='AMAZON_ORDER_REFERENCE_ID',
success_url='http://www.test.com?status=success',
failure_url='http://www.test.com?status=failure',
expect_immediate_authorization=True
)
    Making a call to the ConfirmOrderReference 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: :eur,
    region: :de
)

client.confirm_order_reference(
    amazon_order_reference_id,
    success_url: 'http://www.test.com?status=success',
    failure_url: 'http://www.test.com?status=failure',
    expect_immediate_authorization: true
)
    Making a call to the ConfirmOrderReference API 
    
POST /OffAmazonPayments/2013-01-01 HTTP/1.1
Content-Type: x-www-form-urlencoded
Host: mws-eu.amazonservices.com
User-Agent: <Your User Agent Header>
AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&Action=ConfirmOrderReference
&AmazonOrderReferenceId=P02-8406368-4434100
&ExpectImmediateAuthorization=true
&SuccessUrl=http://www.test.com?status=success
&FailureUrl=http://www.test.com?status=failure
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2019-02-06T19:01:11Z
&Version=2013-01-01
&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE
  4. Return a 200 HTTP code to the AJAX call, if all calls were successful and make sure the confirmationFlow.success() callback function is called in your frontend JavaScript (see Step 1 of this section). This success() callback will trigger a redirect to an Amazon hosted page. If MFA is required, Amazon Pay shows the credit card issuer’s MFA challenge to the buyer and the buyer takes action to complete the MFA challenge. If the MFA was successful or not needed, the user will be redirected to the URL provided in the SuccessUrl parameter of the confirmBillingAgreement operation. Otherwise Amazon Pay will redirect the Buyer to the URL provided in the FailureUrl parameter.
    • User get's redirected to SuccessUrl
      Amazon Pay returns a GET-parameter named AuthenticationStatus. Check if this Parameter is equal to “Success”. If so, you are ready to request an authorization and you should proceed with the next section.
    • User get's redirected to FailureUrl
      Amazon Pay returns the GET-parameter named ErrorCode if an error occurs. Check if this GET-Parameter is set on the Failure-URL. If so, check the possible error codes below more information and recommended action:

      Error code Description Recommended action
      InvalidSellerId The value provided for the SellerId parameter is not valid. Verify the SellerId parameter value is correct and retry
      InvalidIdStatus The status of AmazonOrderReferenceId provided is not valid. The Order Reference object provided in the Id parameter, has a State value that is not set to Open when Amazon Pay processed the request. This could be due to delay or errors when you called ConfirmOrderReference operation. Please make sure correct status is set and retry.
      InternalServerError The server encountered an internal error Something went wrong. Please try again.
      If no ErrorCode Get-parameter is set, check for the GET-parameter AuthenticationStatus. Amazon Pay returns the GET-parameter AuthenticationStatus. Check the possible error codes below more information and recommended action:

      AuthenticationStatus Description Recommended action
      Failure The buyer failed the MFA challenge for the chosen payment instrument.
      • Logout from Amazon Pay
      • Redirect buyer back to Cart Page
      • Send a CancelOrderReference API-Call
      • Show info to buyer about failed payment
      Abandoned The buyer canceled/closed the MFA challenge for the chosen payment instrument Handle like an InvalidPaymentMethod-Decline (see section "Prepare to handle declined authorizations")