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 PayPal 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 PayPal 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 PayPal 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 PayPal 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 PayPal 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 PayPal 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 PayPal 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 PayPal Express Checkout.

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

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

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
                no

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

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
required (in CN)
Format LIST

Permitted values ISO 3166-2 States (regions)  2-letter-codes

Samples US Samples CA
AK BC
AB AR
AL
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
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount

required for physical goods in order to ensure PayPal seller protection

id[n]
optional
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]Permitted Symbols [0-9][a-z][A-Z], .,-,_,/

required for physical goods in order to ensure PayPal seller protection

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 Array elements [n] starting with [1]; serially numbered; max [400]Permitted

required for physical goods in order to ensure PayPal seller protection

Unit gross price of the item in smallest unit! e.g. cent

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

required for physical goods in order to ensure PayPal seller protection

Quantity of this item

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

required for physical goods in order to ensure PayPal seller protection

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

Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE

Response Parameter (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.

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=pui-test@payone.de 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

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
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount

required for physical goods in order to ensure PayPal seller protection

id[n]
optional
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]Permitted Symbols [0-9][a-z][A-Z], .,-,_,/

required for physical goods in order to ensure PayPal seller protection

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 Array elements [n] starting with [1]; serially numbered; max [400]Permitted

required for physical goods in order to ensure PayPal seller protection

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 Array elements [n] starting with [1]; serially numbered; max [400]Permitted

required for physical goods in order to ensure PayPal seller protection

Quantity of this item

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

required for physical goods in order to ensure PayPal seller protection

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=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.