API Reference

Configuration Guides
Setting up Merchant ID in Apple Pay

In order for your store to begin receiving payments with Apple Pay, you will need to set Merchant ID in your Apple developer account.

Creating the Merchant ID

First of all, you need to create the Merchant ID itself - your store's ID on Apple's system.

This account acts as your login to the Apple Pay setup with VTEX. More specifically, this Merchant ID will be entered in the gateway affiliation which will, in turn, process payments.

It's therefore important to choose an ID that's easy to remember. We recommend something similar to

In addition, your Merchant ID will not be the same as that of other stores. Apple's system ensures that each ID is unique.

Let's now turn our attention to the step-by-step process below:

  1. Access your Apple developer account at
  2. Select the Certificates, IDs & Profiles option.

{"base64":"  ","img":{"width":208,"height":335,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":13465,"url":""}}

  1. Select Identifiers.

{"base64":"  ","img":{"width":194,"height":237,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":6937,"url":""}}

  1. Next to Identifiers, click on the blue + button.


  1. Select the Merchant IDs option.
  2. Click on the blue Continue button.


  1. Fill on the Description field.
  2. Fill in the Identifier field.
  3. Click on Continue.


You will have created your Merchant ID.

Creating the certificate to process payments

Now you've created your Merchant ID, you'll need a certificate to activate it.

This certificate is created by VTEX. Therefore, the retailer needs to open a ticket with support for the team responsible for integrations to send you the file.

Thereafter, the retailer can submit the file to Apple Pay's system.

Follow the instructions below to proceed to this step:

  1. On the left-hand side, open Certificates from the menu.


  1. Type in your newly created Merchant ID in the search bar.
  2. Select the desired Merchant ID.


  1. Under Apple Pay Payment Processing Certificate, click the Create Certificate button.


  1. Ensure that the question "Will payments associated with this Merchant ID be processed exclusively in China?" is ticked with the default option (No).

{"base64":"  ","img":{"width":623,"height":143,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":13362,"url":""}}

You'll then be redirected to a screen with instructions on creating the Certificate Signing Request (CSR).

This is the time to open a ticket with the certificate request. The VTEX team will send you a file entitled {{merchantID}}.csr and with it saved on your computer, you must click on Continue.

After this step, you will be redirected once again, this time to the upload screen.

With the {{merchantID}}.csr that you've received, complete the following:

  1. Click on Choose File.
  2. Select the desired CSR file.
  3. Click on Continue.


  1. Click on Download.


  1. Click on Done.

Adding domains to Merchant ID

The next step is to link the domains used by your store to the Merchant ID that you've just created.

Firstly, you need to validate each of the desired URLs. Once this step is correctly completed, Apple's own system will create a .txt file and point to which domain this document should be linked to.

Lastly, you need to import this file to VTEX's system through Postman - an API management tool.

This validation can only be done one domain at a time. This means that if your store uses 10 different domains, the process will have to be repeated 10 times.

Follow these steps:

  1. Search for the recently created MerchantID in the search bar.


  1. Click on the desired MerchantID.
  2. In the Merchant Domain module, click on Add Domain.


  1. Add the domain in the Enter the domain you wish to register field.
  2. Click on Save.

Thereafter, to upload the.txt file by API, follow these instructions:

  1. Click on Download and make no changes to the file.


  1. Open the .txt file and copy all the content.

Then, start a Postman session. You perform a call to VTEX's CDN using the POST method:

  1. Configure the route POST https://{{yourdomainhere}}/.well-known/raw/apple-developer-merchantid-domain-association.txt?persistent=true.
  2. Paste the content of the .txt file in the request body. Ensure that all contents of the file are:
    • Inside quotations marks.
    • In JSON format, as in "{token_content}".
    • Without any line breaks.

{"base64":"  ","img":{"width":1836,"height":535,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":667192,"url":""}}

  1. Add the X-VTEX-API-AppKey and the X-VTEX-API-AppToken to the header.

Now, when making the POST call, the response will inform you that your certificate will be saved for 60 minutes. During this time, you should complete the domain validation.

Head back to the Apple's website. On the same screen where you downloaded the .txt file, click on Verify.


If you've followed the step-by-step correctly, your domain will be registered with the verified status. If you want, you can repeat the process to add more domains by using the Add Domain button in the Merchant Domains section.

Creating a Merchant Identity Certificate

Lastly, you must generate a Merchant ID certificate, which will be used every time Apple shows the Apple Pay screen to your customers. To complete the steps of this process, it's important that to have a Mac computer available.

To complete the action, you'll need to create a password to protect the exported data.

️ We recommend an easy to remember password, since it will be filled into the Apple Merchant Password field upon configuring the gateway affiliation on VTEX's platform.

  1. Access the Certificate, Identifiers & Profilers module.
  2. From the left side menu, choose Identifiers.
  3. In the upper right corner, filter by Merchant IDs.


  1. Select the desired Merchant Identifier.
  2. Click on Create Certificate.


  1. Follow the instructions displayed on the screen to create a certificate.
  2. Click on Continue.

{"base64":"  ","img":{"width":605,"height":682,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":75082,"url":""}}

  1. Click on Download.

{"base64":"  ","img":{"width":588,"height":377,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":41121,"url":""}}
After the file has been downloaded, double-click it to install it in Keychain Access.

Afterwards, proceed to the following steps:

  1. Open Keychain Access.
  2. Locate the certificate created in step 4 above.
  3. Right click on the key icon.

{"base64":"  ","img":{"width":582,"height":109,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":40336,"url":""}}

  1. Click on Export.
  2. Give the certificate a name.
  3. Select the .p12 export format.
  4. Click on OK.
  5. Save the certificate on your computer.

After completing all the steps above, you will have a Merchant ID set up for Apple Pay, a .p12 certificate saved on your computer, and an access password. All this data will be requested during the process of setting up the payment provider that will process payments with Apple Pay in your store.

Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
On this page