Strong Customer Authentication for customer-initiated transactions

Change summary

because the customer is present at the time of purchse, you need to initialize a post-checkout experience (“Confirmation Flow”) to handle Strong Customer Authentication (SCA) when it’s required. This post-checkout procedure will redirect the buyer to an Amazon Pay hosted page and if a SCA is required, this confirmation page shows the credit card issuer’s SCA challenge to the buyer. After the buyer interacts with the Confirmation Flow (for example, completes the SCA challenge), the buyer is returned to the site you defined in the ConfirmOrderReference operation.

Charge the customer

1. Create a Child-OrderReference
   Use CreateOrderReferenceForId. Don't set the confirmNow flag to true. Because the customer is present, the bank might require an MFA challenge.
2. Change the frontend code that initiates the purchase
   After the buyer clicks the Buy now button and initiates order completion, register the OffAmazonPayments.initConfirmationFlow function as the first call after the button click event (see example below). Doing this enables Amazon Pay to handle MFA when it’s required.
   

   
   <script>
   var sellerId = 'ABCDEFGHYOURSELLERID';
   var id = 'P02-1234567-1234567'; // use the AmazonOrderReferenceId you used for the ConfirmOrderReference-Call
   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: 0 //specify your timeout value (for example, 5000)
           //If the ajax request takes longer than this timeout (in ms), the error callback
           //will be called. A value of 0 means there will be no timeout.
       });
   }
   </script>
   

   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.
3. Set the OrderDetails and confirm the order
   Call the SetOrderAttributes operation to set the amount and order details, and then call the ConfirmOrderReference operation. In the request, set the following attributes
   

   Parameter	Required	Description
   SuccessUrl	yes	The buyer is redirected to this URL if the SCA is successful. if not FailureUrl is set, the customer will also be redirected to this page if SCA was unsuccessful.
   FailureUrl	no	The buyer is redirected to this URL if the SCA is unsuccessful.
   AuthorizationAmount	no	The amount to authenticate during SCA 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 SCA will be equal to the OrderTotal provided in the SetOrderReferenceDetails operation call.)

   • PHP
   • Python
   • Ruby
   • Other
   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['amazon_order_reference_id'] = $orderReferenceId;
   $requestParameters['success_url'] = 'https://www.test.com/OrderConfirmed';
   $requestParameters['failure_url'] = 'https://www.test.com/OrderFailed';
   
   $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='https://www.test.com/OrderConfirmed',
   failure_url='https://www.test.com/OrderFailed'
   )
   

   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: 'https://www.test.com/OrderConfirmed',
       failure_url: 'https://www.test.com/OrderFailed'
   )
   

   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-1234567-1234567
   &FailureUrl=https%3A%2F%2Fwww.test.com%2FOrderFailed
   &SellerId=YOUR_SELLER_ID_HERE
   &SignatureMethod=HmacSHA256
   &SignatureVersion=2
   &SuccessUrl=https%3A%2F%2Fwww.test.com%2FOrderConfirmed
   &Timestamp=2019-07-17T06%3A54%3A29.000Z
   &Version=2013-01-01
   &Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE         
   

   Return a 200 HTTP code to the AJAX call if ConfirmOrderReference was successful.
4. Trigger confirmationFlow.success() callback function
   The 200 response from now triggers the confirmationFlow.success() function. For sample code, see Step 1.
   This success() callback triggers a redirect to an Amazon-hosted page. If MFA is required, Amazon Pay shows the credit card issuer’s MFA challenge to the buyer. The buyer takes action to complete the MFA challenge.
5. Implement logic after failure and success redirect
   
   Case 1: MFA was successful or not needed
   The user is redirected to the URL provided in the SuccessUrl parameter of the confirmBillingAgreement operation.
   Amazon Pay returns a GET parameter named AuthenticationStatus. Check if this parameter is equal to “Success” and, if it is, proceed with the ValidateBillingAgreement operation.
   The ValidateBillingAgreement operation requires the following input parameters. For more information, see Step 5: Validate the billing agreement.
   

   Parameter name	Required	Definition
   BillingAgreementId	Yes	The BillingAgreement identifier. This value is retrieved from the on onReady callback function in the AddressBook and Wallet widgets. See also: Step 2: Add the AddressBook and Wallet widgets

   • PHP
   Making a call to the ValidateBillingAgreement 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['amazon_billing_agreement_id'] = $billing_agreement_id; //B02-XXXXXX-XXXXXX
   
   $client->validateBillingAgreement($requestParameters);
   

   Note: To prevent expiration of the authentication token, you need to make the Capture within 30 days of subscription creation. If the recurring frequency exceeds 30 days, you can do a €0 charge as a placeholder.
   Case 2: MFA was unsuccessful or buyer aborted the challenge
   The user is redirected to the URL provided in the FailureUrl parameter of the confirmBillingAgreement operation.
   If an error occurs, Amazon Pay returns the GET parameter named ErrorCode. Check if this GET parameter is set on the failure URL. If so, for more information and recommended actions, check the possible error codes below.
   

   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 SCA challenge for the chosen payment instrument.	Logout from Amazon Pay Redirect buyer back to Cart Page Send a CancelOrderReference API-Call Show the Recommended errors message
   Abandoned	The buyer canceled/closed the SCA challenge for the chosen payment instrument	Handle like an InvalidPaymentMethod-Decline (see section "Prepare to handle declined authorizations"). Show the Recommended errors message

Testing payment authentications

You can use the Amazon Pay sandbox to simulate payment authentications declines by choosing one of the payment methods marked with a * in the Wallet widget during checkout. In addition to these simulations, you can also trigger certain payment authentications declines by using a simulation string. The table below outlines how certain payment authentications declines can be simulated.

Recommended errors messages

MFA Abandoned

MFA Failure

Troubleshooting

• The redirect to the success- or failure-URL was not successful. I see the error message "Hmmm...that didn't work" after I trigger the success-callback.
  
  
  
  • Check that an AmazonOrderReference ID is present in the URL of the MFA page. If not, please double-check that the AmazonOrderReference ID was passed as the “Id” parameter in the definition of the initConfirmationFlow function.
  • Make sure that the redirect to the Amazon Pay hosted page happened after successful ConfirmOrderReference response. Check if the OrderReference object is in status “OPEN” by doing a GetOrderReferenceDetails API call.
  • Make sure that you set a valid parameter as SuccessUrl for the ConfirmOrderReference-operation. This parameter must not be null and has to have the format https://www.url.com
  • Make sure that you are using an SDK version that supports the SCA workflow. The minimum required versions are listed below.
    • PHP v3.4.1
    • C# v3.5.0
    • Ruby v2.4.0
    • Python v2.6.0
• The redirect to the success- or failure-URL was not successful. I see the error message "Problem connecting" after I trigger the success-callback.
  
  
  
  • Check that you have passed the correct Seller ID and AmazonOrderReference ID for the ConfirmOrderReference operation. To verify this, make sure that the GET-parameters sellerId and amazonPaymentContractId are set correctly. The Seller ID should be the same you use for all API calls. You can find the Seller ID in your SellerCentral account at Integration > MWS Access Key. If you are using an SDK, you may have already set it when configuring your client class. The AmazonOrderReference ID passed as “Id” parameter in the front-end code for the initConfirmationFlow function must be the same Id you used for the ConfirmOrderReference-Call.
  • Make sure that you are using an SDK version that supports the SCA workflow. The minimum required versions are listed below.
    • PHP v3.4.1
    • C# v3.5.0
    • Ruby v2.4.0
    • Python v2.6.0