Integrating Amazon Pay Checkout Version 2

Amazon Pay button

To show the Amazon Pay button, you want to retrieve the correct configuration-parameters by sending a genericpayment-request with action "createCheckoutSessionPayload" to our server api, to create an Amazon Pay checkout session and retrieving the payload and the signature required for rendering the Amazon Pay button.

You can get all information about rendering button in the amazon developer documentation.

You have to use Payone Public key when rendering the Amazon Pay button. The signature is calculated using Payone’s key pair.

Public key ID: AE5E5B7B2SAERURYEH6DKDAZ

Example: Render Amazon Pay button expand
<!-- Use amazon.Pay.renderButton() to render the Amazon Pay Checkout button to a HTML container element as shown below.-->

<body>
    <div id="AmazonPayButton"></div>
    <script src="https://static-eu.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        const amazonPayButton = amazon.Pay.renderButton('#AmazonPayButton', {
            // set checkout environment
            merchantId: 'merchant_id',
            publicKeyId: 'AE5E5B7B2SAERURYEH6DKDAZ',
            ledgerCurrency: 'EUR',
            // customize the buyer experience
            checkoutLanguage: 'en_GB',
            productType: 'PayAndShip',
            placement: 'Cart',
            buttonColor: 'Gold',
            estimatedOrderAmount: { "amount": "109.99", "currencyCode": "EUR"},
            // configure Create Checkout Session request
            createCheckoutSessionConfig: {
                payloadJSON: 'payload', // payload provided in response of createCheckoutSessionPayload
                signature: 'xxxx', // signature provided in response of createCheckoutSessionPayload
            }
        });
    </script>
</body>

Additional Payment Button (APB)

The Additional Payment Button (APB) can be used for one-time transactions at the end of your checkout flow. APB is typically added at the step where the buyer selects their payment method before completing checkout. Unlike the standard one-time integration, the buyer will not have the opportunity to return to your site to review their order before completing checkout after clicking on the Amazon Pay button, enabling this way express checkout for Amazon Pay.

Main differences from standard one-time integration (with Amazon Pay button)

  • you will skip genericpayment for creating checkout session & button signature. Instead, you will directly submit Pre-/Authorization request
  • you will set payment information ("checkout mode" and "product type") in your Pre-/Authorization request.
  • you will skip displaying shipping/payment info since the buyer will complete checkout on the Amazon Pay hosted page after clicking on the Amazon Pay button.
  • since the Amazon Pay button is at the end of checkout after buyer has already manually entered their shipping address, you must provide that information in request for all physical goods transactions. Providing address information for digital goods transactions will result in an error.

Enable shipping and payment updates

The display of payment and shipping info after retrieval from Amazon, are read only. All updates should take place on Amazon hosted pages. However, you need to enable the possibility in your checkout to update payment instrument and/or shipping address. The user experience once landed in amazon hosted pages is the same for both change types, the buyer can either change on of them or both.

You will need amazonCheckoutSessionId returned to you in response to render the HTML elements in your checkout. Detailed information on enabling shipping and payment updates can be found in the Amazon developer documentation.

API Requests

Before proceeding to specific API requests for Amazon Pay CV2 your should familiarise yourself with the general Payone Server API interface definition as described in Channel Server API - Platform - PAYONE docs.
In this section we will describe the request chain specific remarks for Amazon Pay CV2 integration.

Reservation with Amazon Pay Button

Create Checkout Session & button signature

Use genericpayment request to create an Amazon Pay checkout session and generate payload and signature required for rendering Amazon Pay button. 

In the first step you need to show the Amazon Pay button to the customer.

POST Request - genericpayment – add_paydata[action] = createCheckoutSessionPayload
Account Parameters
request
required
Fixed Value: genericpayment
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
clearingtype
required
Fixed Value: wlt
wallettype
required
Fixed Value: AMP

AMP: Amazon Pay V2

mode
required
Fixed Value: test/live
amount
required
Format Nummeric(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples:

EUR

USD

GBP

Specifies currency for this transaction

successurl
required
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "payment successful"

errorurl
required
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "faulty payment"

backurl
required
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "Back" or "Cancel"

add_paydata Parameters
add_paydata[action]
required
Format: AN..255
Fixed Value: createCheckoutSessionPayload
add_paydata[specialRestrictions]
optional
Format: LIST
  • 'RestrictPOBoxes' - Marks PO box addresses in US, CA, GB, FR, DE, ES, PT, IT, AU as restricted
  • 'RestrictPackstations' - Marks packstation addresses in DE as restricted

Represents shipping address restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book.

Comma separated list in case multiple restrictions apply, example: 

add_paydata[specialRestrictions]= "RestrictPOBoxes,RestrictPackstations"
add_paydata[addressRestrictions_type]
optional
Format: LIST
  • 'Allowed' - Mark addresses that don't match restrictions configuration as restricted
  • 'NotAllowed' - Mark addresses that match restrictions configuration as restricted

Represents the type of shipping address restrictions specified.

Conditional in case shipping address restrictions apply (when add_paydata[specialRestrictions] is present in request)
add_paydata[addressRestrictions_country_[n]]
optional
Format: LIST
Permitted values: ISO 3166 2-letter-codes
Samples:

DE

GB

US

Example: addPayData[addressRestrictions_country_1]="DE"

Country code(s) for the shipping address restrictions related according to the rule specified in add_paydata[addressRestrictions_type]

Conditional in case shipping address restrictions apply (when add_paydata[specialRestrictions] is present in request)

Specifies country of address for the customer

Some countries require additional information in parameter "state"
add_paydata[addressRestrictions_stateOrRegions_[n]]
optional
Format: LIST
Permitted values: Use 2-character state codes (for example: WA, CA, IL)

Example: addPayData[addressRestrictions_stateOrRegions_1]="OH,WA"

List of country-specific states/region that should or should not be restricted based on parameter add_paydata[addPayData[addressRestrictions_type]. It may be present multiple times for each country restriction and can have comma separated value.

Conditional in case shipping address restrictions apply (when add_paydata[specialRestrictions] is present in request)

add_paydata[addressRestrictions__zipCodes_[n]]
optional
Format: LIST
Permitted values: Country-specific Zip Codes

Example: addPayData[addressRestrictions_zipCodes_1]="72046,72047"

List of country-specific zip codes that should or should not be restricted based on parameter add_paydata[addPayData[addressRestrictions_type].  It may be present multiple times for each country restriction and can have comma separated value.

Conditional in case shipping address restrictions apply (when add_paydata[specialRestrictions] is present in request)

Note: Use wild card symbols to skip over variable alphanumeric characters. The "*" symbol will match multiple characters. The "?" symbol will only match a single character
Response Parameters
Permitted Values
OK
ERROR
Response Data (OK)
workorderid
Format CHAR(1..50)

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

add_paydata[signature]
Format CHAR(1..1028)

Signature of the payload, required to render the Amazon Pay button

add_paydata[payload]
Format JSON

Payload required to render the Amazon Pay button
Below the payload object

Response parameters (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Payload Object
Structure of Payload object returned in add_paydata[payload]
webCheckoutDetails
required
Format: Object, Fixed Value: webCheckoutDetails

URLs associated to the Checkout Session used to complete checkout. The URLs must use HTTPS protocol 

checkoutReviewReturnUrl
required
Format: CHAR(2..512)(Sub of webCheckoutDetails)

Checkout review URL provided by the merchant. Amazon Pay will redirect to this URL after the buyer selects their preferred payment instrument and shipping address

Note:
In the Live environment, URLs must use HTTPS protocol. The URL domain must be added to Seller Central. See Add domains to Seller Central for more information.
In Sandbox environment, you don't need a SSL certificate and can use the HTTP protocol if you're testing on localhost (https://docs.payone.com). You don't need to add URLs to the JavaScript Origins in SellerCentral

Max length: 512 characters/bytes

checkoutResultReturnUrl
required
Format: CHAR(2..255)(Sub of webCheckoutDetails)

Checkout result URL provided by the merchant. Amazon Pay will redirect to this URL after completing the transaction

checkoutCancelUrl
optional
Format: CHAR(2..255)(Sub of webCheckoutDetails)

Order object containing lorem ipsum dolor sit amet consectetur

storeId
required
Format: CHAR(2..255)

Amazon Pay store ID. Retrieve this value from Amazon Pay Integration Central: US, EU, JP

scopes
optional
Format: LIST, Fixed Value: scopes

The buyer details requested to have access to. Currently fixed list, comma separated with all supported values.

Supported values:

  • 'name' - Buyer name
  • 'email' - Buyer email
  • 'phoneNumber' - Default billing address phone number
  • 'billingAddress' - Default billing address
chargePermissionType
optional
Format: fixed Value

The type of Charge Permission requested.

'OneTime' - The Charge Permission can only be used for a single order
'Recurring' - The Charge Permission can be used for recurring orders

Note: Only "OneTime" is supported and is fixed. 

deliverySpecifications
optional
Format: Object, Fixed Value: deliverySpecifications

Specify shipping restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book 

specialRestrictions
Format: LIST (Sub of deliverySpecifications)
Permitted Values: RestrictPOBoxes,RestrictPackstations

Rule-based restrictions as it was provided in the genericpayment request, comma separated list

add_paydata[specialRestrictions]="RestrictPOBoxes,RestrictPackstations"


Supported values:

'RestrictPOBoxes' - Marks PO box addresses in US, CA, GB, FR, DE, ES, PT, IT, AU as restricted
'RestrictPackstations' - Marks packstation addresses in DE as restricted

tur

addressRestrictions
Fixed Value: addressRestrictions (Sub of deliverySpecifications)

Country-based restrictions

type
Fixed Value: Allowed, NotAllowed (Sub of deliverySpecifications)

Supported values:

  • 'Allowed' - Mark addresses that don't match restrictions configuration as restricted
  • 'NotAllowed' - Mark addresses that match restrictions configuration as restricted
restrictions
hash<countryCode:restriction>

Hash of country-level restrictions that determine which addresses should or should not be restricted based on request parameter add_paydata[addressRestrictions_type]

statesOrRegions
Format: LIST
List of country-specific states that should or should not be restricted based on request parameters add_paydata[addressRestrictions_country_[n]] and  add_paydata[addressRestrictions_stateOrRegions_[n]]
zipCodes
Format: LIST

List of country-specific zip codes that should or should not be restricted based on request parameters add_paydata[addressRestrictions_country_[n]] and  add_paydata[addressRestrictions_stateOrRegions_[n]]

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload    

add_paydata[action]=createCheckoutSessionPayload
add_paydata[addressRestrictions_country_018ba8e2a8b97122a7b2856cee99dc3b]=DE
add_paydata[addressRestrictions_type]=Allowed
aid=12345
amount=55767
api_version=3.10
backurl=https://sw6.6560.ddev.site/payone/redirect?hash=NjkwMWEyMDNiZTgxZDg5NzcxYTJkYzgwYmQ5NTVlN2Q1NjRjZjlhOGVlMWI5MTM2ZDU5MGUzMGY0ZDQ0ZWRlZA%3D%3D
clearingtype=wlt
currency=EUR
encoding=UTF-8
errorurl=https://yourwebsite.de/payone/redirect?hash=ZWQxZmY5.........MjAyOTBmZA%3D%3D
hash=df539a0ca88583e...........170df4eca0d82
key=abcdefghijklmn123456789
mid=12345
mode=test
portalid=1234567
request=genericpayment
successurl=https://sw6.6560.ddev.site/payone/redirect?hash=NzBkZTc1MmMxOTlmMzFlOGNjMTlmYmI2MGNmNDE4ZjRmN2FmY2Y1ZDVkNDU3YWE1NGNjZDMyMjY2NTk4YTFmYw%3D%3D
wallettype=AMP
RESPONSE

status=OK
workorderid=ZYXTSRQPONMLKJHGF
add_paydata[payload]={
"webCheckoutDetails" : {
"checkoutReviewReturnUrl" : "https://eine-url.de/redirect/review?woid=PABCDEFG12345678",
"checkoutResultReturnUrl" : "https://eine-url.de/redirect/result?woid=PABCDEFG12345678",
"checkoutCancelUrl" : "https://eine-url.de/redirect/cancel?woid=PABCDEFG12345678" },
"storeId" : "amzn1.application-oa2-client.d5c899d..........4a00448",
"scopes" : [ "name", "email", "phoneNumber", "billingAddress" ],
"chargePermissionType" : "OneTime",
"deliverySpecifications" : {
"addressRestrictions" : {
"type" : "Allowed",
"restrictions" : { "DE" : { } } } },
"paymentDetails" : {
"paymentIntent" : "Authorize",
"canHandlePendingAuthorization" : false,
"chargeAmount" : { "amount" : "557.67", "currencyCode" : "EUR" },
"totalOrderAmount" : { "amount" : "557.67", "currencyCode" : "EUR" }, "presentmentCurrency" : "EUR" },
"merchantMetadata" : { }}
add_paydata[signature]=KXq98.........GVBw==
POST Request - genericpayment – add_paydata[action] = getCheckoutSession

Use genericpayment-getCheckoutSession request to retrieve the checkout session details including buyer info, payment instrument details. Use this operation to determine if checkout was successful after the buyer returns from the Amazon Pay hosted pages (AmazonPayRedirectUrl) to the specified successurl and to display retrieved information in your checkout.

Optionally, you can use this request at a second step after the buyer changes decides to change the shipping address or payment instrument on the Amazon Pay hosted page to get the updated information.
Account Parameters
request
required
Fixed Value: genericpayment
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalid
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
clearingtype

required
Fixed Value: wtl
wallettype

required
Fixed Value: AMP

AMP: Amazon Pay

mode

required
Fixed Value: test/live
amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples

EUR

USD

GBP

workorderid
required
Format CHAR(1..50)

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Response Parameters
Permitted Values
OK
ERROR
Response Data (OK)
workorderid
Format AN(1..16)

The ID is unique. The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

add_paydata[buyer_id]
Format CHAR
Unique Amazon Pay buyer identifier
add_paydata[buyer_name]
required
Format CHAR
Buyer name
app_data[email]
required
Format AN(1..255)

Mail of the buyer

app_data[shipping_name]
Format AN(1..255)

First and Lastname of customer

app_data[shipping_firstname]
Format AN(1..255)

Firstname of customer

app_data[shipping_lastname]
Format AN(1..255)

Lastname of customer

app_data[shipping_city]
Format AN(1..255)

City

app_data[shipping_zip]
Format AN(1..20)

Postalcode

app_data[shipping_street]
Format AN(1..255)

Streetname

app_data[shipping_pobox]
Format AN(1..255)

Postbox
In case the customer selected a postbox as shipping destination, you will find the post number (number for the customer, using the postbox) in this field. In addition the parameter add_paydata[shipping_street] will contain the postbox number (number of the postbox the delivery will be shipped to) with a leading "postbox".
PO Box as destination:
add_paydata[pobox]=1234456
add_paydata[shipping_street]=Postbox 12

app_data[shipping_company]
Format AN(1..255)

Companyname

app_data[shipping_county]
Format AN(1..255)

County

app_data[shipping_country]
Country Code (ISO 3166)

Examples: DE,AT,CH,FR,US,GB

app_data[shipping_district]
Format AN(1..255)

District, only in a few countries used

app_data[shipping_telephonenumber]
Format AN(1..50)

Phone number

app_data[shipping_state]
Format AN(1..255)

State or Region

app_data[billing_type]
Format AN(1..255)

Type of destination.

app_data[billing_name]
Format AN(1..255)

First and Lastname of customer

app_data[billing_firstname]
Format AN(1..255)

Firstname of customer

app_data[billing_lastname]
Format AN(1..255)

Lastname of customer

app_data[billing_city]
Format AN(1..255)

City

app_data[billing_zip]
Format AN(1..255)

Postal Code

app_data[billing_street]
Format AN(1..255)

Streetname

app_data[billing_pobox]
Format AN(1..255)

Post box

app_data[billing_company]
Format AN(1..255)

Company

app_data[billing_county]
Format AN(1..255)

County

app_data[billing_country]
Format AN(1..255)

Country

app_data[billing_district]
Format AN(1..255)

District

app_data[billing_telephonenumber]
Format AN(1..255)

Phonenumber of the Customer

app_data[billing_state]
Format AN(1..255)

State or Region

app_data[paymentDescriptor_[n]]
Format AN(1..255)

Amazon Pay-provided description for buyer-selected payment instrument

app_data[amazonCheckoutSessionId]
required

The Amazon Pay checkout session ID. Use the checkout session ID to enable updates of the shipping address or payment instrument by using Amazon Pay bindChangeAction after the buyer returns to your site

Response parameters (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload        

add_paydata[action]=getCheckoutSession
aid=12345
amount=55767
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
hash=6edf8fe7aa7282b76afd05...........2a2344aa44d9cd06
key=abcdefghijklmn123456789
mid=12345
mode=test
portalid=1234567
request=genericpayment
wallettype=AMP
workorderid=ZYXTSRQPONMLKJHGF
RESPONSE

status=OK
workorderid=ZYXTSRQPONMLKJHGF
add_paydata[shipping_state]=Bavaria
add_paydata[shipping_city]=München
add_paydata[buyer_name]=AmzTestbestellung AmzTestbestellung
add_paydata[buyer_id]=amzn1.account.AHX.......XHHDQ
add_paydata[shipping_zip]=80939
add_paydata[billing_zip]=66538
add_paydata[buyer_phoneNumber]=+49123456789
add_paydata[shipping_name]=Max Mustermann
add_paydata[shipping_firstname]=Max
add_paydata[email]=eineemail@email.de
add_paydata[shipping_lastname]=Mustermann
add_paydata[shipping_street]=Schützstraße 123
add_paydata[billing_country]=DE
add_paydata[billing_lastname]=Barker
add_paydata[billing_name]=Liam Barker
add_paydata[billing_street]=Meininger Strasse 58
add_paydata[billing_city]=Neunkirchen
add_paydata[billing_telephonenumber]=+49123456789
add_paydata[amazonCheckoutSessionId]=12345678-abc12-ab12-1234-abcd1234567e
add_paydata[billing_firstname]=Liam
add_paydata[paymentDescriptor_1]=Visa ****1111 (Amazon Pay)
add_paydata[shipping_telephonenumber]=+491731112222
add_paydata[shipping_country]=DE
POST Request - genericpayment – add_paydata[action] = updateCheckoutSession

You want to set all order details and may want to change the amount for example to add shipping fees after obtaining the customer address.

Account Parameters
request
required
Fixed Value: genericpayment
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalid
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
clearingtype
required
Fixed Value: wtl
wallettype
required
Fixed Value: AMP

AMZ: Amazon Pay

successurl
optional
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "payment successful"

mode
required
Fixed Value: test/live
amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples

EUR

USD

GBP

workorderid
required
Format CHAR(1..50)

With the first genericpayment the workorderid will be generated from the PAYONE platform and will be sent to you in the response. The ID is unique. The returned workorderid is mandatory for the following requests of Amazon Express Checkout.

Response Parameters
Permitted Values
OK
ERROR
Response Data (OK)
workorderid
Format AN(1..16)

The ID is unique. The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

add_paydata[buyer_id]
Format CHAR
Unique Amazon Pay buyer identifier
add_paydata[buyer_name]
required
Format CHAR
Buyer name
app_data[email]
required
Format AN(1..255)

Mail of the buyer

app_data[shipping_name]]
Format AN(1..255)

First and Lastname of customer

app_data[shipping_firstname]
Format AN(1..255)

Firstname of customer

app_data[shipping_lastname]
Format AN(1..255)

Lastname of customer

app_data[shipping_city]
Format AN(1..255)

City

app_data[shipping_zip]
Format AN(1..20)

Postalcode

app_data[shipping_street]
Format AN(1..255)

Streetname

app_data[shipping_pobox]
Format AN(1..255)

Postbox
In case the customer selected a postbox as shipping destination, you will find the post number (number for the customer, using the postbox) in this field. In addition the parameter add_paydata[shipping_street] will contain the postbox number (number of the postbox the delivery will be shipped to) with a leading "postbox".
PO Box as destination:
add_paydata[pobox]=1234456
add_paydata[shipping_street]=Postbox 12

app_data[shipping_company]
Format AN(1..255)

Companyname

app_data[shipping_county]
Format AN(1..255)

County

app_data[shipping_country]
Country Code (ISO 3166)

Examples: DE,AT,CH,FR,US,GB

app_data[shipping_district]
Format AN(1..255)

District, only in a few countries used

app_data[shipping_telephonenumber]
Format AN(1..50)

Phone number

app_data[shipping_state]
Format AN(1..255)

State or Region

app_data[billing_type]
Format AN(1..255)

Type of destination.

app_data[billing_name]
Format AN(1..255)

First and Lastname of customer

app_data[billing_firstname]
Format AN(1..255)

Firstname of customer

app_data[billing_lastname]
Format AN(1..255)

Lastname of customer

app_data[billing_city]
Format AN(1..255)

City

app_data[billing_zip]
Format AN(1..255)

Postal Code

app_data[billing_street]
Format AN(1..255)

Streetname

app_data[billing_pobox]
Format AN(1..255)

Post box

app_data[billing_company]
Format AN(1..255)

Company

app_data[billing_county]
Format AN(1..255)

County

app_data[billing_country]
Format AN(1..255)

Country

app_data[billing_district]
Format AN(1..255)

District

app_data[billing_telephonenumber]
Format AN(1..255)

Phonenumber of the Customer

app_data[billing_state]
Format AN(1..255)

State or Region

app_data[paymentDescriptor_[n]]
Format AN(1..255)

Amazon Pay-provided description for buyer-selected payment instrument

app_data[amazonCheckoutSessionId]
required

The Amazon Pay checkout session ID. Use the checkout session ID to enable updates of the shipping address or payment instrument by using Amazon Pay bindChangeAction after the buyer returns to your site

Response parameters (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload          

add_paydata[action]=getCheckoutSession
aid=12345
amount=55767
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
hash=6edf8fe7aa7282b76afd05...........2a2344aa44d9cd06
key=abcdefghijklmn123456789
mid=12345
mode=test
portalid=1234567
request=genericpayment
wallettype=AMP
workorderid=ZYXTSRQPONMLKJHGF
RESPONSE
status=OK add_paydata[shipping_street]=Schützstraße 123 add_paydata[shipping_city]=München add_paydata[shipping_type]=Physical add_paydata[billing_country]=DE add_paydata[storename]=Deutsch add_paydata[billing_lastname]=Mustermann add_paydata[billing_name]=Erika Mustermann add_paydata[billing_street]=Marcel-Breuer-Straße 12 add_paydata[billing_city]=München add_paydata[billing_telephonenumber]=+491731112222 add_paydata[workorderid]=WX1A1DZ26ET8UXWN add_paydata[billing_company]=Fiktive Firma add_paydata[shipping_zip]=80939 add_paydata[billing_type]=Physical add_paydata[billing_zip]=80807 add_paydata[billing_firstname]=Erika add_paydata[shipping_name]=Max Mustermann add_paydata[shipping_firstname]=Max add_paydata[shipping_telephonenumber]=+491731112222 add_paydata[shipping_country]=DE add_paydata[shipping_lastname]=Mustermann add_paydata[email]=pui-test@payone.de workorderid=ZYXTSRQPONMLKJHGF
POST Request - Pre-/ Authorization
Account Parameters
request
required
Fixed Value: preauthorisation/authorization
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalid
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
clearingtype
required
Fixed Value: wtl
mode
required
Fixed Value: test/live

Can be either test environment (test) or live environment (live)

workorderid
required
Format AN(1..16)

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

reference
required
Format CHAR(2..255)

A Merchant reference number for the payment process (case insensitive). Its a unique ID, that will be displayed in your shop backend and for the customer. It must be the same as given in add_paydata[reference]=1224900480 previously

amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples

EUR

USD

GBP

add_paydata[mail_text]
optional
Format CHAR(1..255)

Description displayed in emails to the buyer

narrative_text
optional
Format CHAR(1..81)

Dynamic text element on account statements (3 lines with 27 characters each) and credit card statements.

PERSONAL DATA Parameters
customerid
optional
Format CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]

Merchant's customer ID, defined by you / merchant to refer to the customer record.

"customerid" can be used to identify a customer record. 
If "customerid" is used then stored customer data are loaded automatically.
userid
optional
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE

businessrelation
optional
Format LIST
Value Comment
b2c

Indicates business to private customer

b2b

indicates business to business customer (company)

currently not available for PDD

Value specifies business relation between merchant and customer

salutation
optional
Format CHAR(1..10)

The customer's salutation

title
optional
Format CHAR(1..20)
Samples

Dr

Prof.

Dr.-Ing.

Title of the customer

firstname
optional
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

lastname
required
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

company
optional
Format CHAR(2..50)

Comany name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

street
optional
Format CHAR(1..50)

Street number and name (required: at least one character)

addressaddition
optional
Format CHAR(1..50)
Samples

7th floor

c/o Maier

Specifies an additional address line for the invoice address of the customer.

zip
optional
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode

city
optional
Format CHAR(2..50)

City of customer

country
required
Fixed Value DE
state
optional
Format LIST
Permitted values: ISO 3166-2 States (regions) 2-letter-codes
Samples US Samples CA
AK AB
AL BC

Specifies state / region of country for the customer.
"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries.

email
optional
Format CHAR(5..254)

Mandatory if "add_paydata[shopping_cart_type]=DIGITAL"

Permitted Symbols RFC 5322

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

Username = Max. 63 characters

Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters 
Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]

"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

email-address of customer

telephonenumber
optional
Format CHAR(1..30)

Phone number of customer

birthday
optional
Format DATE(8), YYYYMMDD
Samples

20190101

19991231

Date of birth of customer

language
optional
Format LIST
Permitted values ISO 639-1 (Language)2-letter-codes

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display). If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

vatid
optional
Format CHAR(1..50)

VAT identification number. Used for b2b transactions to indicate VAT number of customer.

gender
optional
Format LIST
Permitted values f/ m/  d

Gender of customer (female / male / diverse* )

* currently not in use

personalid
optional
Format CHAR(1..32)
Permitted Symbols [0-9][A-Z][a-z][+-./()]

Person specific numbers or characters, e.g. number of passport / ID card

ip
optional
Format CHAR(1..39)

Customer's IP-V4-address (123.123.123.123) or IP-V6-address

Delivery data Parameters
shipping_firstname
required
Format CHAR(1..50)

First name of delivery address

shipping_lastname
required
Format CHAR(1..50)

Surname of delivery address

shipping_company
optional
Format CHAR(2..50)

Company name of delivery address

shipping_street
optional
Format CHAR(2..50)

Street number and name of delivery address

shipping_zip
required
Format CHAR(2..50)

Postcode of delivery address

shipping_addressaddition
optional
Format CHAR(1..50)

Specifies an additional address line for the delivery address of the customer, e.g. "7th floor", "c/o Maier".

shipping_country
optional
Format LIST
Permitted values ISO 3166 2-letter-codes
Samples

DE

GB

US

Specifies country of address for the customer.

Some countries require additional information in parameter "state"

shipping_state
optional
Format LIST
Permitted values ISO 3166-2 States (regions)  2-letter-codes
Samples US Samples CA
AK BC
AB AR

Specifies state / region of country for the customer. 
"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries

Wallet PARAMETERS
wallettype

required
Fixed Value AMP
successurl
required
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "payment successful"

errorurl
required
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "faulty payment"

backurl
required
Format CHAR(2..255)

Scheme <scheme>://<host>/<path>
       <scheme>://<host>/<path>?<query>
       
scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL for "Back" or "Cancel"

Response Parameters
Permitted Values
REDIRECT
ERROR
Response Parameter (REDIRECT)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

redirecturl
Format CHAR(2..2000)

Redirect URL → zMerchant system has to redirect customer to this URL to complete payment

workorderid
Format AN(1..16)

The ID is unique. The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

add_paydata[buyer_id]
Format CHAR
Unique Amazon Pay buyer identifier
add_paydata[buyer_name]
required
Format CHAR
Buyer name
app_data[email]
required
Format AN(1..255)

Mail of the buyer

add_paydata[buyer_phoneNumber]
required
Format AN(1..50)

Buyer phone number

app_data[shipping_name]]
Format AN(1..255)

First and Lastname of customer

app_data[shipping_firstname]
Format AN(1..255)

Firstname of customer

app_data[shipping_lastname]
Format AN(1..255)

Lastname of customer

app_data[shipping_city]
Format AN(1..255)

City

app_data[shipping_zip]
Format AN(1..20)

Postalcode

app_data[shipping_street]
Format AN(1..255)

Streetname

app_data[shipping_pobox]
Format AN(1..255)

Postbox

In case the customer selected a postbox as shipping destination, you will find the post number (number for the customer, using the postbox) in this field. In addition, the parameter add_paydata[shipping_street] will contain the postbox number (number of the postbox the delivery will be shipped to) with a leading "postbox".
app_data[shipping_company]
Format AN(1..255)

Companyname

app_data[shipping_county]
Format AN(1..255)

County

app_data[shipping_country]
Country Code (ISO 3166)

Examples: DE,AT,CH,FR,US,GB

app_data[shipping_district]
Format AN(1..255)

District, only in a few countries used

app_data[shipping_telephonenumber]
Format AN(1..50)

Phone number

app_data[shipping_state]
Format AN(1..255)

State or Region

app_data[paymentDescriptor_[n]]
Format AN(1..255)

Amazon Pay-provided description for buyer-selected payment instrument and useful for display at review order page.

Response Parameter (Error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload
add_paydata[amazon_reference_id]=A00-1234567-9876543 add_paydata[amazon_timeout]=0 add_paydata[cancel_on_timeout]=yes request=preauthorization
aid=12345
mid=12345
portalid=1234567
key=abcdefghijklmn123456789
clearingtype=wlt wallettype=AMP amount=12000 currency=EUR mode=test workorderid=ZYXTSRQPONMLKJHGF reference=ABCDEF12378ABC add_paydata[mail_text]="Vielen Dank für Ihre Bestellung hier sind die details" successurl=https://yourdomain.de/amazonpay/returned/ errorurl=https://yourdomain.de/amazonpay/cancel?error=1/ backurl=https://yourdomain.de/amazonpay/cancel/
RESPONSE 

status=REDIRECT                        
txid=985903934
userid=655785762
redirecturl=https://payments.amazon.de/checkout/processing?amazonCheckoutSessionId=abcdefg-abcd-1234-abcd-abcd12345
add_paydata[shipping_city]=Maxhausen
add_paydata[buyer_name]=Max Muster
add_paydata[buyer_id]=amzn1.account.ABCD ...CXYZ
add_paydata[shipping_zip]=12345
add_paydata[billing_zip]=12345
add_paydata[buyer_phoneNumber]=+491712345678
add_paydata[shipping_name]=Max Muster
add_paydata[shipping_firstname]=Max
add_paydata[email]=maxmustertesting@googlemail.com
add_paydata[shipping_lastname]=Muster
add_paydata[shipping_street]=Musterstrasse 1
add_paydata[billing_country]=DE
add_paydata[billing_lastname]=Muster
add_paydata[billing_name]=Max Muster
add_paydata[billing_street]=Musterstrasse 1
add_paydata[billing_city]=Musterstadt
add_paydata[billing_telephonenumber]=+49(171)2345678
add_paydata[amazonCheckoutSessionId]=abcdefg-abcd-1234-abcd-abcd12345
add_paydata[billing_firstname]=Max
add_paydata[paymentDescriptor_1]=Muster BANK AG... ****123 (Amazon Pay)
add_paydata[shipping_telephonenumber]=+49(171)2345678
add_paydata[shipping_country]=DE
POST Request - Capture
Account Parameters
request
required
Fixed Value: capture
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalid
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
txid
required
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

sequencenumber
optional
Format NUMERIC(1..3)
Permitted values 0..127

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

For partial captures, capturemode is also required

amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Fixed Value EUR
narrative_text
optional
Format CHAR(1..81)

Dynamic text element on account statements (3 lines with 27 characters each) and credit card statements.

Response Parameters
Permitted Values
APPROVED
PENDING
ERROR
Response Parameter (approved)
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

Format LIST
Value Comment
yes Settlement of outstanding balances has been carried out.
no Settlement of outstanding balances has not been carried out.

Provides information about whether a settlement of balances has been carried out.

Response parameters (pending)
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE

Response parameters (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload (partial captures)
capture 1 (notcompleted) add_paydata[amazon_reference_id]=A00-1234567-9876543 aid=12345 amount=10000 capturemode=notcompleted currency=EUR key=abcdefghijklmn123456789
mid=12345 mode=test portalid=1234567
request=capture txid=123456789 workorderid=WX1AABCDEFGHIJL8K
Payload (2nd capture)
add_paydata[amazon_reference_id]=A00-1234567-9876543 aid=12345 amount=2000 capturemode=completed
currency=EUR
key=abcdefghijklmn123456789
mid=12345
mode=test
portalid=1234567
request=capture sequencenumber=2 txid=123456789
workorderid=WX1AABCDEFGHIJL8K
RESPONSE
status=APPROVED txid=345678901 settleaccount=yes
POST Request - Debit
Account Parameters
request
required
Fixed Value: debit
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalid
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
Common Parameters
txid
required
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

sequencenumber
required
Format NUMERIC(1..3)
Permitted values 0..127

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, Capture1: 1, Capture2: 2, Refund1: 3, Refund2: 4 etc

Required for multi partial capture (starting with the 2nd capture)

amount
required
Format NUMERIC(1..10)
Permitted values max. - 19 999 999 99

Specifies the total gross amount of refund, if partial it will be amount of partial refund.

Value is given in smallest currency unit, e.g. Cent of Euro; and the Value is a negative number

currency
required
Fixed Value EUR
Article Parameters
it[n]
optional
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount
id[n]
optional
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [400]
Permitted Symbols [0-9][a-z][A-Z], .,-,_,/

International Article Number (EAN bzw. GTIN)

Product number, SKU, etc. of this item

pr[n]
optional
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]

Unit gross price of the item in smallest unit! e.g. cent. Value negative for refund like -1500 for refund of 15 EUR

no[n]
optional
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
optional
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [400]

Description of this item. Will be printed on documents to customer.

va[n]
optional
Format NUMERIC(4)

VAT rate (% or bp)

Array elements [n] starting with [1]; serially numbered; max [400]

Response Parameters
status
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

settleaccount
Format LIST
Value Comment
yes Settlement of outstanding balances has been carried out.
no Settlement of outstanding balances has not been carried out.

Provides information about whether a settlement of balances has been carried out.

Response Parameter (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload
                    
request=debit mid=12345 aid=12345 portalid=1234567
key=abcdefghijklmn123456789
mode=test txid=935037887 sequencenumber=3 amount=-4500 currency=EUR de[1]=Hauptartikel mit Kennzeichnung Versandkostenfrei und Hervorhebung de[2]=Express Versand id[1]=SW10006 id[2]=Express Versand it[1]=goods it[2]=shipment no[1]=3 no[2]=1 pr[1]=-1500 pr[2]=0 va[1]=1900 va[2]=0
RESPONSE
status=APPROVED txid=935037887 settleaccount=yes

Specials

Error Codes

Common errors
Full list of platform error codes can be found in Error messages.

Errorcode 993

Throttling is the process of limiting the number of requests you can submit to a given operation in a given amount of time. Such limits are exclusively maintained on the Amazon side. Throttling protects the web service from being overwhelmed with requests.

Requests that have been throttled will return a dedicated error code as below. Retry mechanism is recommended to be implemented in case a throttling is identified.

Detailed information on throttling limits applied by Amazon can be found in Amazon Developer Portal

Error Description Suggested Activity
993 Too many requests at external service provider Please try again later.

Errorcode 903

In case you get the errorcode 903, the transaction timed out at amazon. This is a common error for synchronous transactions. You can retry the synchronous transaction, however, retry does not guarantee a successful response.

Error Description Suggested Activity
903 No connection to external service provider possible (timeout, breakdown) Please try again later.

Errorcode 980

In case you get the errorcode 980, the transaction timed out at amazon. This is a common error for synchronous transactions. You can retry the synchronous transaction, however, retry does not guarantee a successful response.
Otherwise you can request to process the transaction asynchronously by specifying add_paydata[processing_mode] = asynchronous parameter. That will try to complete the transaction in asynchronous mode. You then get a approved status and can tell the customer, that the processing is still in progress and that you will inform for example via mail, if the transaction was successful or not. For more information please check Asynchronous processing

Error Description Suggested Activity
980 The transaction cannot complete successfully. Try to authorize the payment via asynchronous mode.

- Chinese characters are not supported by the PAYONE platform
- Partial Captures are supported but the customers account will be debited with the Preauthorization
- Partial Refunds are not supported
- Reversal is not supported

Sequence Diagrams

Pre-authorization - standard integration

Pre-authorization - Additional Payment Button (APB)

Reverse

Capture

Capture 2

Refund

Notify

Configure Amazon Account with Payone platform

Authorising PAYONE as third-party developer on your Amazon account

When integrating Amazon Pay CV2, you as a merchant, will need to authorise PAYONE to process Amazon Pay requests on your behalf by adding PAYONE as allowed 3rd party on your seller central section.  This process is considered Delegation,

1
Add PAYONE as third-party developer

Login to your Seller Central account. 
To add Payone as Developer, please navigate to Settings/User Permissions menu and scroll down to section “Third-party developer and apps”, click to “Manage your apps” (Amazon Manage your apps ).

Settings/User Permissions

Third-party developer and apps

Manage your apps

Authorize PAYONE as Developer

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

2
MWS Authorization Token

Next step is to retrieve the MWS Authorization Token generated in the previous step and shown below and store it with PAYONE.

You should then submit the received "Seller ID" and "MWS Authorisation Token" on a secure way to PAYONE Helpdesk for Amazon Pay CV2 onboarding and configuration.

Additionally you should store with Payone your Store Id along with Seller ID (Merchant ID) and MWS Authorzation Token.

3
IPN Configuration Setting

Handling of Instant Payment Notifications for your integration of Amazon Pay with PAYONE goes through PAYONE. Therefore you would need to configure PAYONE endpoints in your integration settings  as shown below.

If you are already using Amazon Pay CV1 with PAYONE, you should set "Merchant URL" with the URL: https://gpc-sys.pay1.de/gpc/amazon/1.1/notify, otherwise you can leave it empty.

You should set the "Integrator URL" as shown below with the URL: https://gpc-sys.pay1.de/gpc/amazon2/1.1/notify