1 About Amazon Pay

1.1 General information about Amazon Pay

1.2 Configuration for Amazon Pay

1.3 Steps within the process

1.4 Integrate Amazon Pay button widget

1.5 Review page

1.6 Process flow chart

1.7 Subsequent actions

2 1cs OPS interface

2.1 Definitions

2.1.1 Data formats

2.1.2 Abbreviations

2.2 Initializing the Amazon Pay interface

2.3 Amazon Pay capture a payment

2.4 Amazon Pay credit a pament

2.5 Amazon Pay reverse an order

3 Batch processing via the interface

3.1 Scope

3.2 Process flow

3.3 Integrate Amazon Pay button

3.4 Initialize Amazon Pay interface

3.5 Adress validation

1 About Amazon Pay

1.1 General information about Amazon Pay

Amazon Pay provides buyers with a secure, trusted, and convenient way to sign in and pay for their purchases on your site by using their Amazon credentials. See browser support for information about the operating systems, browsers and browser versions that Amazon Pay supports.

This guide provides an overview of the buyer experience and shows you how to integrate with the latest checkout technology from Amazon Pay.

The Amazon Pay checkout experience

1. The buyer clicks on the Amazon Pay button to start checkout.
2. The buyer signs in, confirms their preferred payment instrument, and optionally selects a shipping address on the Amazon Pay-hosted page.
3. The buyer is redirected back to your order review page for confirmation.
4. The buyer completes checkout on the Amazon Pay-hosted page by responding to the multi-factor authentication (identity validation) challenge, if prompted, or by selecting another payment method if payment was declined.
5. Amazon Pay redirects the buyer back to your confirmation page.

Further information you will find also on the:

• Web page of Amazon Pay
• Checkout Demo page from Amazon: Demo page

Logo

1.2 Configuration for Amazon Pay

There are two options that can be used depending if you are a new or an existing customer.

Existing Customers

Already existing customers need to login to their accounts and create a new set of API keys to be used with Amazon Pay Checkout version.2.

We already have the needed data for your accounts done for the original checkout v.1.

Please see below the “Guide to create API keys”.

New Customer

Before using Amazon Pay you need to register at https://pay.amazon.de/signup  

An alternative is also the signup for Amazon based on country, the steps are the;

• follow the above URL
• choose the country needed, based on the country flag found at the top-right:

When logged in in the Amazon seller central, you should have 2 accounts, that you can toggle between:

• Sandbox
• Production

The needed data for the onboarding are the following:

• If you have more than one market this information needs to be given to us for each market needed.

Please follow the guide below to create the API keys necessary.

Important: If you don´t see the option to create the API keys, you need to create a store first and then create the API keys.

Under the “Integration central” at the bottom you can do this using the link found there:

MWS Autorization Token

One of the important piece of data needed is the MWS Authorization token from Amazon which gives the 1cs Online Payment System permission to conduct transactions for your shop.

The second step is generating a MWS Auth Token. This is the data needed:

• Developer name: 1cs OPS Ltd
  
• Developer account number: 8662-2365-9858

Guide

When logged in to the seller central of Amazon, go to the top right-hand side of the page and click on Settings and choose “User Permissions”:

This leads you to the “User permissions” page which show you the current users, here you can add an external developer to your account, here please click on “Visit manage your apps”:

This leads you to a new page were you can see developers that have access, here you can add, delete and renew permissions. Please click on “Authorise new developer”:

On the new page you need to add the developer name and ID given above. Fill in the information and click on “Next”:

The last page is were you need to agree to the terms and conditions of granting a developer access to the account.

When clicking on “Next”, you are shown a success page with information:

With the last click on “Next”, you are led back to the original “User Permission” were the developer is now shown:

Here you can now click on “View” and access the “MWS Authorization token” and can also copy it.

Then submit the received MWS Authorisation Token on a secure way to 1cs OPS Helpdesk for configuration.

Guide to create API keys

In order to create new API keys, choose one of your accounts, either Production or Sandbox on top of the page, process needs to be done for both accounts. Amazon description is found here.

Please click left-hand side on the symbol with the 3 horizontal lines.

On the menu that appears, please go to “Integration” and choose “Integration central”.

On the Integration central, go to the section “Create API Keys” and click on the button there.

A Pop-up window appears where you need to choose “Generate API Credentials”, here you also need to give the keys a unique name:

The newly created keys are immediately visible on the “Integration central”. There you choose the option to “See Details”:

When looking at the details, you can see the data or download the data in JSON format:

JSON example:

“merchant_id”: ”             “,
“public_key_id”: ”                                  “,
“store_id”: ”                                                                    “,

Important: 

• This data is needed for your onboarding and needs to be sent in a secure way to the 1cs Online Payment System Helpdesk for configuration.
• The same process needs to be repeated for the second account depending on which one you did first

Notify URL

Customers will need to also to store/configure the following 1cs OPS notify URL.

URL:  https://www.computop-paygate.com/amazonpaycomplete.aspx

Go to the menu on the te top left-hand side:

On the menu that appears, please go to “Integration” and choose “MWD Access Key”:

At the bottom of the page you can see the option for IPN (Instant Payment notification):

After clicking on the blue link another pages open with integration settings:

Here please click on the “Edit”-button:

1. Here please add the fowllowing URL to the integrator URL and click on the “Update”-button

2. The merchant can also save his own notify URL if he so wishes. The 1cs Online Payment System will ask for the NotifyURL on the request as well.

Important: Please make sure to use the Notifies sent via server to server and not only rely on the SuccessURLs/FailureURLs.

1.3 Steps within the process

The basic payment process with Amazon consists of several steps:

Important

Please make sure that you plan in the 2 main tasks for merchants:

1. Add the new Amazon Cv.2 Button (Step 1)
2. On the redirect back to the shop (Step 3) were changes may take place, merchant needs to make sure that address (if applicable) and payment method, can be changed. Also the possibility of changes to the amount should be pass with a call to the 1cs Online Payment System.  

1.4 Integrate Button-Widget

The following example code shows how to integrate the Amazon Pay button in your webshop.

When customer submits this button, you will call the 1cs Online Payment System to obtain additional data, which are required for updating the Amazon Pay button.

   var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’,{

merchantId: ‘xxxxx’,

   publicKeyId: ‘SANDBOX-xxxxxxxxxx’,

   ledgerCurrency: ‘EUR’,         

   checkoutLanguage: ‘en_GB’,

   productType: ‘PayAndShip’,

   placement: ‘Cart’,

   buttonColor: ‘Gold’

});

amazonPayButton.onClick(function(){

  const [payload, signature, publicKeyId] = your_call_to_paygate();

  amazonPayButton.initCheckout({

    createCheckoutSessionConfig: {

      payloadJSON: payload,

      signature: signature,

      publicKeyId: publicKeyId

    }

  });

});

In this case the following parameters must be present within the Button:

Further information can be found in the documentation from Amazon Pay.

1.5 Review Page

When using the complete checkout of Amazon Pay v2, the review page is to be used on the side of the merchant to allow:

• change of address
• change of payment method

A change of either one or both is possible.

1cs Online Payment System Data

This is the 1cs OPS data that is delivered to the merchant for the review page

• mid
• PayID
• XID
• TransID
• Status=REQUEST
• Code=0
• AmountAuth=0
• AmountCap=0
• AmountCred=0
• bdaddrstreet2
• bdaddrcity
• bdaddrcountrycode
• bdaddrname
• bdphonenumber
• bdaddrzip
• AddrStreet
• AddrCity
• AddrCountryCode
• addrname
• phonenumber
• AddrZip
• addrstate
• amazonmerchantid
• rtf=onetime
• amazonstatus=Open
• amazonpayredirecturl
• amazoncheckoutsessionid
• amazonpaymentdescriptor

ISON example

This is an example on the JSON that merchants can use to accomodate changes if necessary

let session = document.getElementById(‘sessionId’).value;

let link = document.getElementById(‘redirectUrl’).value;

let buyNow = document.getElementById(‘buy-now’);

buyNow.addEventListener(‘click’, () => {

  window.location = link;

})

amazon.Pay.bindChangeAction(‘#change-paymethod’, {

  amazonCheckoutSessionId: session,

  changeAction: ‘changePayment’

});

amazon.Pay.bindChangeAction(‘#change-shipping’, {

  amazonCheckoutSessionId: session,

  changeAction: ‘changeAddress’

});

The Amazon description can be found here:

1.6 Process flow chart

• Version with possibly changes done to delivery address, payment instrument or amount.
  
• Valid for OTP (One time payments) or for Recurring setup (RTF=I)

Recurring Subsequent

Subsequent actions

Capture a payment

Credit a payment

Reverse an order

2 1cs Online Payment System interface

2.1 Definitions

2.1.1 Data formats

2.1.2 Abbreviations

Notice: Please note that the names of parameters can be returned in upper or lower case.

2.2 Initialize Amazon Pay interface

In order to initialize a payment with Amazon Pay, please visit the following URL:

Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.  

The following table describes the encrypted payment request parameters:

Encrypted parameters for initializing an Amazon Pay payment

Intermediate response with button additional parameters

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters after initializing an Amazon Pay payment

The following example code shows the updated and complete Amazon Pay button, which will redirect the client to Amazon.

<div id=”AmazonPayButton”></div>

<script src=”https://static-na.payments-amazon.com/checkout.js“></script>

<script type=”text/javascript” charset=”utf-8″>

var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’, {

merchantId: ‘xxxxx’,

ledgerCurrency: ‘EUR’,         

checkoutLanguage: ‘en_GB’,

productType: ‘PayAndShip’,

placement: ‘Cart’,

buttonColor: ‘Gold’

});

amazonPayButton.onClick(function(){

// Here you need to call your shop server, which creates the initial Call towards the 1cs Online Payment System

// and then returns the required data payloadJSON, signature, publicKeyId from the response

var buttonData = getSignedButtonData()

amazonPayButton.initCheckout({

    createCheckoutSessionConfig: {

    payloadJSON: buttonData.payloadJSON,

    signature: buttonData.signature,

    publicKeyId: buttonData.publicKeyId

    }

});

</script>

Intermediate response with customer information to your ShopUrl

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters after initializing an Amazon Pay payment.

2.3 Amazon Pay capture a payment

In order to capture an authorized payment with Amazon Pay, please visit the following URL:

The following tables describe the transfer parameters and return values which are exchanged via the socket connection. The server-to-server communication process is described in the manual Programming basics.

Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.  

The following table describes the encrypted payment request parameters:

Encrypted parameters for capturing an authorized Amazon Pay payment

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters after capturing an authorized Amazon Pay payment

After a capture you get a notify to your specified URLNotify with following parameters:

Response parameters to URLNotify after capturing an authorized Amazon Pay payment.

2.4 Amazon Pay credit a payment

In order to credit a captured payment with Amazon Pay, please visit the following URL:

The following tables describe the transfer parameters and return values which are exchanged via the socket connection. The server-to-server communication process is described in the manual Programming basics.

Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.  

The following table describes the encrypted payment request parameters:

Encrypted parameters for crediting an Amazon Pay payment

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Encrypted parameters for crediting an Amazon Pay payment

After a credit you get a notify to your specified URLNotify with following parameters:

Response parameters to URLNotify after credit of an Amazon Pay payment.

2.5 Amazon Pay reverse an order

In order to reverse a complete order with Amazon Pay with the function „CancelOrderReference“, please visit the following URL:

The following tables describe the transfer parameters and return values which are exchanged via the socket connection. The server-to-server communication process is described in the manual Programming basics.

Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter. See separate appendix to the programming manual for cancellation error messages and their causes.

The following table describes the encrypted payment request parameters:

Encrypted parameters for reversal of an Amazon Pay payment

The following table describes the result parameters with which the 1cs Online Payment System responds to your system:

Response parameters after reversing an Amazon Pay payment

3 Amazon Pay Cv2 Additional Payment Button

3.1 Scope

The additional payment button (APB) is a slightly different way to use the Amazon Pay Checkout Cv2. This option can be used with OneTime (OTP) or recurring transactions.

The standard setup of account at Amazon is done just like the regular integration.

The key differences to the “normal” integration are:

• The set payment info (charge amount, total amount & paymentIntent) is done immediately within the button 
• Adress for physical goods has to be sent with the request
• For digital goods no adressDetails are to be sent, this leads to an error
• Mandatory parameter “checkoutMode” is present

APB Specific

This implementation differs from the normal checkout in:

• there is a parameter called checkoutMode that is set to ProcessOrder ‒ this parameter doesn´t exist on the regular checkout!
• When selling physical products, the shippingAddress needs to be sent in the request
• Address of the user for physical goods is different depending on Market, this is important since Amazon performs a validation depending on market

3.2 Process flow

Using only the button to trigger a transaction.

Using our HPP in connection with APB

Payload Example

{

    “webCheckoutDetails”: {

        “checkoutResultReturnUrl”: “https://a.com/merchant-review-page“,

        “checkoutMode”: “ProcessOrder”

    },

    “storeId”: “amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId”,

    “scopes”: [“name”, “email”, “phoneNumber”, “billingAddress”],

    “paymentDetails”: {

        “paymentIntent”: “AuthorizeWithCapture”,

        “chargeAmount”: {

            “amount”: “10”,

            “currencyCode”: “USD”

        },

        “presentmentCurrency”:”USD”

    },

    “merchantMetadata”: {

        “merchantReferenceId”:”Merchant-order-123″,

        “merchantStoreName”:”Merchant Store Name”,

        “noteToBuyer”:”Thank you for your order”

    },

    “addressDetails”: {

        “name”: “Paul Smith”,

        “addressLine1”: “9999 First Avenue”,

        “city”: “New York”,

        “stateOrRegion”: “NY”,

        “postalCode”: “10016”,

        “countryCode”: “US”,

        “phoneNumber”: “212555555”

    }

}

{

    “storeId”: “xxx”,

    “webCheckoutDetails”: {

        “checkoutResultReturnUrl”: “https://merchant1/xxxxxxxx“,

        “checkoutMode”: “ProcessOrder”

    },

    “paymentDetails”: {

        “paymentIntent”: “Confirm”,

        “chargeAmount”: {

            “amount”: “1”,

            “currencyCode”: “JPY”

        }

    },

    //recurring case

    “chargePermissionType”: “Recurring”,

    “recurringMetadata”: {

        “frequency”: {

            “unit”: “Month”,

            “value”: “1”

        },

        “amount”: {

            “amount”: “10”,

            “currencyCode”: “JPY”

        }

    },

    “addressDetails”: {

        “addressLine1”: “%E7%9B%AE%E9%BB%92%E5%8C%BA%E4%B8%8B%E7%9B%AE%E9%BB%92”,

        “addressLine2”: “%EF%BC%91%EF%BC%8D%EF%BC%94%EF%BC%8D%EF%BC%91”,

        “addressLine3”: “%E3%82%A2%E3%83%89%E3%83%AC%E3%82%B9%E3%83%A9%E3%82%A4%E3%83%B3%EF%BC%93”,

        “name”: “%E5%90%8D%E5%89%8D%E3%80%80%E3%83%86%E3%82%B9%E3%83%88%EF%BC%91%EF%BC%92%EF%BC%93”,

        “countryCode”: “JP”,

        “postalCode”: “1560064”,

        “phoneNumber”: “0333333333”

    }

} 

3.3 Integrate Amazon Pay button

The following example code shows how to integrate the Amazon Pay button in your webshop.

When customer submits this button, you will call the 1cs Online Payment System to obtain additional data, which are required for updating the Amazon Pay button.

<div id=”AmazonPayButton”></div>

<script src=”https://static-na.payments-amazon.com/checkout.js“></script>

<script type=”text/javascript” charset=”utf-8″>

var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’, {

    merchantId: ‘xxxxx’,

    ledgerCurrency: ‘EUR’,        

    checkoutLanguage: ‘en_GB’,

    productType: ‘PayAndShip’,

    placement: ‘Cart’,

    buttonColor: ‘Gold’

});

</script>

Button

Further information can be found in the documentation from Amazon Pay.

3.4 Initialize Amazon Pay interface

In order to initialize a payment with Amazon Pay, please use the following URL:

Notice: For security reasons, the 1cs OPS rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Encrypted parameters for initializing an Amazon Pay payment

Intermediate Response with Button additional parameters

The following table describes the result parameters with which the 1cs online payment system responds to your system

be prepared to receive additional parameters at any time and do not check the order of parameters

the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive

Response parameters after initializing an Amazon Pay payment

The following example code shows the updated and complete Amazon Pay button, which will redirect the client to Amazon

<div id=”AmazonPayButton”></div>

<script src=”https://static-na.payments-amazon.com/checkout.js“></script>

<script type=”text/javascript” charset=”utf-8″>

var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’, {

merchantId: ‘xxxxx’,

ledgerCurrency: ‘EUR’,        

checkoutLanguage: ‘en_GB’,

productType: ‘PayAndShip’,

placement: ‘Cart’,

buttonColor: ‘Gold’

});

amazonPayButton.onClick(function(){

// Here you need to call your shop server, which creates the initial Call towards the 1cs Online Payment System

// and then returns the required data payloadJSON, signature, publicKeyId from the response

var buttonData = getSignedButtonData()

amazonPayButton.initCheckout({

    createCheckoutSessionConfig: {

    payloadJSON: buttonData.payloadJSON,

    signature: buttonData.signature,

    publicKeyId: buttonData.publicKeyId

    }

});

</script>

3.5 Address validation

Since the address is to be send by the merchant for APB and we support different markets, this is what will be validated.

EU (including UK)

• EU address validations apply if countryCode is one of the following values:

‘UK’ ,’GB’ ,’DE’ ,’FR’ ,’IT’ ,’ES’ ,’AT’ ,’BE’ ,’BG’ ,’HR’ ,’CY’ ,’CZ’ ,’DK’ ,’EE’ ,’FI’ ,’GR’ ,’HU’ ,’IE’ ,’LV’ ,’LT’ ,’LU’ ,’MT’ ,’NL’ ,’PL’ ,’PT’ ,’RO’ ,’SK’ ,’SI’ ,’SE’

JP

US