Table Of Contents
  AMAZON V1 INTEGRATION  AMAZON PAY BUTTON  SHOW WIDGET AND RETRIEVE CUSTOMER DATA  CONFIRM ORDER  INITIALIZING THE CONFIRMATION AND FINALIZE THE ORDER  REQUESTS  ADDITIONAL INFORMATION  SEQUENCE DIAGRAMS  SALE  CONFIGURATION IN SELLER CENTRAL (AMAZON BACKEND)  ACQUIRE FULL ADDRESS DATA  SIMULATION  COMMON ERRORS

Amazon V1 Integration

amazon pay button

To show the Amazon Pay button, you want to retrieve the correct configuration-parameters by sending a genericpayment-request with action "getconfiguration" to our server api.
You can get all information about the button widget in amazon developer documentation:

https://pay.amazon.com/de/developer/documentation/lpwa/201952050

→  Genericpayment getconfiguration

Show widget and retrieve customer data

After the customer clicked the amazon Pay button, he needs to authenticate his amazon account. If authentication was successful, you now need to display the amazon widgets, to let the customer choose his shipping-address and the favourite payment-method, he has configured in his amazon account. You can find details for widget integration provided by amazon here https://pay.amazon.com/de/developer/documentation/lpwa/201952070

At the end the customer clicks “next/order now”. At this point, you can obtain the address_consent_token from the widget, which you need for the next steps.

An example checkout page:

  1. You now need to send a getorderreferencedetails request to payone api, to get full address-data-
  2. You send a setorderreferencedetails request to payone api, to change details of the order, like shipping-cost based on shipping address data obtained by getorderreferencedetails request. This step is mandatory.

→ getorderreferencedetails request

→ setorderreferencedetails request

Confirm order

You have finished all order details and retrieved customer data. You now want to confirm the order to amazon, so that amazon can now check the authentication status of the customer. To do this, you send a genericpayment-request with action "confirmorderdetails" to us with a success- and a error-url, where the customer can be redirected to after the sca-challenge has been done.

→ confirmorderreference request

Initializing the confirmation and finalize the order

To finish the order, you now need to use the javascript offered by amazon to initiate the confirmation of the order. This javascript will check the sca status of the order and routes the customer to the amazon pay sca challenge website. If the selected payment method of the customer needs to be authenticated, then the customer now needs to do the sca challenge (and amazon checks, if you sent the confirmorder-request mentioned above). The customer will then be redirected to your shop, depending on the challenge result (success or error page). After this step is done, you can now send a authorization-requests to our server api to process the order via PAYONE.

If the customer gets redirected to your shop, we will send a get-parameter ("authenticationstatus") appended to the shop-url, that indicates if the sca challenge was successful, failed or abandoned.

Successful
you can continue to finalize the order

Failed
You need to show the customer a errormessage and let him choose another payment method

Abandoned
You need to show the amazon payment method widget again and the customer needs to select another payment method and can try to finalize the order again.

→ Amazon Pay JavaScript documentation for initializing the confirmation

→ Preauthorization/Authorization

If the customer selected a payment method, that doesn't need to be challegened, then the customer will be redirected to the sca challenge website and directly back to your shop url (scuccess or error, depending on the payment method status).

Requests

POST Request - genericpayment – add_paydata[action] = getconfiguraton

To show the Amazon Pay button, you want to retrieve the correct configuration-parameters by sending a genericpayment-request with action "getconfiguration" to our server api.

You can get all information about the button widget in amazon developer documentation:
https://pay.amazon.com/de/developer/documentation/lpwa/201952050

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: AMZ

AMZ: Amazon Pay
mode
required
Fixed Value: test/live
amount
required
Fixed Value: 0

As only the configuration is requested, the amount is set to zero
currency
required
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples

EUR

USD

GBP
add_paydata Parameters
add_paydata[action]
required
AN..255

Set to "getconfiguration"
Response Parameters
Permitted Values
OK
ERROR
Response Data (OK)
workorderid
Format AN(1..16)

The ID is unique. The returned workorderid is mandatory for the following requests of Amazon Express Checkout.

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.
app_data[client_id]
Format AN(1..255)

This is a unique Client ID for Amazon. Find the ID in Amazon Seller Central. Amazon button needs this id too.
app_data[seller_id]
Format AN(1..255)

This is a unique Seller ID for Amazon. Find the ID in Amazon Seller Central. Amazon button needs this id too.
Response parameters (error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
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]=getconfiguration
request=genericpayment
aid=54400
mid=54399
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
clearingtype=wlt
wallettype=AMZ
mode=test
amount=0
currency=EUR
RESPONSE

status=OK
add_paydata[seller_id]=ABCDEFG123456
add_paydata[client_id]=amzn1.application-oa2-client.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
workorderid=WX1A8DZ26B1DDU4H
POST Request - genericpayment – add_paydata[action] = getorderreferencedetails

After the customer clicked the amazon Pay button, he needs to authenticate his amazon account. If authentication was successful, you now need to display the amazon widgets, to let the customer choose his shipping-address and the favourite payment-method, he has configured in his amazon account.
At the end the customer clicks “next/order now”. At this point, you can obtain the address_consent_token from the widget, which you need for the next steps.

You can find details for widget integration provided by amazon developer documentation:
https://pay.amazon.com/de/developer/documentation/lpwa/201952070

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: AMZ

AMZ: 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)

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.
add_paydata Parameters
add_paydata[action]
required
AN..255

Set to "getorderreferencedetails"
add_paydata[amazon_address_token]
required
Format CHAR(1..81)

The Amazon order reference ID, that is returned by the widgets in the shop implementation.
add_paydata[amazon_reference_id]
required
Format CHAR(1..81)

This token is available after the buyer has successfully authenticated using Login with Amazon and is returned by Amazon Pay button’s auth function. This process is not part of the API integration but a result of the widget implementation within the respective shop system or custom implementation. Complete buyer information will only be returned after you have specified a valid AddressConsentToken in the GetOrderReferenceDetails operation. Until then, only the City, PostalCode, and CountryCode elements are returned.
Response Parameters
Permitted Values
REDIRECT
ERROR
Response Data (REDIRECT)
workorderid
Format AN(1..16)

The ID is unique. The returned workorderid is mandatory for the following requests of Amazon Express Checkout.

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.
app_data[email]
Format AN(1..255)

Mail of the buyer
app_data[storename]
Format AN(1..255)

Identifier of the store. Sending this parameter overrides the default value in amazon seller central under “Settings -> Account Settings”.
app_data[expiration_timestamp]
Format AN(1..255)

Timestamp (ISO 8601) indicating when authorization expires and capture is not possible anymore.
app_data[shipping_type]
Format AN(1..255)

Type of destination.
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
Response parameters (error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
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                    

request=genericpayment
aid=54400
mid=54399
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
clearingtype=wlt
wallettype=AMZ
amount=12000
currency=EUR
mode=test
add_paydata[action]=getorderreferencedetails
add_paydata[amazon_address_token]=Atza|verylongalphaNUMMERICcharsetWithSpecialCharacters (obtained by widgets)
add_paydata[amazon_reference_id]=A00-1234567-9876543 (obtained by widgets)
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[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=WX1A1DZ26ET8UXWN

POST Request - genericpayment – add_paydata[action] = setorderreferencedetails

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: AMZ

AMZ: 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)

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.
add_paydata Parameters
add_paydata[action]
required
AN..255

Set to "setorderreferencedetails"
add_paydata[amazon_address_token]
required
Format CHAR(1..81)

The Amazon order reference ID, that is returned by the widgets in the shop implementation.
add_paydata[amazon_reference_id]
required
Format CHAR(1..81)

This token is available after the buyer has successfully authenticated using Login with Amazon and is returned by Amazon Pay button’s auth function. This process is not part of the API integration but a result of the widget implementation within the respective shop system or custom implementation. Complete buyer information will only be returned after you have specified a valid AddressConsentToken in the GetOrderReferenceDetails operation. Until then, only the City, PostalCode, and CountryCode elements are returned.
add_paydata[platform_id]
required
Format CHAR(1..81)

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]
required
Format CHAR(1..81)

Identifier of the store. Sending this parameter overrides the default value in amazon seller central under “Settings -> Account Settings”.
Response Parameters
Permitted Values
REDIRECT
ERROR
Response Data (REDIRECT)
workorderid
Format AN(1..16)

The ID is unique. The returned workorderid is mandatory for the following requests of Amazon Express Checkout.

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.
app_data[email]
Format AN(1..255)

Mail of the buyer
app_data[storename]
Format AN(1..255)

Identifier of the store. Sending this parameter overrides the default value in amazon seller central under “Settings -> Account Settings”.
app_data[expiration_timestamp]
Format AN(1..255)

Timestamp (ISO 8601) indicating when authorization expires and capture is not possible anymore.
app_data[shipping_type]
Format AN(1..255)

Type of destination.
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
Response parameters (error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
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                    

request=genericpayment
aid=54400
mid=54399
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
clearingtype=wlt
wallettype=AMZ
amount=12000
currency=EUR
mode=test
workorderid=WX1A1DZ26ET8UXWN
add_paydata[action]=setorderreferencedetails
add_paydata[amazon_address_token]=Atza|verylongalphaNUMMERICcharsetWithSpecialCharacters
add_paydata[amazon_reference_id]=A00-1234567-9876543
add_paydata[storename]=DeutscherStore
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=WX1A1DZ26ET8UXWN

POST Request - genericpayment – add_paydata[action] = confirmorderreference

You have finished all order details and retrieved customer data. You now want to confirm the order to amazon, so that amazon can now check the authentication status of the customer. To do this, you send a genericpayment-request with action "confirmorderdetails" to us with a success- and a error-url, where the customer can be redirected to after the sca-challenge has been done.

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: AMZ

AMZ: 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)

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.
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"
add_paydata Parameters
add_paydata[action]
required
AN..255

Set to "confirmorderreference"
add_paydata[amazon_reference_id]
required
Format CHAR(1..81)

This token is available after the buyer has successfully authenticated using Login with Amazon and is returned by Amazon Pay button’s auth function. This process is not part of the API integration but a result of the widget implementation within the respective shop system or custom implementation. Complete buyer information will only be returned after you have specified a valid AddressConsentToken in the GetOrderReferenceDetails operation. Until then, only the City, PostalCode, and CountryCode elements are returned.
add_paydata[reference]
required
Format CHAR(1..81)

Merchant specified identifier for this order. Is shown in emails to the buyer and buyers transaction history on amazon website. This value needs to be the same as in parameter „reference“ in pre-/authorization
Response Parameters
Permitted Values
OK
ERROR
Response Data (OK)
add_paydata[workorderid]=WX1A1DZ26ET8UXWN/workorderid
Format AN(1..16)

The ID is unique. The returned workorderid is mandatory for the following requests of Amazon Express Checkout.

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 (error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
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                    

request=genericpayment
aid=54400
mid=54399
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
clearingtype=wlt
wallettype=AMZ
mode=test
amount=12000
currency=EUR
successurl=https://yourdomain.de/amazonpay/returned/
errorurl=https://yourdomain.de/amazonpay/cancel?error=1/
workorderid=WX1A1DZ26ET8UXWN
add_paydata[action]=confirmorderreference
add_paydata[amazon_reference_id]=A00-1234567-9876543
add_paydata[reference]=1224900480
RESPONSE

status=OK
add_paydata[workorderid]=WX1A8DZ26B1DDU4H
workorderid=WX1A8DZ26B1DDU4H
POST Request - genericpayment – add_paydata[action] = cancelorderreference

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: AMZ

AMZ: 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)

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.
add_paydata Parameters
add_paydata[action]
required
AN..255
<p">Set to "cancelorderreference"
add_paydata[amazon_reference_id]
required
Format CHAR(1..81)

This token is available after the buyer has successfully authenticated using Login with Amazon and is returned by Amazon Pay button’s auth function. This process is not part of the API integration but a result of the widget implementation within the respective shop system or custom implementation. Complete buyer information will only be returned after you have specified a valid AddressConsentToken in the GetOrderReferenceDetails operation. Until then, only the City, PostalCode, and CountryCode elements are returned.
Response Parameters
Permitted Values
OK
ERROR
Response Data (OK)
add_paydata[workorderid]=WX1A1DZ26ET8UXWN/workorderid
Format AN(1..16)

The ID is unique. The returned workorderid is mandatory for the following requests of Amazon Express Checkout.

 

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 (error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
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                    

request=genericpayment
aid=54400
mid=54399
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
clearingtype=wlt
wallettype=AMZ
mode=test
amount=12000
currency=EUR
workorderid=WX1A1DZ26ET8UXWN
add_paydata[action]=cancelorderreference
add_paydata[amazon_reference_id]=A00-1234567-9876543
RESPONSE

status=OK
add_paydata[workorderid]=WX1A1DZ26ET8UXWN
workorderid=WX1A1DZ26ET8UXWN
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
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.
clearingtype
required
Fixed Value: wtl
mode
required
Fixed Value: test/live

can be either test environment (test) or live environment (live)
reference
required
Format CHAR(2..255)

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

EUR

USD

GBP
param
optional
Format CHAR(1..255)

Individual parameter (per payment process)
narrative_text
optional
Format CHAR(1..81)

Dynamic text element on account statements (3 lines with 27 characters each) and credit card statements.
customer_is_present
optional
Format: LIST
Permitted Values: yes / nop

Indicates whether customer is “present” and can enter their data in the shop (=yes). Or customer is not present and can not enter any data (=no).
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)

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
required (in CN)
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 4217 (currencies) 3-letter-codes
Samples

EUR

USD

GBP

Specifies country of address for the customer.

Some countries require additional information in parameter "state"
shipping_state
required (in CN)
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.
Wallet PARAMETERS
wallettype
required
Fixed Value ALP
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"
Article Parameters
it[n]
optional
Format LIST
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
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 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
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform
userid
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE
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=54400
mid=54399
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
clearingtype=wlt
wallettype=AMZ
amount=12000
currency=EUR
mode=test
workorderid=WX1A8DZPHPRRUGM8
param=session-1|emenpn8np1qnf4g9jdn19at29q|8f201fd35033c79b769d6aad65d4c448
customer_is_present=yes
ip=172.19.0.9
language=de
email=test@payone.com
successurl=https://yourdomain.de/amazonpay/returned/
errorurl=https://yourdomain.de/amazonpay/cancel?error=1/
backurl=https://yourdomain.de/amazonpay/cancel/
company=Fiktive Firma
salutation=Herr
gender=m
firstname=Erika
lastname=Mustermann
street=Marcel-Breuer-Straße 12
zip=80807
city=München
country=DE
telephonenumber=+491731112222
shipping_city=München
shipping_company=
shipping_country=DE
shipping_firstname=Max
shipping_lastname=Mustermann
shipping_street=Schützstraße 123
shipping_zip=80939
de[1]=Hauptartikel mit Kennzeichnung Versandkostenfrei und Hervorhebung
de[2]=Hauptartikel mit Grundpreisberechnung
de[3]=Express Versand
id[1]=SW10006
id[2]=SW10010
id[3]=ship14
ip=172.19.0.9
it[1]=goods
it[2]=goods
it[3]=shipment
no[1]=3
no[2]=15
no[3]=1
pr[1]=1500
pr[2]=500
pr[3]=0
va[1]=1900
va[2]=1900
va[3]=0
RESPONSE
                        
status=APPROVED
add_paydata[shipping_street]=Schützstraße 123
add_paydata[shipping_city]=München
add_paydata[expiration_timestamp]=2023-12-03T07:41:22.715Z
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]=WX1A8DZPHPRRUGM8
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
txid=934964467
userid=616333616
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
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 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)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
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=54400
amount=10000
capturemode=notcompleted
currency=EUR
key=17031f73e2c6f9755788bddfff04169b
mid=54399
mode=test
portalid=2039743
request=capture
txid=935013857
workorderid=WX1A5DZP2NU60L8K
Payload (2nd capture)

add_paydata[amazon_reference_id]=A00-1234567-9876543
aid=54400
amount=2000
capturemode=completed
currency=EUR
key=17031f73e2c6f9755788bddfff04169b
mid=54399
mode=test
portalid=2039743
request=capture
sequencenumber=2
txid=935013857
workorderid=WX1A5DZP2NU60L8K
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
Format LIST
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
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)
Array elements [n] starting with [1]; serially numbered; max [400]

VAT rate (% or bp)
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=54399
aid=54400
portalid=2039743
key=17031f73e2c6f9755788bddfff04169b
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

Additional Information

- 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

Sale

Configuration in seller central (amazon backend)

For asynchronous notification to work properly, please take care that the following notify-URL is configured in your seller central (amazon merchant account) as “integrator-url”.

Notify-URL: https://gpc-sys.pay1.de/gpc/amazon/1.0/notify

You can find the integrator-url in your seller central, by logging in, click on „integration“ at the top of the website. Then click an „MWS Access Key“. There is a link to „IPN Settings“ in the bottom left.

Please see screenshots for detailed information:

 

Acquire full address data

There are two ways to acquire address data. While following the integration by using the provided requests shown in chapter 1.9 and 1.10, you will receive complete address data as part of the successful authorization response. Until then, you’ll only receive city, state, postalcode and countrycode. If you need the full address data before committing the order (authorization/capture) you need to send the amazon_address_token in the getorderreferencedetails or setorderreferencedetails request. The response will deliver all address data available at amazon.

Simulation

There are two ways to simulate errorhandling.

By payment method:

You can choose a specific payment method in wallet widget to simulate a distinct error. With this choice you will enforce the error handling for this request and every following request regarding this transaction. So you won’t have a chance to escape this errorhandling cycle.

By test-string:

You can send a test-string in a specific parameter to simulate errorhandling just for this particular request. Following requests for this transaction will not be affected by this simulation if you do not send the string again. You need to send the test-string as value for the parameter add_paydata[simulation_string].

Common errors

There are two common errors that can be handled in a special way, to try to complete the transaction successfully afterwards.

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 transaction with a set add_paydata[amazon_timeout] 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.

Please use the following test-string to simulate the first decline with errorcode 980:

{"SandboxSimulation": {"State":"Declined", "ReasonCode":"TransactionTimedOut"}}

Errorcode 981

This code points to a declined transaction at amazon, because the paymentmethod the customer has chosen in the widget, is not authorized by amazon. You need to save the transaction data (especially workorderid and amazonOrderReferenceID) and prompt the widgets to the customer again, so he can choose another paymentmethod. While displaying the widgets, you need to set the address-widget to read-only mode by setting „displayMode: 'Read'“. Please note that you may need to delete orderReferenceCreate and onReady function to ensure, that no new amazonOrderReferenceID is crated. This might even be an issue, if these functions are not actively used.

Afterwards send the request with the saved workorderid again to complete the checkout. Please ensure that you use the test-string method to simulate the described error. Otherwise further requests following the declined request will be declined too.

Please use the following test-string to simulate the first decline with errorcode 981:

{"SandboxSimulation": {"State":"Declined","ReasonCode":"InvalidPaymentMethod"}}

In asynchronous mode (send add_paydata[amazon_timeout]) you can get the InvalidPaymentMethodError too. But in asynchronous mode you’ll get a PENDING status in our response and the errorcode 981 in transaction status send to you. In this case, you can now send an email (see mail template) to your customer that he/she needs to update his/her payment details in the amazon account for this order. After updating this details, amazon will send a notify to our payment platform. We will send you a new transaction status with the final status change for this transaction.

Errorcode 985

Show the wallet-widget to the customer, to let him choose another payment method.

Errorcode 986

Show the wallet-widget to the customer, to let him choose a payment method.

Errorcode 987

Show the address-widget to the customer, to let him choose a shippingaddress.