Amazon Pay Strong Customer Authentication (SCA) Upgrade

Overview

The SCA Upgrade introduces a post-checkout experience (“Confirmation Flow”) to handle Strong Customer Authentication (SCA) when it’s required. When SCA is required, the Confirmation Flow 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 merchant’s site (for example, order confirmation page). Find all details of PSD2 and SCA on our help page.

SCA payment flow (PDF | SVG)

Change summary

Before you can request payment, 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.

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 SCA 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: "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>
   

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 (or SetOrderReferenceDetails) 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 SCA is successful.
   • FailureUrl
     The buyer is redirected to this URL if the SCA is unsuccessful.
   Ensure that the Amazon Order Reference ID is a unique value. For more information, see Handling errors from Amazon Pay SCA calls.
   
   Optional:
   • AuthorizationAmount
     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.)
   • 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.
• 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['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            

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 SCA is required, Amazon Pay shows the credit card issuer’s SCA challenge to the buyer and the buyer takes action to complete the SCA challenge. If the SCA 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 SCA challenge for the chosen payment instrument.	Logout from Amazon Pay Redirect buyer back to Cart Page 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 specific payment scenarios and trigger certain behaviors 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