Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Notes to type of payment

Countries (merchant residence)

Currency

  • Germany
  • France
  • Italy
  • Spain
  • Luxembourg
  • Netherlands
  • Sweden
  • Portugal
  • Hungary
  • Denmark
  • Euro


UI Text Box
typenote

B2B transactions are not supported.

API-Requests - special notes / deviations

Overview of deviations

UI Text Box
typeinfo
  • It's always recommended to use the most recent API-version
    -> minimal API-version is api_version=3.10
  • Status "PENDING" has to be processed
    • for API-response "PENDING"
    • for TransactionStatus "pending"
    -> Please setup notify-version in PMI -> Configuration -> Payment Portals -> General -> Notify-Version at least to "Version 7.5"
  • Please note the additional information for use of Amazon Pay via Payone at the bottom of this page → additional information

Clearingtype / Clearingsubtype

clearingtype

wltAmazon Pay is handled as a wallet payment
wallettypeAMZAmazon Pay

Summary

Amazon heavily relies on frontend widgets to let the customer select address and payment options.


UI Steps


UI Step

Show Amazon button

In the first step you need to show the Amazon Pay button to the customer. Amazon Pay is an express checkout payment method, that lets the customer skip the address input in the shop. The merchant will retrieve customer data from Amazon Pay. This will make the checkout flow more convinient for your customer and will optimize your conversion rate.


UI Step

Show widget and retrieve customer data

With the retrieved configuration, you can now show the button. By clicking on it, you need to display the Amazon Widgets. One for address selection, one for payment method options.

The customer needs to accept his selected options to proceed the checkout (you need to display a "next" button). After selection you want to retrieve customer data from Amazon Pay. Therefore, you can now send a genericpayment-request with action "getorderreferencedetail" to retrieve customer data. If you want to change the order afterwards, for example to change the amount because of delivery fees, you can send an optional genericpayment-requests with action "setorderreferencedetails". Both steps should be done in the background, not visible for the customer.


UI Step

Confirm order (new with PSD2)

The next step is new and with PSD2 becoming mandatory. 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.


UI Step

Pre-/Authorization

To finish the order, you now need to initiate the confirmation of the order. The customer will be redirected to your shop and you can authorize the payment via PAYONE.



draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayNameAmazon Pay sequence diagram
lboxtrue
revision22
diagramNameklarna_checkout
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

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:

UI Text Box
typeinfo
  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.

UI Text Box
typeinfo

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


UI Text Box
typenote

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


Anchor
getconfiguration
getconfiguration
Genericpayment getconfiguration

Request "generic getconfiguraton"

API parameter

RequiredFormatComments
clearingtype+Defaultwlt - e-wallet
wallettype+DefaultAMZ: Amazon Pay
add_paydata[action]+N..24

Fixed value "getconfiguration"


Response "genericpayment - getconfiguration"

API parameter

RequiredFormatComments

add_paydata[client_id]

+AN..255Client ID for Amazon. Find the ID in Amazon Seller Central. Amazon button needs this id too.
add_paydata[seller_id]+AN..255Seller ID for Amazon. Find the ID in Amazon Seller Central. Amazon button needs this id too.
status+

OK


workorderid+AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

ERROR

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

errorcode+

Excerpt Include
errorcode - definition
errorcode - definition
nopaneltrue

errormessage+

Excerpt Include
errormessage - definition
errormessage - definition
nopaneltrue

customermessage+

Excerpt Include
customermessage - definition
customermessage - definition
nopaneltrue


Code Block
titlegetconfiguration example request
add_paydata[action]=getconfiguration
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
mode=test (set to „live“ for live-requests)
request=genericpayment
wallettype=AMZ


Code Block
titlegetconfiguration example response
add_paydata[action]=getconfiguration
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
mode=test (set to „live“ for live-requests)
request=genericpayment
wallettype=AMZ

Anchor
getorderreferencedetails
getorderreferencedetails
Genericpayment getorderreferencedetails

To obtain customer data, you need to send a genericpayment-request with action=getorderreferencedetails.


true

Request "genericpayment - getorderreferencedetails"

API parameterRequiredFormatComments
clearingtype+Default


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



valueCommetCommentDescription/ Comments
wlte-walletnot allowed for vauthorization, createaccess, updateaccess


wallettype+Default

AMZ: Amazon Pay

Excerpt Include
wallettype - definitionwallettype - definitionnopanel


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



valueCommentServer-APIClient-APIChannel-Frontend
AMZAmazon Payments(tick)(tick)(minus)


workorderid+AN..16

Reference ID to the generic request. Has to be passed on to the following "genericrequests".

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

add_paydata[action]+N..24Fixed value "getorderreferencedetails"
add_paydata[amazon_reference_id]+AN..30

The Amazon order reference ID, that is returned by the widgets in the shop implementation.

add_paydata[amazon_address_token]-AN..700

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 "genericpayment - GetOrderReferenceDetails”      

API parameterRequiredFormatComments

status

+

Default

REDIRECT / ERROR

workorderid

+

AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

add_paydata[email]

-

AN..255

Mail of the buyer

add_paydata[storename]

-

AN.255

Identifier of the store. Sending this parameter overrides the default value in amazon seller central under “Settings -> Account Settings”.

add_paydata[expiration_timestamp]

-

AN..255

Timestamp (ISO 8601) indicating when authorization expires and capture is not possible anymore.

add_paydata[shipping_type]

-

AN..255

Type of destination.

add_paydata[shipping_name]

-

AN..255

First and Lastname of customer

add_paydata[shipping_firstname]

-

AN..255

Firstname of customer

add_paydata[shipping_lastname]

-

AN..255

Lastname of customer

add_paydata[shipping_city]

-

AN..255

City

add_paydata[shipping_zip]

-

AN..20

Postalcode

add_paydata[shipping_street]

-

AN..255

Streetname

add_paydata[shipping_pobox]

-

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


Expand
titleExample


Code Block
titleCustomer selected postbox as destination
add_paydata[pobox]=2458736
add_paydata[shipping_street]=Postbox 12

With this values, you can now fill the delivery informationon your address label. Take "Postbox 12" for your street value and "2458736" for the addressaddition value. We separated this information from our addressaddition parameter to make sure, you can identify when a customer selected a postbox as the delivery address.


add_paydata[shipping_company]

-

AN..255

Companyname

add_paydata[shipping_county]

-

AN..255

County

add_paydata[shipping_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[shipping_district]

-

AN..255

District

add_paydata[shipping_telephonenumber]

-

AN..50

Phone number

add_paydata[shipping_state]

-

AN..255

State or Region

add_paydata[billing_type]

-

AN..255

Type of destination.

add_paydata[billing_name]

-

AN..255

First and Lastname of customer

add_paydata[billing_firstname]

-

AN..255

Firstname of customer

add_paydata[billing_lastname]

-

AN..255

Lastname of customer

add_paydata[billing_city]

-

AN..255

City

add_paydata[billing_zip]

-

AN..20

Postalcode

add_paydata[billing_street]

-

AN..255

Streetname

add_paydata[billing_pobox]

-

AN..255

Postbox

add_paydata[billing_company]

-

AN..255

Companyname

add_paydata[billing_county]

-

AN..255

County

add_paydata[billing_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[billing_district]

-

AN..255

District

add_paydata[billing_telephonenumber]

-

AN..50

Phone number

add_paydata[billing_state]

-

AN..255

State or Region


Code Block
titlegetorderreferencedetails example request
add_paydata[action]=getorderreferencedetails 
add_paydata[amazon_address_token]=aluhdqudw|1323iin32 (obtained by widgets)
add_paydata[amazon_reference_id]=S00-12346-789012 (obtained by widgets) 
add_paydata[storename]=Your Storename 
aid=12345 (your aid) 
mid=23456 (your mid) 
portalid=12345123 (your portalid) 
key=abcdefghijklmn123456789 (your key) 
amount=6413 
api_version=3.10 
clearingtype=wlt 
currency=EUR 
encoding=UTF-8 
mode=test 
request=genericpayment 
wallettype=AMZ 
workorderid= WORKORDERID12345 


Code Block
titlegetorderreferencedetails example response
status=OK
add_paydata[shipping_zip]=80939
add_paydata[shipping_city]=München
add_paydata[shipping_type]=Physical
add_paydata[shipping_country]=DE
add_paydata[shipping_firstname]=Alfred
add_paydata[shipping_lastname]=Amazing
add_paydata[billing_zip]=80939
add_paydata[billing_city]=München
add_paydata[billing_type]=Physical
add_paydata[billing_country]=DE
add_paydata[billing_firstname]=Alfred
add_paydata[billing_lastname]=Amazing
add_paydata[storename]= Your Storename
workorderid= WORKORDERID12345


Anchor
setorderreferencedetails
setorderreferencedetails
Genericpayment 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.

Request "genericpayment - SetOrderReferenceDetails”

Parameter

Required

Format

Comment

clearingtype

+

Default


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



value
Commet
CommentDescription/ Comments
wlte-walletnot allowed for vauthorization, createaccess, updateaccess


wallettype

+

Default

AMZ: Amazon pay

Excerpt Include
wallettype - definitionwallettype - definition
nopaneltrue

workorderid

+

AN


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



valueCommentServer-APIClient-APIChannel-Frontend
AMZAmazon Payments(tick)(tick)(minus)

workorderid

+

AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”. Is obtained by getconfiguration request

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

add_paydata[action]

+

N..24

For “SetOrderReferenceDetails” Requests this has to be:

-          setorderreferencedetails

add_paydata[amazon_reference_id]

+

AN..30

The Amazon order reference ID, that is returned by the widgets in the shop implementation

add_paydata[amazon_address_token]

-

AN..700

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 or after order completion. Until then, only the City,  PostalCode, and CountryCode elements are returned.

add_paydata[platform_id]

o

AN..255

If you are a merchant, do not enter a platform_id. This is only used by solution providers, for whom it is required. It represents the SellerId of the solution provider that developed the eCommerce platform.

add_paydata[storename]

-

AN.255

Identifier of the store. Sending this parameter overrides the default value in amazon seller central under “Settings -> Account Settings”.

amount

+

N..7

Total amount (in smallest currency unit! e.g. cent)

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Default

Currency (ISO 4217)

Excerpt Include
currency - definition
currency - definition
nopaneltrue


Response "genericpayment - SetOrderReferenceDetails” 

ParameterRequiredFormatComment

status

+

Default

REDIRECT / ERROR

workorderid

+

AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

add_paydata[email]

-

AN..255

eMail of the buyer

add_paydata[storename]

-

AN.255

Identifier of the store. Sending this parameter overrides the default value in amazon seller central under “Settings -> Account Settings”.

add_paydata[expiration_timestamp]

-

AN..255

Timestamp (ISO 8601) indicating when authorization expires and capture is not possible anymore.

add_paydata[shipping_type]

-

AN..255

Type of destination.

add_paydata[shipping_name]

-

AN..255

First and Lastname of customer

add_paydata[shipping_firstname]

-

AN..255

Firstname of customer

add_paydata[shipping_lastname]

-

AN..255

Lastname of customer

add_paydata[shipping_city]

-

AN..255

City

add_paydata[shipping_zip]

-

AN..20

Postalcode

add_paydata[shipping_street]

-

AN..255

Streetname

add_paydata[shipping_pobox]

-

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


Expand
titleExample


Code Block
titleCustomer selected postbox as destination
add_paydata[pobox]=2458736
add_paydata[shipping_street]=Postbox 12

With this values, you can now fill the delivery informationon your address label. Take "Postbox 12" for your street value and "2458736" for the addressaddition value. We separated this information from our addressaddition parameter to make sure, you can identify when a customer selected a postbox as the delivery address.


add_paydata[shipping_company]

-

AN..255

Companyname

add_paydata[shipping_county]

-

AN..255

County

add_paydata[shipping_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[shipping_district]

-

AN..255

District

add_paydata[shipping_telephonenumber]

-

AN..50

Phone number

add_paydata[shipping_state]

-

AN..255

State or Region

add_paydata[billing_type]

-

AN..255

Type of destination.

add_paydata[billing_name]

-

AN..255

First and Lastname of customer

add_paydata[billing_firstname]

-

AN..255

Firstname of customer

add_paydata[billing_lastname]

-

AN..255

Lastname of customer

add_paydata[billing_city]

-

AN..255

City

add_paydata[billing_zip]

-

AN..20

Postalcode

add_paydata[billing_street]

-

AN..255

Streetname

add_paydata[billing_pobox]

-

AN..255

Postbox

add_paydata[billing_company]

-

AN..255

Companyname

add_paydata[billing_county]

-

AN..255

County

add_paydata[billing_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[billing_district]

-

AN..255

District

add_paydata[billing_telephonenumber]

-

AN..50

Phone number

add_paydata[billing_state]

-

AN..255

State or Region


Code Block
titlesetorderreferencedetails example request
add_paydata[action]=setorderreferencedetails
add_paydata[amazon_address_token]=aluhdqudw|1323iin32 (obtained by widgets) 
add_paydata[amazon_reference_id]=S00-12346-789012 (obtained by widgets)
add_paydata[storename]=Your Storename
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
amount=6413
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
mode=test
request=genericpayment
wallettype=AMZ
workorderid= WORKORDERID12345


Code Block
titlesetorderreferencedetails example response
add_paydata[action]=setorderreferencedetails
add_paydata[amazon_address_token]=aluhdqudw|1323iin32 (obtained by widgets) 
add_paydata[amazon_reference_id]=S00-12346-789012 (obtained by widgets)
add_paydata[storename]=Your Storename
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
amount=6413
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
mode=test
request=genericpayment
wallettype=AMZ
workorderid= WORKORDERID12345


Anchor
confirmorderreference
confirmorderreference
Genericpayment confirmorderreference

true

Request "genericpayment - confirmorderreference”

Parameter

Required

Format

Comment

clearingtype

+

Default


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



valueCommetCommentDescription/ Comments
wlte-walletnot allowed for vauthorization, createaccess, updateaccess


wallettype

+

Default

AMZ: Amazon pay
Excerpt Include
wallettype - definitionwallettype - definitionnopanel


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



valueCommentServer-APIClient-APIChannel-Frontend
AMZAmazon Payments(tick)(tick)(minus)


workorderid

+

AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

amount

+

N..7

Total amount (in smallest currency unit! e.g. cent)

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Default

Currency (ISO 4217)

add_paydata[action]

+

N..24

For “confirmorderreference” Requests this has to be:

-          confirmorderreference

add_paydata[amazon_reference_id]

+

AN..30

The Amazon order reference ID, that is returned by the widgets in the shop implementation

add_paydata[reference]

+

AN..20

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

successurl

+

AN..255

URL "payment successful"

Excerpt Include
successurl - definition
successurl - definition
nopaneltrue

errorurl

+

AN..255

URL "faulty payment "

Excerpt Include
errorurl - definition
errorurl - definition
nopaneltrue


Response "genericpayment - confirmorderreference”

ParameterRequiredFormatComment

status

+

Default

OK/ERROR

workorderid

+

AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue


Code Block
titleconfirmorderreference example request
add_paydata[action]=confirmorderreference
add_paydata[reference]=reference5678
add_paydata[amazon_reference_id]=referenceid1234
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
amount=6413
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
mode=test
request=genericpayment
successurl=hhtp://www.your-success.url
errorurl=hhtp://www.your-error.url
wallettype=AMZ
workorderid= WORKORDERID12345


Code Block
titleconfirmorderreference example response
status=OK
workorderid=WORKORDERID12345


Anchor
confirmorderreference
confirmorderreference
Genericpayment cancelorderreference

Request "genericpayment - cancelorderreference”

Parameter

Required

Comment

workorderid

+

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

add_paydata[action]

+


Section


Layout box
cssClasspayonePermittedSymbols
floatingleft

Fixed Value


Layout box
cssClasspayonePermittedSymbolsValue
floatingleft
cancelorderreference



add_paydata[amazon_reference_id]

-

The Amazon order reference ID, that is returned by the widgets in the shop implementation

Section


Layout box
cssClasspayonePermittedSymbols
floatingleft

Format


Layout box
cssClasspayonePermittedSymbolsValue
floatingleft
AN..30




Response "genericpayment - cancelorderreference”

ParameterRequiredFormatComment

status

+

Default

OK/ERROR

workorderid

+

AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue


Code Block
titlecancelorderreference example request
add_paydata[action]=cancelorderreference
add_paydata[reference]=reference5678
add_paydata[amazon_reference_id]=referenceid1234
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
clearingtype=wlt
currency=EUR
encoding=UTF-8
mode=test
request=genericpayment
successurl=hhtp://www.your-success.url
errorurl=hhtp://www.your-error.url
wallettype=AMZ
workorderid= WORKORDERID12345


Code Block
titlecancelorderreference example response
status=OK
workorderid=WORKORDERID12345


Anchor
preauth
preauth
Preauthorization/Authorization

true

Request "preauthorization/authorization"

Parameter

Required

Format

Comment

clearingtype

+

Default


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



valueCommetCommentDescription/ Comments
wlte-walletnot allowed for vauthorization, createaccess, updateaccess


wallettype

+

Default

AMZ: Amazon pay
Excerpt Include
wallettype - definitionwallettype - definitionnopanel


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



valueCommentServer-APIClient-APIChannel-Frontend
AMZAmazon Payments(tick)(tick)(minus)


amount

+

N..7

Total amount (in smallest currency unit! e.g. cent)

Excerpt Include
amount - definition
amount - definition
nopaneltrue

workorderid

+

AN..16

Reference ID to the generic Request. Has to be passed on to the following “genericrequests”

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

reference

+

AN..20

Merchant specified identifier for this order. Is shown in emails to the buyer and buyers transaction history on amazon website.

Needs to be the same value as add_paydata[reference] in confirmorderreference-request.

Excerpt Include
reference - definition
reference - definition
nopaneltrue

currency

+

Default

Currency (ISO 4217)

Excerpt Include
currency - definition
currency - definition
nopaneltrue

 

 

 

 

add_paydata[cancel_on_timeout]

-

Default

Send “yes” if you don’t want to try asynchron transaction after a synchronous timeout.

add_paydata[amazon_timeout]

-

AN..5

Default: 1440

Minutes after which an pre- / authorization is automatically declined if processing wasn’t successful in asynchronous mode.

Must be 0 for synchronous mode. Must contain maximum number of minutes for asynchronous mode.

Valid values: Zero or integer values in multiples of five (5, 10, 15, etc.).

If processing in synchronous mode is not successful, you will receive a pending status and an errormessage with errorcode 980. In this case, try to finish the payment with asynchronous mode, e.g. set a timeout in minutes.

add_paydata[amazon_reference_id]

+

AN..255

The Amazon order reference ID, that is returned by the widgets in the shop implementation.

Is alternatively taken from configuration.

add_paydata[amazon_address_token]

-

AN..700

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]

o

AN..255

If you are a merchant, do not enter a platform_id. This is only used by solution providers, for whom it is required. It represents the SellerId of the solution provider that developed the eCommerce platform.

narrative_text

-

AN..16

The description to be shown on the buyer’s payment instrument
statement. Default: “AMZ*<SELLER_NAME> amzn.com/pmts WA”

Excerpt Include
narrative_text - definition
narrative_text - definition
nopaneltrue

add_paydata[mail_text]

-

AN..1024

Description displayed in emails to the buyer


Response "preauthorization/authorization“

ParameterRequiredFormatComment

status

+

Default

APPROVED / PENDING / ERROR

txid

+

N..12

Payment process ID (PAYONE)

Mandatory on success

Excerpt Include
txid - definition
txid - definition
nopaneltrue

add_paydata[email]

-

AN..255

Mail of the buyer

add_paydata[storename]

-

AN.255

Identifier of the store. Sending this parameter overrides the default value in amazon seller central under “Settings -> Account Settings”.

add_paydata[expiration_timestamp]

-

AN..255

Timestamp (ISO 8601) indicating when authorization expires and capture is not possible anymore.

add_paydata[shipping_type]

-

AN..255

Type of destination.

add_paydata[shipping_name]

-

AN..255

First and Lastname of customer

add_paydata[shipping_firstname]

-

AN..255

Firstname of customer

add_paydata[shipping_lastname]

-

AN..255

Lastname of customer

add_paydata[shipping_city]

-

AN..255

City

add_paydata[shipping_zip]

-

AN..20

Postalcode

add_paydata[shipping_street]

-

AN..255

Streetname

add_paydata[shipping_pobox]

-

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


Expand
titleExample


Code Block
titleCustomer selected postbox as destination
add_paydata[pobox]=2458736
add_paydata[shipping_street]=Postbox 12

With this values, you can now fill the delivery information on your address label. Take "Postbox 12" for your street value and "2458736" for the addressaddition value. We separated this information from our addressaddition parameter to make sure, you can identify when a customer selected a postbox as the delivery address.


add_paydata[shipping_company]

-

AN..255

Companyname

add_paydata[shipping_county]

-

AN..255

County

add_paydata[shipping_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[shipping_district]

-

AN..255

District

add_paydata[shipping_telephonenumber]

-

AN..50

Phone number

add_paydata[shipping_state]

-

AN..255

State or Region

add_paydata[billing_type]

-

AN..255

Type of destination.

add_paydata[billing_name]

-

AN..255

First and Lastname of customer

add_paydata[billing_firstname]

-

AN..255

Firstname of customer

add_paydata[billing_lastname]

-

AN..255

Lastname of customer

add_paydata[billing_city]

-

AN..255

City

add_paydata[billing_zip]

-

AN..20

Postalcode

add_paydata[billing_street]

-

AN..255

Streetname

add_paydata[billing_pobox]

-

AN..255

Postbox

add_paydata[billing_company]

-

AN..255

Companyname

add_paydata[billing_county]

-

AN..255

County

add_paydata[billing_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[billing_district]

-

AN..255

District

add_paydata[billing_telephonenumber]

-

AN..50

Phone number

add_paydata[billing_state]

-

AN..255

State or Region



Code Block
titlepre-/authorization example request
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
amount=6413
api_version=3.10
backurl=https://your.shop.com/returnpage.php?status=back
city=Kiel
clearingtype=wlt
company=Amaze Me GmbH
country=DE
currency=EUR
email=alfred@amzing.org
encoding=UTF-8
errorurl=https://your.shop.com/returnpage.php?status=error
firstname=Alfred
lastname=Amazing
mode=test
reference=REFERENCE123
request=authorization (preauthorization, authorization)
salutation=Herr
shipping_city=München
shipping_company=Amaze Me GmbH
shipping_country=DE
shipping_firstname=Alfred
shipping_lastname=Amazing
shipping_street=Fraunhofer 2
shipping_zip=80939
street=streetname
successurl=https://your.shop.com/returnpage.php?status=success
telephonenumber=012345678
wallettype=AMZ
workorderid= WORKORDERID12345
zip=01234


Code Block
titlepre-/authorization example response
status=APPROVED
txid=12345678
userid=789654


Capture

Request "capture"

Parameter

Required

Format

Comment

txid

+

AN..255

Payment process ID

Excerpt Include
txid - definition
txid - definition
nopaneltrue

amount

+

N..7

Total amount (in smallest currency unit! e.g. cent)

Excerpt Include
amount - definition
amount - definition
nopaneltrue

currency

+

Default

Currency (ISO 4217)

Excerpt Include
currency - definition
currency - definition
nopaneltrue

narrative_text

-

AN..16

The description to be shown on the buyer’s payment instrument
statement. Default: “AMZ*<SELLER_NAME> amzn.com/pmts WA”

Excerpt Include
narrative_text - definition
narrative_text - definition
nopaneltrue

add_paydata[mail_text]

-

AN..1024

Description displayed in emails to the buyer


Response "capture"

Parameter

Required

Format

Comment

status

+

Default

APPROVED / PENDING / ERROR

txid

+

N..12

Payment process ID (PAYONE)

Mandatory on success

Excerpt Include
txid - definition
txid - definition
nopaneltrue

add_paydata[shipping_type]

-

AN..255

Type of destination.

add_paydata[shipping_name]

-

AN..255

First and Lastname of customer

add_paydata[shipping_firstname]

-

AN..255

Firstname of customer

add_paydata[shipping_lastname]

-

AN..255

Lastname of customer

add_paydata[shipping_city]

-

AN..255

City

add_paydata[shipping_zip]

-

AN..20

Postalcode

add_paydata[shipping_street]

-

AN..255

Streetname

add_paydata[shipping_pobox]

-

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

Example

Customer selected a postbox as destination:

add_paydata[pobox] = 2458736 (number of the customer using the postbox)

add_paydata[shipping_street] = Postbox 123 (number of the postbox)

add_paydata[shipping_company]

-

AN..255

Companyname

add_paydata[shipping_county]

-

AN..255

County

add_paydata[shipping_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[shipping_district]

-

AN..255

District

add_paydata[shipping_telephonenumber]

-

AN..50

Phone number

add_paydata[shipping_state]

-

AN..255

State or Region

add_paydata[billing_type]

-

AN..255

Type of destination.

add_paydata[billing_name]

-

AN..255

First and Lastname of customer

add_paydata[billing_firstname]

-

AN..255

Firstname of customer

add_paydata[billing_lastname]

-

AN..255

Lastname of customer

add_paydata[billing_city]

-

AN..255

City

add_paydata[billing_zip]

-

AN..20

Postalcode

add_paydata[billing_street]

-

AN..255

Streetname

add_paydata[billing_pobox]

-

AN..255

Postbox

add_paydata[billing_company]

-

AN..255

Companyname

add_paydata[billing_county]

-

AN..255

County

add_paydata[billing_country]

-

AN..2

Country Code (ISO 3166)

add_paydata[billing_district]

-

AN..255

District

add_paydata[billing_telephonenumber]

-

AN..50

Phone number

add_paydata[billing_state]

-

AN..255

State or Region


Code Block
titlecapture example request
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
amount=6413
api_version=3.10
clearingtype=wlt
country=DE
currency=EUR
encoding=UTF-8
mode=test
reference=REFERENCE123
request=capture
txid=134567890123
wallettype=AMZ


Code Block
titlecapture example response
status=APPROVED
txid=134567890123
settleaccount=yes

Debit / Refund

Request "Debit"

Parameter

Required

Format

Comment

txid

+

AN..255

Payment process ID

Excerpt Include
txid - definition
txid - definition
nopaneltrue

amount

+

N..7

Total amount (in smallest currency unit! e.g. cent)

Amount needs to be negative value.

For example, if you want to refund 10 EUR, amount = -1000.

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

Excerpt Include
amount - definition
amount - definition
nopaneltrue

narrative_text

-

AN..16

The description to be shown on the buyer’s payment instrument
statement. Default: “AMZ*<SELLER_NAME> amzn.com/pmts WA”

Excerpt Include
narrative_text - definition
narrative_text - definition
nopaneltrue

add_paydata[mail_text]

-

AN..1024

Description displayed in emails to the buyer


Response "Debit"

Parameter

Required

Format

Comment

status

+

Default

APPROVED / PENDING / ERROR


Code Block
titleDebit example request
aid=12345 (your aid)
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
amount=-5405
api_version=3.10
currency=EUR
encoding=UTF-8
mode=test
request=debit
sequencenumber=-1
txid=134567890123


Code Block
titledebit example response
status=APPROVED
txid=134567890123
settleaccount=yes


Anchor
additionalinfo
additionalinfo
Additional Information

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.


Table of Contents
outlinetrue
indent2em