AI resources

Mercado Pago integration for websites

This model lets you offer Apple Pay on your website without managing payment certificates or decrypting tokens on your server. Mercado Pago handles validation with Apple and returns a token ready to create the payment.

sequenceDiagram
    title How it works
    participant C as Buyer
    participant V as Website (frontend)
    participant MP as Mercado Pago
    participant A as Apple

    V->>MP: Initialize Apple Pay
    MP->>A: Validate merchant and domain
    A-->>V: Apple Pay button available
    C->>V: Click Apple Pay
    V->>A: Payment request (Touch ID/Face ID)
    A-->>MP: Apple Pay token
    MP-->>V: Mercado Pago token (callback)
    V->>V: Send token to backend
    V->>MP: Create payment (token + data)
    MP-->>V: Payment response

In this integration you implement the Apple Pay flow in your backend. Your backend validates the session with Apple and obtains the token through Mercado Pago APIs to create the payment. Follow the steps below to integrate.

Validate the session for tokenization flow

Having obtained and configured the required Apple Developer certificates, before starting tokenization with Apple, your backend must validate the Apple Pay session with the merchant certificate certificate_id and the data Apple sends to the frontend. To do so, send a POST with your test Public KeyPublic key used in the frontend to access information and encrypt data. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /applepay/v1/sessionAPI.

curl --location 'https://api.mercadopago.com/applepay/v1/session' \
  --header 'X-Product-ID: {{YOUR_PRODUCT_ID}}' \
  --header 'Content-Type: application/json' \
  --header 'X-Public-key: {{YOUR_PUBLIC_KEY}}' \
  --data '{
    "id": "CERTIFICATE_ID_MERCHANT",
    "merchantIdentifier": "merchant.your-identifier",
    "domainName": "your-domain.com",
    "displayName": "My store",
    "initiative": "web",
    "initiativeContext": "your-domain.com",
    "validationURL": "https://apple-pay-gateway.apple.com/paymentservices/startSession"
  }'

Parameter	Type	Description	Required
`X-Product-ID`	Header	Product identifier.	Required
`X-Public-key`	Header	Header with your test Public KeyPublic key used in the frontend to access information and encrypt data. You can access it through Your integrations > Integration data > Tests > Test credentials..	Required
`id`	String	Certificate ID of the merchant certificate obtained when obtaining the Apple Developer certificates.	Required
`merchantIdentifier`	String	Merchant ID configured in Apple.	Required
`domainName`	String	Domain of your site where the Apple Pay button is displayed. Must match the domain you verified in the Apple Developer Portal and where the verification file is published in `.well-known`.	Required
`displayName`	String	Name of your merchant or store shown to the user in the Apple Pay payment flow.	Required
`initiative`	String	Fixed value `web`.	Required
`initiativeContext`	String	Must match `domainName`.	Required
`validationURL`	String	URL that Apple sends to your frontend when starting the flow; send it here unchanged.	Required

The API returns a response with a structure similar to the following example. It includes merchantSessionIdentifier and other data that your frontend will use to complete the flow with Apple:

json
{
  "epochTimestamp": 1768253984908,
  "expiresAt": 1768257584908,
  "merchantSessionIdentifier": "SSH1920C0C97402...7B1B1A97F33C9C3",
  "nonce": "124074e7",
  "merchantIdentifier": "10DDB60D113BB4...CDF76292133",
  "domainName": "your-domain.com",
  "displayName": "My store",
  "signature": "308006092...2f5d0c8000000000000"
}

Payment tokenization

When the buyer authorizes the payment with Apple Pay, Apple returns the encrypted payment data in the frontend. Send that data to your backend and, from there, send a POST with your test Public KeyPublic key used in the frontend to access information and encrypt data. You can access it through Your integrations > Integration data > Tests > Test credentials. to the endpoint /platforms/pci/applepay/v1/tokenizeAPI to obtain a card token from Mercado Pago.

curl --location 'https://api.mercadopago.com/platforms/pci/applepay/v1/tokenize' \
  --header 'X-Product-ID: {{YOUR_PRODUCT_ID}}' \
  --header 'Content-Type: application/json' \
  --header 'X-Public-key: {{YOUR_PUBLIC_KEY}}' \
  --data '{
    "payment_method": {
      "type": "applepay",
      "payment_data": "PAYMENT_DATA_FROM_APPLE_BASE64"
    },
    "transaction_identifier": "TRANSACTION_ID_FROM_APPLE",
    "device": {
      "meli": {
        "session_id": "SESSION_ID_DEVICE"
      }
    }
  }'

Parameter	Type	Description	Required
`X-Product-ID`	Header	Product identifier.	Required
`X-Public-key`	Header	Header with your test Public KeyPublic key used in the frontend to access information and encrypt data. You can access it through Your integrations > Integration data > Tests > Test credentials..	Required
`payment_method.type`	String	Fixed value `applepay`.	Required
`payment_method.payment_data`	String	Payment data that Apple sends to the frontend, returned in Base64 format. When the user authorizes the payment on an Apple device, the browser triggers the `onpaymentauthorized` event and, from that point on, within `payment.token.paymentData` there will be a `JavaScript` object containing the card data encrypted by Apple. The returned object must be converted to a `JSON` string and then encoded in Base64.	Required
`transaction_identifier`	String	Transaction identifier that Apple sends to the frontend. It is a unique hexadecimal string generated by Apple for each transaction.	Required
`device.meli.session_id`	String	Device session identifier. It must be initialized on the page before clicking the Apple Pay button. The value is available in the global variable `window.MP_DEVICE_SESSION_ID` and comes from Mercado Pago’s device fingerprint SDK (Armor).	Optional

The API returns a response with a structure similar to the following example:

json
{
  "id": "5c055ff0d...00b888c85c64e",
  "bin": "44...49"
}

Parameter	Type	Description	Required
`id`	String	Card token. Use it as `token` when creating the payment with the Orders API.	Required
`bin`	String	First digits of the card.	Required

Create the payment

Create the payment by sending a POST with your test Access TokenPrivate key of the application created in Mercado Pago, that must be used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials. to /v1/ordersAPI with the values described in the table below.

curl --location 'https://api.mercadopago.com/v1/orders' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
  --header 'X-Idempotency-Key: SOME_UNIQUE_VALUE' \
  --data '{
    "type": "online",
    "processing_mode": "automatic",
    "total_amount": "100.00",
    "currency_id": "MXN",
    "external_reference": "ext_ref_1234",
    "payer": {
      "email": "buyer@email.com",
      "identification": {
        "type": "CURP",
        "number": "GARC800101HDFRRL09"
      }
    },
    "transactions": {
      "payments": [
        {
          "amount": "100.00",
          "payment_method": {
            "id": "visa",
            "type": "credit_card",
            "token": "ID_RETURNED_BY_TOKENIZATION",
            "installments": 1
          }
        }
      ]
    }
  }'

Parameter	Type	Description	Required
`Authorization`	Header	Header with your test Access TokenPrivate key of the application created in Mercado Pago, that must be used in the backend. You can access it through Your integrations > Integration data > Tests > Test credentials..	Required
`X-Idempotency-Key`	Header	Unique value per request (UUID v4) to avoid duplicate payments.	Required
`type`	Body. String	Order type. Fixed value `online`.	Required
`processing_mode`	Body. String	Processing mode of the order. The possible values are: - `automatic`: to create and process the order in automatic mode. - `manual`: to create the order and process it later. For more information, visit the section Integration model.	Required
`total_amount`	Body. String	Total amount for the transaction.	Required
`external_reference`	Body. String	Reference to sync the order with your system.	Optional
`payer.email`	Body. String	Buyer's email address.	Required
`payer.identification.type`	Body. String	Buyer's identification document type. You can check the available values by sending a request to the Get identification types endpoint.	Required
`payer.identification.number`	Body. String	Buyer's identification document number.	Required
`transactions.payments[].amount`	Body. String	Transaction amount.	Required
`transactions.payments[].payment_method.id`	Body. String	Payment method identifier. In this case, it is the brand of each card. You can check the complete list of available identifiers by sending a request to the Get payment methods endpoint.	Required
`transactions.payments[].payment_method.type`	Body. String	Payment method type. For credit card payments, it should be `credit_card`, and for debit card payments, it should be `debit_card`.	Required
`transactions.payments[].payment_method.token`	Body. String	Card token obtained in the Payment tokenization step.	Required
`transactions.payments[].payment_method.installments`	Body. Integer	Number of installments the payment will be split into.	Required

To see all available parameters, see the Orders API reference.

PreviousIntroductionLearn about the different Apple Pay integration models and choose the one that best suits your business.

NextIntegration via Mercado Pago for mobile appsIntegrate Apple Pay as a payment method with your own token processing for mobile apps.