Strong Customer Authentication for merchant-initiated transactions

Update your existing billing agreements

PSD2 requires that Amazon Pay provide to banks more information than before that you need to supply. To provide this additional information to Amazon Pay, update all existing billing agreements created before 14 September 2019 and provide us the additional parameters using the setBillingAgreementDetails operation.

1. Define your BillingAgreementType
   Call a setBillingAgreementDetails operation for all subscriptions created before 14 September 2019. The setBillingAgreementDetails operation requires the following input parameters:

   Parameter name	Required	Definition
   BillingAgreement Id	Yes	The BillingAgreement identifier. This value is retrieved from the onReady callback function in the AddressBook and Wallet widget
   BillingAgreement Type	No	Set it to CustomerInitiatedTransaction or MerchantInitiatedTransaction, depending on the integration pattern defined here. If you do not provide this value, we take CustomerInitiatedTransaction as default.
   Amount	No	Define a subscription amount only if you charge the same amount for all orders of this billing agreement. Even if you change the amount for only one order, don't set the amount.

2. Validate your Billing Agreements
   Call a ValidateBillingAgreement operation for all billing agreements created before 14 September 2019.
   The ValidateBillingAgreement operation requires the following input parameters.
   

   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 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_billing_agreement_id'] = $billing_agreement_id; //B02-XXXXXX-XXXXXX
   
   $client->validateBillingAgreement($requestParameters);
   

Change the process to set up a new Billing Agreement

The workflow shown below assumes that a buyer has done the following:

• Signed in using the Login with Amazon or Amazon Pay Button widget.
• Chosen a shipping address using the Amazon Pay AddressBook widget (if applicable) and a payment instrument using the Wallet widget.
• Initiated billing agreement setup (for example, by clicking the Subscribe button).

1. Change the front-end ode that initiates the billing agreement setup
   After the customer initiates order completion, register the OffAmazonPayments.initConfirmationFlow function as click event by adding a click-listener to place order button. This event initiates an Asynchronous JavaScript and XML (“AJAX”) call to the backend.
   Note: If you currently use form submission to process orders after the buyer initiates order completion, change your integration to use an AJAX function.
   

   
   <script>
   var sellerId = 'ABCDEFGHYOURSELLERID';
   var id = 'B02-1234567-1234567'; // use the Amazon Pay BillingAgreementId
   var subscribeBtn = document.getElementById("buy-now");
   
   subscribeBtn.addEventListener('click', function () {
       OffAmazonPayments.initConfirmationFlow(sellerId, id, function(confirmationFlow) {
           subscribe(confirmationFlow);
       });
   });
   
   // your function to initiate order processing in backend
   // recommendation: use the latest version of the jQuery library for the $.ajax function
   function subscribe(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>
   

2. Handle AJAX request
   Listen on the backend for the AJAX request described above and call the setBillingAgreementDetails operation.
   The setBillingAgreementDetails operation requires the following input parameters:
   

   Parameter name	Required	Definition
   BillingAgreement Id	Yes	The BillingAgreement identifier. This value is retrieved from the onReady callback function in the AddressBook and Wallet widget
   BillingAgreement Type	No	Set it to CustomerInitiatedTransaction or MerchantInitiatedTransaction, depending on the integration pattern defined here. If you do not provide this value, we take CustomerInitiatedTransaction as default.
   Amount	No	Define a subscription amount only if you charge the same amount for all orders of this billing agreement. Even if you change the amount for only one order, don't set the amount.

   If setBillingAgreementDetails returns a constraint, handle them as described in Step 2: Set purchase details and define the purchase of the Amazon Pay and Login with Amazon integration guide. Otherwise, proceed and call the confirmBillingAgreement operation.
   The confirmBillingAgreement operation requires the following input parameters.
   

   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.
3. 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.
4. 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 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