1.1 General information about Amazon Pay
1.2 Configuration for Amazon Pay
1.4 Integrate Amazon Pay button widget
2.2 Initializing the Amazon Pay interface
2.3 Amazon Pay capture a payment
2.4 Amazon Pay credit a pament
2.5 Amazon Pay reverse an order
3 Batch processing via the interface
3.3 Integrate Amazon Pay button
Amazon Pay provides buyers with a secure, trusted, and convenient way to sign in and pay for their purchases on your site by using their Amazon credentials. See browser support for information about the operating systems, browsers and browser versions that Amazon Pay supports.
This guide provides an overview of the buyer experience and shows you how to integrate with the latest checkout technology from Amazon Pay.
Further information you will find also on the:
Logo
| Info | Type |
| “Amazon Pay and Login by Amazon” is a complete checkout and payment service. It allows millions of Amazon customers to complete their purchases with using their Amazon account without leaving the web page of the visited online shop. The A-Z-guarantee from Amazon gives a comprehensive protection. | Payments by eWallet |
There are two options that can be used depending if you are a new or an existing customer.
Already existing customers need to login to their accounts and create a new set of API keys to be used with Amazon Pay Checkout version.2.
We already have the needed data for your accounts done for the original checkout v.1.
Please see below the “Guide to create API keys”.
Before using Amazon Pay you need to register at https://pay.amazon.de/signup
An alternative is also the signup for Amazon based on country, the steps are the;
When logged in in the Amazon seller central, you should have 2 accounts, that you can toggle between:
The needed data for the onboarding are the following:
| Amazon Cv.2 | Anmerkung |
| *Country Code* | Code of the Amazon market used (DE=EU, UK, JP and US) |
| MerchantID | taken from Amazon seller central |
| MWS Autorization Token | Example: amzn.mws.a4a8d852-3d9e-f441-0674-d042baa3cf6452 |
| Merchant Store Name | Name of the store |
| StoreID | Example: amzn1.application-oa2-client.7150fff45acf49f8acd519fa485142a2 |
Please follow the guide below to create the API keys necessary.
Important: If you don´t see the option to create the API keys, you need to create a store first and then create the API keys.
Under the “Integration central” at the bottom you can do this using the link found there:
One of the important piece of data needed is the MWS Authorization token from Amazon which gives the 1cs Online Payment System permission to conduct transactions for your shop.
The second step is generating a MWS Auth Token. This is the data needed:
When logged in to the seller central of Amazon, go to the top right-hand side of the page and click on Settings and choose “User Permissions”:
This leads you to the “User permissions” page which show you the current users, here you can add an external developer to your account, here please click on “Visit manage your apps”:
This leads you to a new page were you can see developers that have access, here you can add, delete and renew permissions. Please click on “Authorise new developer”:
On the new page you need to add the developer name and ID given above. Fill in the information and click on “Next”:
The last page is were you need to agree to the terms and conditions of granting a developer access to the account.
When clicking on “Next”, you are shown a success page with information:
With the last click on “Next”, you are led back to the original “User Permission” were the developer is now shown:
Here you can now click on “View” and access the “MWS Authorization token” and can also copy it.
Then submit the received MWS Authorisation Token on a secure way to 1cs OPS Helpdesk for configuration.
In order to create new API keys, choose one of your accounts, either Production or Sandbox on top of the page, process needs to be done for both accounts. Amazon description is found here.
Please click left-hand side on the symbol with the 3 horizontal lines.
On the menu that appears, please go to “Integration” and choose “Integration central”.
On the Integration central, go to the section “Create API Keys” and click on the button there.
A Pop-up window appears where you need to choose “Generate API Credentials”, here you also need to give the keys a unique name:
The newly created keys are immediately visible on the “Integration central”. There you choose the option to “See Details”:
When looking at the details, you can see the data or download the data in JSON format:
JSON example:
“merchant_id”: ” “,
“public_key_id”: ” “,
“store_id”: ” “,
Important:
Customers will need to also to store/configure the following 1cs OPS notify URL.
URL: https://www.computop-paygate.com/amazonpaycomplete.aspx
Go to the menu on the te top left-hand side:
On the menu that appears, please go to “Integration” and choose “MWD Access Key”:
At the bottom of the page you can see the option for IPN (Instant Payment notification):
After clicking on the blue link another pages open with integration settings:
Here please click on the “Edit”-button:
1. Here please add the fowllowing URL to the integrator URL and click on the “Update”-button
2. The merchant can also save his own notify URL if he so wishes. The 1cs Online Payment System will ask for the NotifyURL on the request as well.
Important: Please make sure to use the Notifies sent via server to server and not only rely on the SuccessURLs/FailureURLs.
The basic payment process with Amazon consists of several steps:
| Step | Description |
| Display Amazon Pay button | The Amazon Pay button widget must be properly implemented on the page of the webshop and must be called for each payment process. You can find below the example code snippet. |
| Initialize payment via amazonAPA.aspx (Server to Server) | You will call the 1cs OPS endpoint https://www.computop-paygate.com/amazonapa.aspx according to description below. The 1cs Online Payment System will respond with parameters that you must use to update the Amazon Pay button. |
| Redirect to Amazon | After updating the Amazon Pay button, customer will be redirected to Amazon. |
| Redirect back to your webshop | After confirming customer’s preferred payment instrument, and optionally shipping address on the Amazon Pay-hosted page, customer is redirected back to your webshop order review page. |
| Finalize the purchase | After customer confirms the order, you will redirect the client to Amazon URL received in response from the 1cs Online Payment System. |
| Redirect back to your webshop | After customer finalizes the payment at Amazon side, customer will be redirected back to your defined URL based on result of payment (URLSuccess / URLFailure). |
| Notify from the 1cs Online Payment System is sent via S2S | Please make sure to setup and use the notifyURL to get final confirmation on the requests success/failure |
Please make sure that you plan in the 2 main tasks for merchants:
The following example code shows how to integrate the Amazon Pay button in your webshop.
When customer submits this button, you will call the 1cs Online Payment System to obtain additional data, which are required for updating the Amazon Pay button.
var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’,{
merchantId: ‘xxxxx’,
publicKeyId: ‘SANDBOX-xxxxxxxxxx’,
ledgerCurrency: ‘EUR’,
checkoutLanguage: ‘en_GB’,
productType: ‘PayAndShip’,
placement: ‘Cart’,
buttonColor: ‘Gold’
});
amazonPayButton.onClick(function(){
const [payload, signature, publicKeyId] = your_call_to_paygate();
amazonPayButton.initCheckout({
createCheckoutSessionConfig: {
payloadJSON: payload,
signature: signature,
publicKeyId: publicKeyId
}
});
});
In this case the following parameters must be present within the Button:
| Parameter | Description | Value |
| MerchantID | SellerId issued by Amazon | |
| LedgerCurrency | Your ledger currency. For EU/UK accounts a different presentment currency can be used on the auth/capture | Permissible values: US merchants – ‘USD’ EU merchants – ‘EUR’ UK merchants – ‘GBP’ JP merchants – ‘JPY’ |
| Placement | Placement of the button | Permissible values: Cart |
| ButtonColor | The parameter ButtonColor defines the color of the button widget | Permissible values: Gold, LightGray, DarkGray |
| ProductType | The parameter productType defines if the transaction is done for physical or digital goods. PayAndShip is default. | Permissible values: PayAndShip – Physical goods PayOnly – Digital goods |
| CheckoutLanguage | The parameter checkoutLanguage is optionally used for defining the language of the checkout process. This is helpful especially within a multilingual shop environment. Without submitting the parameter Language Amazon automatically uses the most suitable language for checkout. | Permissible values: US merchants – ‘en_US’ EU/UK merchants – ‘en_GB’, de_DE’, ‘fr_FR’, ‘it_IT’, ‘es_ES’ JP merchants – ‘ja_JP’ |
| EstimatedOrderAmount | This is the estimated checkout order amount, it does not have to match the final order amount if the buyer updates their order after starting checkout. Amazon Pay will use this value to assess transaction risk and prevent buyers from selecting payment methods that can’t be used to process the order Use updateButtonInfo() to update the estimatedOrderAmount if the estimated order amount changes; for example, if the buyer removes or adds something to their cart. This function may update the button UI and the new estimatedOrderAmount will be used to determine whether the order meets the installment provider’s minimum order price threshold. Example of the function <script type=”text/javascript” charset=”utf-8″> amazonPayButton.updateButtonInfo({“amount”:”120.99″,”currencyCode”:”USD”}); </script> | Example: { “amount”: “50.99”, “currencyCode”:”USD”} |
Further information can be found in the documentation from Amazon Pay.
When using the complete checkout of Amazon Pay v2, the review page is to be used on the side of the merchant to allow:
A change of either one or both is possible.
This is the 1cs OPS data that is delivered to the merchant for the review page
This is an example on the JSON that merchants can use to accomodate changes if necessary
let session = document.getElementById(‘sessionId’).value;
let link = document.getElementById(‘redirectUrl’).value;
let buyNow = document.getElementById(‘buy-now’);
buyNow.addEventListener(‘click’, () => {
window.location = link;
})
amazon.Pay.bindChangeAction(‘#change-paymethod’, {
amazonCheckoutSessionId: session,
changeAction: ‘changePayment’
});
amazon.Pay.bindChangeAction(‘#change-shipping’, {
amazonCheckoutSessionId: session,
changeAction: ‘changeAddress’
});
The Amazon description can be found here:
Recurring Subsequent
Credit a payment
Reverse an order
| Format | Description |
| a | alphabetical |
| as | alphabetical with special characters |
| n | numeric |
| an | alphanumeric |
| ans | alphanumeric with special characters |
| ns | numeric with special characters |
| bool | boolean expression (true or false) |
| 3 | fixed length with 3 digits/characters |
| ..3 | variable length with maximum 3 digits/characters |
| enum | enumeration of allowed values |
| dttm | ISODateTime (YYYY-MM-DDThh:mm:ss) |
| Abbreviation | Description |
| CND | condition |
| M | mandatory |
| O | optional |
| C | conditional |
Notice: Please note that the names of parameters can be returned in upper or lower case.
In order to initialize a payment with Amazon Pay, please visit the following URL:
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter has to be passed in plain language too. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| RefNr | ans..30 | O | Merchant´s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| CountryCode | an2 | M | Country code of used marketplace. Options EU, US and JP |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent). Please contact the 1cs OPS Helpdesk, if you want to capture amounts <100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: Currency table |
| URLSuccess | ans..256 | M | The buyer is redirected to this URL if action was successful |
| URLFailure | ans..256 | M | The buyer is redirected to this URL if action was unsuccessful |
| URLNotify | ans..256 | M | Complete URL which the 1cs Online Payment System calls up in order to notify the shop about the payment result.It may not contain parameters: Use the UserData parameter instead. Common notes: We recommend to use parameter “response=encrypt” to get an encrypted response by the 1cs OPS However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful. |
| URLCancel | ans..256 | M | The buyer is redirected to this URL if the operation is cancelled |
| ShopURL | ans..256 | M | Order review page where customer is redirected after confirming customer’s preferred payment instrument and optionally shipping address on the Amazon Pay-hosted page |
| TxType | an..20 | C | Payment flow for charging the buyer. Supported values: ‘AuthorizeWithCapture’ – Authorize and capture funds immediately, is default ‘Authorize’ – Authorize funds immediately and capture at a later time |
| LocalCurrency | a3 | C | The currency that the buyer will be charged in ISO 4217 format. Only possible for Amazon EU and UK markets. |
| Scope | a..128 | O | The buyer details that you’re requesting access to. Possible values: “name” “email” “phoneNumber” “billingAddress” If not included, all buyer information is requested. |
| ChDesc | ans..16 | C | Only for sale type transactions: AuthorizeWithCapture. Default: “AMZ*<SELLER_NAME> pay.amazon.com“ |
| OrderDesc | ans..127 | O | Use this parameter for the simulation mode. During live mode this parameter has no effects. |
| Recurring | |||
| RTF | ans1 | O | For repeated payments (subscriptions): I = Initial payment of series of payments. Default is OTP, one time payment. |
| Cycle | an..7 | C | Cycle. Supported values: ‘Year’, ‘Month’, ‘Week’, ‘Day’, ‘Variable’ |
| Value | n..4 | C | Number of frequency units per billing cycle. For example, to specify a weekly cycle set unit to Week and value to 1. You must set value to 0 if you’re using variable unit. year: 1-3 Month: 1-36 Week: 1-57 Day: 1-1095 |
| InstallmentAmount | n..10 | C | Transaction amount – choose zero if is not a fixed amount |
| Currency | a3 | C | Transaction currency code in ISO 4217 format. Example: EUR |
Encrypted parameters for initializing an Amazon Pay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
be prepared to receive additional parameters at any time and do not check the order of parameters
the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture oder credit request |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided byyou which should be qunique for each payment |
| RefNr | ans..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| ButtonSignature | ans..256 | M | Signature for the Amazon Button |
| ButtonPayload | ans..256 | M | Payload for the Amazon Button |
| ButtonPublicKeyID | ans..256 | M | Public Key ID for the Amazon Button |
Response parameters after initializing an Amazon Pay payment
The following example code shows the updated and complete Amazon Pay button, which will redirect the client to Amazon.
<div id=”AmazonPayButton”></div>
<script src=”https://static-na.payments-amazon.com/checkout.js“></script>
<script type=”text/javascript” charset=”utf-8″>
var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’, {
merchantId: ‘xxxxx’,
ledgerCurrency: ‘EUR’,
checkoutLanguage: ‘en_GB’,
productType: ‘PayAndShip’,
placement: ‘Cart’,
buttonColor: ‘Gold’
});
amazonPayButton.onClick(function(){
// Here you need to call your shop server, which creates the initial Call towards the 1cs Online Payment System
// and then returns the required data payloadJSON, signature, publicKeyId from the response
var buttonData = getSignedButtonData()
amazonPayButton.initCheckout({
createCheckoutSessionConfig: {
payloadJSON: buttonData.payloadJSON,
signature: buttonData.signature,
publicKeyId: buttonData.publicKeyId
}
});
</script>
Intermediate response with customer information to your ShopUrl
The following table describes the result parameters with which the 1cs online payment system responds to your system
be prepared to receive additional parameters at any time and do not check the order of parameters
the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture oder credit request |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided byyou which should be qunique for each payment |
| RefNr | ans..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs OPS Response Codes (A4 Error codes) |
| RTF | ans1 | O | Onetime or recurring. For repeated payments (subscriptions): I = Initial payment of series of payments. |
Response parameters after initializing an Amazon Pay payment.
In order to capture an authorized payment with Amazon Pay, please visit the following URL:
The following tables describe the transfer parameters and return values which are exchanged via the socket connection. The server-to-server communication process is described in the manual Programming basics.
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter has to be passed in plain language too. |
| PayID | an32 | M | ID issued by the 1cs Online Payment System for the payment, e.g. for the referencing of cancellations, captures and credits. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, Please find an overview here: Currency table |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| ChDesc | ans..16 | O | Text printed on the customer’s credit card bill alongside the payee |
| OrderDesc | ans..127 | M | Use this parameter for the simulation mode. During live mode this parameter has no effects. |
| ReqID | ans..32 | O | To avoid double payments / actions, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction / action is submitted again with the same ReqID, 1cs OPS will not carry out the payment or new action, but will just return the status of the original transaction / action. Please note that the 1cs OPS must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the 1cs Online Payment System. |
Encrypted parameters for capturing an authorized Amazon Pay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
be prepared to receive additional parameters at any time and do not check the order of parameters
the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | TrancsactionID provided by you which should be unique for each payment |
| TransID | ans..64 | M | Merchant transaction number for capture |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| CodeExt | ans..10 | O | error code from Amazon, if transferred |
| ErrorText | as..1024 | O | Error description from Amazon, if it was transferred |
| ChargeID | ans..256 | M | Amazon Pay Charge ID |
| AmazonStatus | a..20 | M | Order status at Amazon. Following values are possible: „Pending“, „Declined“, „Completed“, „Closed“. Details see Amazon API Reference Guide. |
| ChargePermissionID | ans..256 | M | Amazon Pay Permission ID |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: Currency table |
| AmountAuth | n..10 | M | Total amount which is reserved at Amazon |
| AmountCap | n..10 | M | Total amount which is already successfully captured at Amazon |
| AmountCred | n..10 | M | Total amount which is already successfully credited at Amazon |
Response parameters after capturing an authorized Amazon Pay payment
After a capture you get a notify to your specified URLNotify with following parameters:
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as wekk as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | Merchant´s transaction number |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| CodeExt | ans..10 | O | Error code from Amazon, if transferred |
| ErrorText | ans..1024 | O | Error description from Amazon, if it was transferred |
| ChargeID | ans..256 | M | Amazon Pay Charge ID |
| AmazonStatus | a..20 | M | Order status at Amazon. Following values are possible: „Draft“, „Open“, „Suspended“, „Abandoned“, „Canceled“, „Closed“. Details see Amazon API Reference Guide. |
| ChargePermissionID | ans..256 | M | Amazon Pay Permission ID |
| OrderID | ans..19 | M | Unique ID for the order issued by Amazon. Corresponds to the OrderReferenceID. |
| AmazonRefID | ans..27 | M | Unique ID for the transaction issued by Amazon |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, , e.g. EUR, USD, GBP. Please find an overview here: Currency table |
| AmountAuth | n..10 | M | Total amount which is reserved at Amazon |
| AmountCap | n..10 | M | Total amount which is already sucessfully captured at Amazon |
| AmountCred | n..10 | M | Total amount which is already sucessfully credited at Amazon |
| NotificationType | a..25 | M | Describes the type of notification. Fixed value: <CaptureNotification> |
Response parameters to URLNotify after capturing an authorized Amazon Pay payment.
In order to credit a captured payment with Amazon Pay, please visit the following URL:
The following tables describe the transfer parameters and return values which are exchanged via the socket connection. The server-to-server communication process is described in the manual Programming basics.
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter has to be passed in plain language too. |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, , e.g. EUR, USD, GBP. Please find an overview here: Currency table |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| OrderDesc | ans..127 | M | Description of purchased goods, unit prices etc. for credit |
| ChargeID | ans..256 | M | Amazon Pay Charge ID |
| ReqID | ans..32 | O | To avoid double payments / actions, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction / action is submitted again with the same ReqID, 2cs OPS will not carry out the payment or new action, but will just return the status of the original transaction / action. Please note that the 1cs OPS must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the 1cs Online Payment System. |
Encrypted parameters for crediting an Amazon Pay payment
The following table describes the result parameters with which the 1cs online payment system responds to your system
be prepared to receive additional parameters at any time and do not check the order of parameters
the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch file as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| CodeExt | ans..10 | O | Error code from Amazon, if transferred |
| ErrorText | as..1024 | O | Error description from Amazon, if transferred |
| AmazonStatus | a..20 | M | Order status at Amazon. Following values are possible:„Draft“, „Open“, „Suspended“, „Abandoned“, „Canceled“, „Closed“. Details see Amazon API Reference Guide. |
| ChargeID | ans..256 | M | Amazon Pay Charge ID |
| RefundID | ans..256 | M | Amazon Pay Refund ID |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: Currency table |
| AmountAuth | n..10 | M | Total amount which is reserved at Amazon |
| AmountCap | n..10 | M | Total amount which is already successfully captured at Amazon |
| AmountCred | n..10 | M | Total amount which is already successfully credited at Amazon |
Encrypted parameters for crediting an Amazon Pay payment
After a credit you get a notify to your specified URLNotify with following parameters:
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| RefNr | ns..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| CodeExt | ans..10 | O | error code from Amazon, if transferred |
| ErrorText | as..1024 | O | Error description from Amazon, if transferred |
| AmazonStatus | a..20 | M | Order status at Amazon. Following values are possible: „Draft“, „Open“, „Suspended“, „Abandoned“, „Canceled“, „Closed“. Details see Amazon API Reference Guide. |
| ChargeID | ans..256 | M | Amazon Pay Charge ID |
| RefundID | ans..256 | M | Amazon Pay Redund ID |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent) Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: Currency table |
| AmountAuth | n..10 | M | Total amount which is reserved at Amazon |
| AmountCap | n..10 | M | Total amount which is already sucessfully captured at Amazon |
| AmountCred | n..10 | M | Total amount which is already sucessfully credited at Amazon |
| NotificationType | a..25 | M | Describes the type of notification. Fixed value: <CreditNotification> |
Response parameters to URLNotify after credit of an Amazon Pay payment.
In order to reverse a complete order with Amazon Pay with the function „CancelOrderReference“, please visit the following URL:
The following tables describe the transfer parameters and return values which are exchanged via the socket connection. The server-to-server communication process is described in the manual Programming basics.
Notice: For security reasons, the 1cs Online Payment System rejects all payment requests with formatting errors. Therefore please use the correct data type for each parameter. See separate appendix to the programming manual for cancellation error messages and their causes.
The following table describes the encrypted payment request parameters:
| Parameter | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by First Cash Solution. Additionally, this parameter has to be passed in plain language too. |
| PayID | an32 | M | ID issued by the 1cs Online Payment System for the payment, e.g. for the referencing of cancellations, captures and credits. |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| Reason | a..1024 | O | Reason for reversal |
| ReqiD | ans..32 | O | To avoid double payments / actions, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction / action is submitted again with the same ReqID, 1cs OPS will not carry out the payment or new action, but will just return the status of the original transaction / action. Please note that the 1cs OPS must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly. |
Encrypted parameters for reversal of an Amazon Pay payment
The following table describes the result parameters with which the 1cs Online Payment System responds to your system:
| Parameter | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by First Cash Solution |
| PayID | an32 | M | ID issued by the 1cs Online Payment System for the payment, e.g. for the referencing of cancellations, captures and credits. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | Merchant’s transaction number |
| RefNr | ans..30 | O | Merchant’s unique reference number Only ASCII characters are allowed. Special characters such as (“umlauts”, …) are not permitted and may have to be replaced by ASCII characters (e.g. ü → ue, é → e, …). |
| Status | a..30 | M | OK or FAILED |
| Description | ans..1024 | M | Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis! |
| Code | n8 | M | Error code according to the 1cs Online Payment System Response Codes Excel file |
| OrderID | ans..19 | M | Unique ID for the order issued by Amazon. Corresponds to the OrderReferenceID. |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217 |
| AmountAuth | n..10 | M | Total amount which is reserved at Amazon |
| AmountCap | n..10 | M | Total amount which is already successfully captured at Amazon |
| AmountCred | n..10 | M | Total amount which is already successfully credited at Amazon |
Response parameters after reversing an Amazon Pay payment
The additional payment button (APB) is a slightly different way to use the Amazon Pay Checkout Cv2. This option can be used with OneTime (OTP) or recurring transactions.
The standard setup of account at Amazon is done just like the regular integration.
The key differences to the “normal” integration are:
This implementation differs from the normal checkout in:
Using only the button to trigger a transaction.
Using our HPP in connection with APB
Payload Example
{
“webCheckoutDetails”: {
“checkoutResultReturnUrl”: “https://a.com/merchant-review-page“,
“checkoutMode”: “ProcessOrder”
},
“storeId”: “amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId”,
“scopes”: [“name”, “email”, “phoneNumber”, “billingAddress”],
“paymentDetails”: {
“paymentIntent”: “AuthorizeWithCapture”,
“chargeAmount”: {
“amount”: “10”,
“currencyCode”: “USD”
},
“presentmentCurrency”:”USD”
},
“merchantMetadata”: {
“merchantReferenceId”:”Merchant-order-123″,
“merchantStoreName”:”Merchant Store Name”,
“noteToBuyer”:”Thank you for your order”
},
“addressDetails”: {
“name”: “Paul Smith”,
“addressLine1”: “9999 First Avenue”,
“city”: “New York”,
“stateOrRegion”: “NY”,
“postalCode”: “10016”,
“countryCode”: “US”,
“phoneNumber”: “212555555”
}
}
{
“storeId”: “xxx”,
“webCheckoutDetails”: {
“checkoutResultReturnUrl”: “https://merchant1/xxxxxxxx“,
“checkoutMode”: “ProcessOrder”
},
“paymentDetails”: {
“paymentIntent”: “Confirm”,
“chargeAmount”: {
“amount”: “1”,
“currencyCode”: “JPY”
}
},
//recurring case
“chargePermissionType”: “Recurring”,
“recurringMetadata”: {
“frequency”: {
“unit”: “Month”,
“value”: “1”
},
“amount”: {
“amount”: “10”,
“currencyCode”: “JPY”
}
},
“addressDetails”: {
“addressLine1”: “%E7%9B%AE%E9%BB%92%E5%8C%BA%E4%B8%8B%E7%9B%AE%E9%BB%92”,
“addressLine2”: “%EF%BC%91%EF%BC%8D%EF%BC%94%EF%BC%8D%EF%BC%91”,
“addressLine3”: “%E3%82%A2%E3%83%89%E3%83%AC%E3%82%B9%E3%83%A9%E3%82%A4%E3%83%B3%EF%BC%93”,
“name”: “%E5%90%8D%E5%89%8D%E3%80%80%E3%83%86%E3%82%B9%E3%83%88%EF%BC%91%EF%BC%92%EF%BC%93”,
“countryCode”: “JP”,
“postalCode”: “1560064”,
“phoneNumber”: “0333333333”
}
}
The following example code shows how to integrate the Amazon Pay button in your webshop.
When customer submits this button, you will call the 1cs Online Payment System to obtain additional data, which are required for updating the Amazon Pay button.
<div id=”AmazonPayButton”></div>
<script src=”https://static-na.payments-amazon.com/checkout.js“></script>
<script type=”text/javascript” charset=”utf-8″>
var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’, {
merchantId: ‘xxxxx’,
ledgerCurrency: ‘EUR’,
checkoutLanguage: ‘en_GB’,
productType: ‘PayAndShip’,
placement: ‘Cart’,
buttonColor: ‘Gold’
});
</script>
Button
| Parameter | Description | Value |
| MerchantID | Seller issued by Amazon | |
| LedgerCurrency | Your ledger currency. For EU/UK accounts a different presentment currency can be used on the auth/capture. | Permissible values: US merchants – ‘USD’ EU merchants – ‘EUR’ UK merchants – ‘GBP’ JP merchants – ‘JPY’ |
| Placement | Placement of the button | Permissible values: Cart |
| ButtonColor | The parameter buttonColor defines the color of the button | Permissible values: Gold, LightGray, DarkGray |
| ProductType | The parameter productType defines if the transaction is done for physical or digital goods. PayAndShip is default. | Permissible values: PayAndShip – Physical goods PayOnly – Digital goods |
| CheckoutLanguage | The parameter checkoutLanguage is optionally used for defining the language of the checkout process. This is helpful especially within a multilingual shop environment. Without submitting the parameter Language Amazon automatically uses the most suitable language for checkout. | Permissible values: US merchants – ‘en_US’ EU/UK merchants – ‘en_GB’, de_DE’, ‘fr_FR’, ‘it_IT’, ‘es_ES’ JP merchants – ‘ja_JP’ |
Further information can be found in the documentation from Amazon Pay.
In order to initialize a payment with Amazon Pay, please use the following URL:
Notice: For security reasons, the 1cs OPS rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.
The following table describes the encrypted payment request parameters:
| Key | Format | CND | Description |
| MerchantID | ans..30 | M | MerchantID, assigned by the 1cs Online Payment System. Additionally this parameter has to be passed in plain language too. |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| RefNr | ns..30 | O | Merchant´s unique reference number |
| MAC | an64 | M | Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify) |
| CountryCode | an2 | M | Country code of used marketplace. Options EU, UK, US and JP. |
| Amount | n..10 | M | Amount in the smallest currency unit (e.g. EUR Cent). Please contact the 1cs OPS Helpdesk, if you want to capture amounts <100 (smallest currency unit). |
| Currency | a3 | M | Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: Currency table |
| URLSuccess | ans..256 | M | The buyer is redirected to this URL if the Multi Factor Authentication was successful |
| URLFailure | ans..256 | M | The buyer is redirected to this URL if the Multi Factor Authentication was unsuccessful |
| URLNotify | ans..256 | M | Complete URL which the 1cs Online Payment System calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserData parameter instead. Common notes: We recommend to use parameter “response=encrypt” to get an encrypted response by the 1cs Online Payment System However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the “code”-value which indicates success/failure of the action. Only a result of “code=00000000” should be considered successful. |
| CheckoutMode | an..12 | M | ProcessOrder – can be hardcoded for APB! Buyer will complete checkout on the Amazon Pay hosted page immediately after clicking on the Amazon Pay button. |
| ShopUrl | ans..256 | M | Amazon=checkoutResultReturnUrl |
| TxType | an..20 | C | The 1cs Online Payment System flow for charging the buyer. Supported values: ‘AuthorizeWithCapture’ – Authorize and capture funds immediately, is default ‘Authorize’ – Authorize funds immediately and capture at a later time |
| LocalCurrency | a3 | C | The currency that the buyer will be charged in ISO 4217 format. In case of using multi-currency. Only possible for Amazon EU and UK markets. |
| Scope | a..128 | O | The buyer details that you’re requesting access to. Possible values: “name” “email” “phoneNumber” “billingAddress” If not included, all buyer information is requested. |
| ChDesc | ans..16 | C | Only for sale type transactions: AuthorizeWithCapture. Default: “AMZ*<SELLER_NAME> pay.amazon.com“ |
| OrderDesc | ans..127 | O | Description of purchased goods, unit prices etc. |
| Shipping address – conditioans..depend on the market, see below | |||
| Recurring Metadata | |||
| RTF | ans1 | O | For repeated payments (subscriptions): I = Initial payment of series of payments. Default is OTP, one time payment. |
| Cycle | an..7 | C | Cycle. Supported values: ‘Year’, ‘Month’, ‘Week’, ‘Day’, ‘Variable’ |
| Value | n..4 | C | Number of frequency units per billing cycle. For example, to specify a weekly cycle set unit to Week and value to 1. You must set value to 0 if you’re using variable unit. year: 1-3 Month: 1-36 Week: 1-57 Day: 1-1095 |
| InstallmentAmount | n..10 | C | Transaction amount – choose zero if is not a fixed amount |
| Currency | a3 | C | Transaction currency code in ISO 4217 format. Example: EUR |
Encrypted parameters for initializing an Amazon Pay payment
Intermediate Response with Button additional parameters
The following table describes the result parameters with which the 1cs online payment system responds to your system
be prepared to receive additional parameters at any time and do not check the order of parameters
the parameters (e.g. MerchantId, RefNr) should not be checked case-sentive
| Key | Format | CND | Description |
| MID | ans..30 | M | MerchantID, assigned by the 1cs OPS |
| PayID | an32 | M | ID assigned by the 1cs Online Payment System for the payment, e.g. for referencing in batch files as well as for capture or credit request. |
| XID | an32 | M | ID for all single transactions (authorisation, capture, credit note) for one payment assigned by the 1cs Online Payment System |
| TransID | ans..64 | M | TransactionID provided by you which should be unique for each payment |
| RefNr | ns..30 | O | Merchant’s unique reference number |
| Status | a..50 | M | OK (URLSuccess) or FAILED (URLFailure) |
| ButtonSignature | ans..256 | M | Signature for the Amazon Button |
| ButtonPayload | ans..256 | M | Payload for the Amazon Button |
| ButtonPublicKeyID | ans..256 | M | Public Key ID for the Amazon Button |
Response parameters after initializing an Amazon Pay payment
The following example code shows the updated and complete Amazon Pay button, which will redirect the client to Amazon
<div id=”AmazonPayButton”></div>
<script src=”https://static-na.payments-amazon.com/checkout.js“></script>
<script type=”text/javascript” charset=”utf-8″>
var amazonPayButton = amazon.Pay.renderButton(‘#AmazonPayButton’, {
merchantId: ‘xxxxx’,
ledgerCurrency: ‘EUR’,
checkoutLanguage: ‘en_GB’,
productType: ‘PayAndShip’,
placement: ‘Cart’,
buttonColor: ‘Gold’
});
amazonPayButton.onClick(function(){
// Here you need to call your shop server, which creates the initial Call towards the 1cs Online Payment System
// and then returns the required data payloadJSON, signature, publicKeyId from the response
var buttonData = getSignedButtonData()
amazonPayButton.initCheckout({
createCheckoutSessionConfig: {
payloadJSON: buttonData.payloadJSON,
signature: buttonData.signature,
publicKeyId: buttonData.publicKeyId
}
});
</script>
Since the address is to be send by the merchant for APB and we support different markets, this is what will be validated.
EU (including UK)
| Parameter | Format | CND | Beschreibung |
| Name | as..50 | M | First name and surname of address |
| SdStreet | a..180 | M | Company name (if given) or street name and street number |
| SdStreet2 | a..60 | O | Street name and house number |
| SdAddressAddition | a..60 | O | Other Additions |
| SdCity | a..50 | M | Town/City of delivery address |
| SdDistrict | a..50 | O | District/Country of delivery address |
| SdState | a..50 | C | Federal state of delivery address. Not suppoerted if yountryCode is: ´UK´, `GB`, `SG`, ´AE´, ´MX´ |
| SdZipcode | a..50 | M | Postcode in the delivery address |
| SdCountryCode | an2 | M | Country code of delivery country according to ISO 3166 |
| SdPhone | a..128 | M | Phone Number of address in the delivery address |
‘UK’ ,’GB’ ,’DE’ ,’FR’ ,’IT’ ,’ES’ ,’AT’ ,’BE’ ,’BG’ ,’HR’ ,’CY’ ,’CZ’ ,’DK’ ,’EE’ ,’FI’ ,’GR’ ,’HU’ ,’IE’ ,’LV’ ,’LT’ ,’LU’ ,’MT’ ,’NL’ ,’PL’ ,’PT’ ,’RO’ ,’SK’ ,’SI’ ,’SE’
JP
| Parameter | Format | CND | Beschreibung |
| Name | as..50 | M | First name and surname of address |
| SdStreet | a..180 | M | Company name (if given) or street name and street number |
| SdStreet2 | a..60 | O | Street name and house number |
| SdAddressAddition | a..60 | O | Other additions |
| SdCity | a..50 | M | Town/city in the delivery address |
| SdDistrict | a..50 | O | District/Country of delivery address |
| SdState | a..50 | C | State or region |
| SdZipcode | a..50 | M | Postcode in the delivery address |
| SdCountryCode | an2 | M | Country code of delivery country according to ISO 3166 |
| SdPhone | a..128 | M | Phone number of address in the delivery address |
US
| Parameter | Format | CND | Beschreibung |
| Name | as..50 | M | First name and surname of address |
| SdStreet | a..180 | M | Company name (if given) or street name and stretet number |
| SdStreet2 | a..60 | O | Street name and house number |
| SdAddressAddition | a..60 | O | Other additions |
| SdCity | a..50 | M | Town/City in the delivery address |
| SdDistrict | a..50 | O | District/Country of delivery address |
| SdState | a..50 | C | State or region |
| SdZipcode | a..50 | M | Postcode in the delivery address |
| SdCountryCode | an2 | M | Country code of delivery country accordings to ISO 3166 |
| SdPhone | a..128 | M | Phone number of address in the delivery address |
“Als eine der bekanntesten Opernhäuser der Welt steht die Semperoper Dresden für herausragende Kultur und Qualität.
Im Bereich der Zahlungs-abwicklung setzen wir deshalb auf die 1cs – für uns die perfekte Kombination aus persönlicher Betreuung und individuelle Beratung auf höchstem Niveau.”
Doris Schneider,
Leiterin Vertrieb und Service
“Wir setzen bei Fahrrad XXL auf den verlässlichen Service der First Cash Solution und fühlen uns hier bestens aufgehoben!”
Peter Hürter, Fahrrad XXL
“Die First Cash Solution ist stets zuverlässig und bietet einen
super Service durch ständige Bereitschaft uns zu helfen
sowie schnelle und kompetente Antworten auf all unsere Fragen.”
Thomas Quindt,
Projektleiter SOCCERBEAT GmbH
Gebühr der Kartenorganisationen:
Werden von den Kreditkartenorganisationen wie Visa oder Mastercard erhoben, sie werden auch Card Scheme Fees (CSF) genannt.
Bearbeitungsgebühr:
Wird von Deinem Zahlungsanbieter/Acquirer berechnet, in Deinem Fall von uns (1cs). Sie wird auch Acquirer Service Fee (ASF) genannt.
Interchange-Gebühr:
Wird von der kartenherausgebenden Bank bzw. Issuer in Rechnung gestellt. Sie wird auch Interchange Fee (ICF) genannt.
“Hier wird uns bei jedem Anliegen kompetent, unkompliziert und schnell geholfen! Daher können wir die First Cash Solution nur empfehlen.”
Sandra von Bargen, Hachez CHOCOVERSUM GmbH
„Die unkomplizierte schnelle Betreuung passt 100% zu uns und unserem Abrechnungssystem.“
Markus Tanger, Road House Paderborn