Notes to type of payment
Countries (merchant residence) | Currency |
|---|---|
|
|
B2B transactions are not supported.
API-Requests - special notes / deviations
Overview of deviations
- It's always recommended to use the most recent API-version
-> minimal API-version isapi_version=3.10 - Status "PENDING" has to be processed
- for API-response "PENDING"
- for TransactionStatus "pending"
- Please note the additional information for use of Amazon Pay via Payone at the bottom of this page → additional information
Clearingtype / Clearingsubtype
clearingtype | wlt | Amazon Pay is handled as a wallet payment |
| wallettype | AMZ | Amazon Pay |
Summary
Amazon heavily relies on frontend widgets to let the customer select address and payment options.
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.
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.
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.
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.
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:
- You now need to send a getorderreferencedetails request to payone api, to get full address-data-
- 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
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).
Genericpayment getconfiguration
Request "generic getconfiguraton" | |||
API parameter | Required | Format | Comments |
|---|---|---|---|
| clearingtype | + | Default | wlt - e-wallet |
| wallettype | + | Default | AMZ: Amazon Pay |
| add_paydata[action] | + | N..24 | Fixed value "getconfiguration" |
Response "genericpayment - getconfiguration" | |||
API parameter | Required | Format | Comments |
|---|---|---|---|
add_paydata[client_id] | + | AN..255 | Client ID for Amazon. Find the ID in Amazon Seller Central. Amazon button needs this id too. |
| add_paydata[seller_id] | + | AN..255 | Seller 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 | Format | ||
| errorcode | + | In case of error the PAYONE Platform returns an error code for your internal usage. Format | |
| errormessage | + | In case of error the PAYONE Platform returns an error message for your internal usage. Format | |
| customermessage | + | 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") Format | |
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
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
Genericpayment getorderreferencedetails
To obtain customer data, you need to send a genericpayment-request with action=getorderreferencedetails.
Request "genericpayment - getorderreferencedetails" | |||||||||||||
| API parameter | Required | Format | Comments | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| clearingtype | + | Default | Format LIST
| ||||||||||
| wallettype | + | Default | Format LIST
| ||||||||||
| workorderid | + | AN..16 | Reference ID to the generic request. Has to be passed on to the following "genericrequests". Format | ||||||||||
| add_paydata[action] | + | N..24 | Fixed 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 parameter | Required | Format | Comments | ||
status | + | Default | REDIRECT / ERROR | ||
+ | AN..16 | Reference ID to the generic Request. Has to be passed on to the following “genericrequests” 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. Format CHAR(1..50) | |||
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". | ||
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 | ||
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
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
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 | ||||||||||
+ | Default | Format LIST
| |||||||||||
+ | Default | Format LIST
| |||||||||||
+ | AN..16 | Reference ID to the generic Request. Has to be passed on to the following “genericrequests”. Is obtained by getconfiguration request 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. Format CHAR(1..50) | |||||||||||
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”. | ||||||||||
+ | N..7 | Total amount (in smallest currency unit! e.g. cent) 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. Format NUMERIC(1..10) Permitted values max. +/- 19 999 999 99 | |||||||||||
+ | Default | Currency (ISO 4217) Specifies currency for this transaction Format LIST Permitted values ISO 4217 (currencies) 3-letter-codes Samples EUR USD GBP | |||||||||||
Response "genericpayment - SetOrderReferenceDetails” | |||||
| Parameter | Required | Format | Comment | ||
status | + | Default | REDIRECT / ERROR | ||
+ | AN..16 | Reference ID to the generic Request. Has to be passed on to the following “genericrequests” Format | |||
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". | ||
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 | ||
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
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
Genericpayment confirmorderreference
Request "genericpayment - confirmorderreference” | |||||||||||||
Parameter | Required | Format | Comment | ||||||||||
+ | Default | Format LIST
| |||||||||||
+ | Default | Format LIST
| |||||||||||
+ | AN..16 | Reference ID to the generic Request. Has to be passed on to the following “genericrequests” Format | |||||||||||
+ | N..7 | Total amount (in smallest currency unit! e.g. cent) 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. Format NUMERIC(1..10) Permitted values max. +/- 19 999 999 99 | |||||||||||
+ | 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 | ||||||||||
+ | AN..255 | URL "payment successful" URL for "payment successful" Format Scheme | |||||||||||
+ | AN..255 | URL "faulty payment " URL for "faulty payment" Format Scheme | |||||||||||
Response "genericpayment - confirmorderreference” | |||||
| Parameter | Required | Format | Comment | ||
status | + | Default | OK/ERROR | ||
+ | AN..16 | Reference ID to the generic Request. Has to be passed on to the following “genericrequests” Format | |||
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
status=OK workorderid=WORKORDERID12345
Genericpayment cancelorderreference
Request "genericpayment - cancelorderreference” | ||
Parameter | Required | Comment |
+ | Reference ID to the generic Request. Has to be passed on to the following “genericrequests” Format | |
add_paydata[action] | + | Fixed Value cancelorderreference |
add_paydata[amazon_reference_id] | - | The Amazon order reference ID, that is returned by the widgets in the shop implementation Format AN..30 |
Response "genericpayment - cancelorderreference” | |||||
| Parameter | Required | Format | Comment | ||
status | + | Default | OK/ERROR | ||
+ | AN..16 | Reference ID to the generic Request. Has to be passed on to the following “genericrequests” Format | |||
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
status=OK workorderid=WORKORDERID12345
Preauthorization/Authorization
Request "preauthorization/authorization" | |||||||||||||
Parameter | Required | Format | Comment | ||||||||||
+ | Default | Format LIST
| |||||||||||
+ | Default | Format LIST
| |||||||||||
+ | N..7 | Total amount (in smallest currency unit! e.g. cent) 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. Format NUMERIC(1..10) Permitted values max. +/- 19 999 999 99 | |||||||||||
+ | AN..16 | Reference ID to the generic Request. Has to be passed on to the following “genericrequests” Format | |||||||||||
+ | 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. Format | |||||||||||
+ | Default | Currency (ISO 4217) Specifies currency for this transaction Format LIST Permitted values ISO 4217 (currencies) 3-letter-codes Samples EUR USD GBP | |||||||||||
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. | ||||||||||
- | AN..16 | The description to be shown on the buyer’s payment instrument Dynamic text element on account statements Format (3 lines with 27 characters each) and credit card statements. | |||||||||||
add_paydata[mail_text] | - | AN..1024 | Description displayed in emails to the buyer | ||||||||||
Response "preauthorization/authorization“ | |||||
| Parameter | Required | Format | Comment | ||
status | + | Default | APPROVED / PENDING / ERROR | ||
+ | N..12 | Payment process ID (PAYONE) Mandatory on success Format | |||
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". | ||
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 | ||
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
status=APPROVED txid=12345678 userid=789654
Capture
Request "capture" | |||
Parameter | Required | Format | Comment |
+ | AN..255 | Payment process ID Format | |
+ | N..7 | Total amount (in smallest currency unit! e.g. cent) 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. Format NUMERIC(1..10) Permitted values max. +/- 19 999 999 99 | |
+ | Default | Currency (ISO 4217) Specifies currency for this transaction Format LIST Permitted values ISO 4217 (currencies) 3-letter-codes Samples EUR USD GBP | |
- | AN..16 | The description to be shown on the buyer’s payment instrument Dynamic text element on account statements Format (3 lines with 27 characters each) and credit card statements. | |
add_paydata[mail_text] | - | AN..1024 | Description displayed in emails to the buyer |
Response "capture" | |||
Parameter | Required | Format | Comment |
status | + | Default | APPROVED / PENDING / ERROR |
+ | N..12 | Payment process ID (PAYONE) Mandatory on success Format | |
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 |
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
status=APPROVED txid=134567890123 settleaccount=yes
Debit / Refund
Request "Debit" | |||
Parameter | Required | Format | Comment |
+ | AN..255 | Payment process ID Format | |
+ | 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. 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. Format NUMERIC(1..10) Permitted values max. +/- 19 999 999 99 | |
- | AN..16 | The description to be shown on the buyer’s payment instrument Dynamic text element on account statements Format (3 lines with 27 characters each) and credit card statements. | |
add_paydata[mail_text] | - | AN..1024 | Description displayed in emails to the buyer |
Response "Debit" | |||
Parameter | Required | Format | Comment |
status | + | Default | APPROVED / PENDING / ERROR |
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
status=APPROVED txid=134567890123 settleaccount=yes
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.