Skip to content

Custom merchant page integration

Our standard merchant page integration template offers a customizable but rapid way to start accepting payments on your website. However, you can achieve an even greater degree of customization by building your own payment form to accommodate your unique use-case, business logic, or technical requirements.

We call it custom merchant page integration. When you choose our custom merchant page integration route you build a custom form that collects payment details and that sends these payment details to the Amazon Payment Services server for authorization.

By doing so you gain full control the form that collects payment card data. You use your own form design to collect payment card details. Unlike standard merchant page integration this integration route does not use an integrated iframe.

A custom merchant page integration form in action

When should you use custom merchant page integration?

Custom merchant page integration is a good choice if you want to build a highly customized payment experience, or if you want to accommodate a unique use case or challenging technical requirements.

Taking the Custom Merchant Page Integration route results in the same trusted, robust payment processing as our standard integration but it does offer you more opportunity to fine tune what exactly your customers see.

Note that your form still submits sensitive payment card data directly to Amazon Payment Services. Configured correctly, your custom merchant page integration will not submit sensitive payment card data to your own server.

However, we expect that most merchants would choose standard merchant page integration. Also note that we offer a specific route for recurring payments.

Mobile in-app payments

Custom merchant payment integration can be used to enable in-app payments in your Android or iOS app. You will need to code your own payment experience that allows your customers to pay inside your mobile app. To do so you have access to the full Amazon Payment Services API — via the custom merchant page integration route.

However , we highly recommend using our mobile sdks (IOS SDK,Android SDK,Flutter SDK, React Native SDK) which are easier and more straight forward to implement as it requires less development effort and skills compared to custom-coding your own in-app payment experience.

How does it work in practice?

If you choose the custom merchant page integration route you are responsible to code a form that captures your customer's payment details and that submits these details to our server using defined parameters. You integrate your custom form on your checkout page.

There is no need to change the look and feel of your merchant site. You can customize the iframe to match your site. Simply insert the Amazon Payment Services iframe in the section of your page where you want to accept credit card payments.

In practice, custom merchant page integration works like this:

  1. You develop a custom payment form that collects the credit card details including card number, expiry date, CVV number.

  2. Your customer fills in their card details in the custom payment form on your checkout page.

  3. The Amazon Payment Services server receives the card details and attempts to authorize the customer's payment.

  4. Amazon Payment Services sends a confirmation to your checkout page to complete the transaction, this confirmation includes a token.

  5. You use the token to complete the Authorization or Purchase operation.

Your payment form must never send sensitive payment card data to your website. Your form must be coded to send data directly to the Amazon Payment Services server.

Note that you must correctly and adequately handle transaction feedback when you implement custom merchant page integration. Every payment transaction that you process will trigger a response -- and your website must be able to interpret and respond to the transaction feedback. Read more about transaction feedback here.

Payment workflow

Customer merchant page integration gives your customer a highly customized, seamless experience. But what happens in the background? This is the workflow when you use the standard merchant page integration:

  1. Your customer begins the checkout process on your website.

  2. Your website displays your custom payment form to capture your customer's card details.

  3. The customer enters their card details on the payment page.

  4. Amazon Payment Services verifies that the card details are correct.

  5. Next, Amazon Payment Services creates a token for the transaction and sends it to your payment page.

  6. Your payment page sends a JSON request along with the token to Amazon Payment Services.

  7. If your customer's bank uses 3D Secure, and if a check is required, your page will receive a 3D Secure URL (3DS URL) from the Amazon Payment Services server and a response indicating that a 3D Secure verification will take place:

    i. The payment page redirects the customer to the 3D Secure Access Control Server (ACS) to verify card enrollment.

    ii. The customer enters their authentication data on the ACS page.

    iii. The ACS attempts to authenticate the customer's data and sends the authentication results to Amazon Payment Services.

  8. Amazon Payment Services completes the operation based on the 3D Secure response.

  9. The payment authentication result is sent to your site.

👆 If you included a token in the request sent to us (by using the token_name parameter) and if the token you provided has already been associated with an successful authorization, Amazon Payment Services will render an iframe that displays the customer's masked payment card number and expiry date.

👆 When we refer to any of: payment processing page, payment form, or payment details form we are always referring to the payment page on your site. In other words, the area on your website where your customer entered payment details.

Tokenization and custom merchant page integration

Tokenization is also critical to the operation of the custom merchant page integration. A token is always generated, but it is your choice to make use of tokens to enable the retention of payment card data -- if your customer agrees.

Learn more about merchant page integration and tokenization here. For full coverage of tokenization, read this page.

Form submission and response

The form you developed will submit a request in a form post. This request will contain the required parameters -- visit this page in our API reference for a list of parameters.

Go to the full API reference

This page is intended to help you understand how the custom merchant page integration route works. Developers should review the full API reference for complete instructions on how to implement custom merchant page integration including a full list of parameters and the relevant endpoints.

Need further help?

If you get stuck feel free to get in touch with the Amazon Payment Services team. Just message our support team at