Table Of Contents
  INTRODUCTION  INTEGRATION STEPS  API REQUESTS  SEQUENCE DIAGRAM

Introduction

The Additional Payment Button (APB) can be used for one-time transactions at the end of your checkout flow. It provides a better user experience as 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. Once landed on Amazon Pay hosted page, the buyer can select the preferred payment instrument, review the order and complete checkout.

Integration steps

The steps required to to integrate and display the Additional Payment Button (APB) are less compared to standard Amazon Pay button. Main differences when considering rendering and displaying APB are explained in the below section:

  • you will skip genericpayment for creating checkout session & button signature. Instead, you will directly submit Pre-/Authorization request and get APB Payload and signature in response. Use the APB Payload and signature to render the Amazon Pay Button using amazon.Pay.renderButton() script.
  • 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
  • you will skip the step for sending order/amount updates
  • since the Additional 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.

API Requests

As the additional payment button is rendered at the last step of your checkout where the shipping address has already been collected, the API requests/response are slightly different from the standard Amazon Pay CV2 integration.

Reservation with APB
Pre-/Authorization request
Use the pre-/authorization request to retrieve the payload needed to render the APB. Shipping address along with add_paydata[checkoutMode] and add_paydata[productType] are required for APB as illustrated in the section "Additional data for the Additional Payment Button" of the request.

The customer will be redirected to Amazon Pay hosted pages to complete the payment processing. Here you can set the standard successurl/errorurl/backurl.

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
add_paydata[platform_id]
optional
AN..255
If you are a merchant, do not enter a platform_id. This is only used by solution providers, for whom it is required. It represents the SellerId of the solution provider that developed the eCommerce platform.
add_paydata[storename]
optional
AN..50

Merchant store name.

Setting this parameter will override the default value configured in Seller Central (US, EU, JP). The store name is shared in buyer communication and in the buyer transaction history on the Amazon Pay website
add_paydata[note_to_buyer]
optional
AN..255

Description of the order that is shared in buyer communication sent by Amazon.

Do not store sensitive data about the buyer or the transaction in this field. Sensitive data includes, but is not limited to:

government-issued identification, bank account numbers, or credit card numbers
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
required
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 Mandatory for Additional Payment Button integration type for orders with physical goods as indicated with add_paydata[productType]=PayAndShip
shipping_lastname
required
Format CHAR(1..50)

Surname of delivery address. Mandatory for Additional Payment Button integration type for orders with physical goods as indicated with add_paydata[productType]=PayAndShip
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. Mandatory for Additional Payment Button integration type for orders with physical goods as indicated with add_paydata[productType]=PayAndShip
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
add_paydata[checkoutMode]
optional
Fixed Value: 'ProcessOrder'

'ProcessOrder' - Buyer will complete checkout on the Amazon Pay hosted page immediately after clicking on the Amazon Pay button. Specify how the buyer will complete the checkout.  In the case of APB the buyer will not return to merchant site to review the order.

Required only for Additional Payment Button
add_paydata[productType]
optional
Fixed Value 'PayAndShip' or 'PayOnly'

Product type selected for checkout
'PayAndShip' - Select PayAndShip if you are selling a physical product. You must pass the buyer's shipping address in the request
'PayOnly' - Select PayOnly if you are selling a digital product
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"
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 "faulty payment"
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 "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
add_paydata[payload]
JSON

Payload required to render the Amazon Pay button.

See here for a Payload example: https://developer.amazon.com/de/docs/amazon-pay-checkout/add-the-amazon-pay-button.html#2-generate-the-create-checkout-session-payload 
add_paydata[signature]
Format CHAR(1..1028)
Signature of the payload, required to render the Amazon Pay button
add_paydata[publickeyid]
Format AN
Public Key ID for rendering Amazon Pay button.
Default value: 'AE5E5B7B2SAERURYEH6DKDAZ'
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")
Payload Object
Structure of Payload object returned in add_paydata[payload]
web​Checkout​Details
required
Format: Object, Fixed Value: webCheckoutDetails

URLs associated to the Checkout Session used to complete checkout. The URLs must use HTTPS protocol 
checkout​Review​ReturnUrl
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
checkout​Result​ReturnUrl
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
checkout​CancelUrl
optional
Format: CHAR(2..255)(Sub of webCheckout​Details)

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
charge​PermissionType
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. 
paymentDetails
optional
Format: Object, Fixed Value: paymentDetails

Payment details specified by the merchant, such as the amount and method for charging the buyer 
paymentIntent
Fixed Value:  (Sub of deliverySpecifications)

Payment flow for charging the buyer. It is a value depending on the request pre-/authorization:

'Authorize' - when using preauthorization request
'AuthorizeWithCapture'  -  when using authorization request
totalOrder​Amount
Format: Object, Fixed Value: totalOrderAmount

The total order amount
amount
Format: Numeric
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
Format: LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples

EUR

USD

GBP
chargeAmount
Format: Object, Fixed Value: chargeAmount
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]]
amount
Format: Numeric

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.
Format: LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples

EUR

USD

GBP
addressDetails
Format: Object, Fixed Value: addressDetails
Shipping address details as selected by the buyer before and submitted with pre-/authorization request, example:   
     { "name": "Alfred Amazing",
        "addressLine1": "Fraunhofer 2",
        "city": "München",
        "stateOrRegion": "",
        "postalCode": "80939",
        "countryCode": "DE",
        "phoneNumber": "012345678"}
 
Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload

aid=12345
mid=23456
portalid=12345123
key=abcdefghijklmn123456789
amount=1500
api_version=3.10
clearingtype=wlt
wallettype=AMP
company=Amaze Me GmbH
country=DE
currency=EUR
email=test@payone.com
encoding=UTF-8
firstname=Alfred
lastname=Amazing
mode=test
reference=REFERENCE123
request=authorization
salutation=Herr
shipping_city=München
shipping_company=Amaze Me GmbH
shipping_country=DE
shipping_firstname=Alfred
shipping_lastname=Amazing
shipping_street=Fraunhofer 2
shipping_zip=80939
street=streetname
city=München
telephonenumber=012345678
zip=01234  
successurl=https://yourdomain.de/amazonpay/returned/
errorurl=https://yourdomain.de/amazonpay/cancel?error=1/
backurl=https://yourdomain.de/amazonpay/cancel/
   
Response

status=REDIRECT
txid=12345678
userid=789654
redirecturl=https://your.shop.com/returnpage.php?status=success
add_paydata[payload]={
  "webCheckoutDetails": {
    "checkoutReviewReturnUrl": "https://gpc-sys.pay1.de:443/gpc/amazon2/1.0/redirect/review?woid=PP2AAVMJJN1G66S5",
    "checkoutResultReturnUrl": "https://gpc-sys.pay1.de:443/gpc/amazon2/1.0/redirect/result?woid=PP2AAVMJJN1G66S5",
    "checkoutCancelUrl": "https://gpc-sys.pay1.de:443/gpc/amazon2/1.0/redirect/cancel?woid=PP2AAVMJJN1G66S5"
  },
  "storeId": "amzn1.application-oa2-client.ba4bf2d577134e379532455408220592",
    "scopes": [
        "name",
        "email",
        "phoneNumber",
        "billingAddress"
    ],
    "chargePermissionType": "OneTime",
    "paymentDetails": {
        "paymentIntent": "Authorize",
        "canHandlePendingAuthorization": false,
        "chargeAmount": {
            "amount": "15.00",
            "currencyCode": "EUR"
        },
        "totalOrderAmount": {
            "amount": "15.00",
            "currencyCode": "EUR"
        },
        "presentmentCurrency": "EUR"
    },
    "merchantMetadata": {
        "merchantReferenceId": "REFERENCE123"
    },
    "addressDetails": {
        "name": "Alfred Amazing",
        "addressLine1": "Fraunhofer 2",
        "city": "München",
        "stateOrRegion": "",
        "postalCode": "80939",
        "countryCode": "DE",
        "phoneNumber": "012345678"
    }
}
add_paydata[signature]=TYFXPSi[...]Y7wJirXoyyXbtadogqm2xAkM0vQg==
add_paydata[publickeyid]=AE5E5B7B2SAERURYEH6DKDAZ

Sequence Diagram

Pre-authorization - Additional Payment Button (APB)

.