Recursos para IA

Integração via Mercado Pago para websites

Este modelo permite oferecer Apple Pay no seu site sem gerenciar certificados de pagamento nem descriptografar tokens no seu servidor. O Mercado Pago faz a validação com a Apple e devolve um token pronto para criar o pagamento.

sequenceDiagram
    participant C as Comprador
    participant V as Site (frontend)
    participant MP as Mercado Pago
    participant A as Apple

    V->>MP: Inicializar Apple Pay
    MP->>A: Validar comércio e domínio
    A-->>V: Botão Apple Pay disponível
    C->>V: Clique em Apple Pay
    V->>A: Solicitação de pagamento (Touch ID/Face ID)
    A-->>MP: Token do Apple Pay
    MP-->>V: Token do Mercado Pago (callback)
    V->>V: Enviar token ao backend
    V->>MP: Criar pagamento (token + dados)
    MP-->>V: Resposta do pagamento

Nesta integração você implementa o fluxo Apple Pay no seu backend, onde será validada a sessão com a Apple e obtido o token pelas APIs do Mercado Pago para criar o pagamento. Siga os passos a seguir para integrar.

Validar a sessão para o fluxo de tokenização

Tendo obtido e configurado os certificados obrigatórios do Apple Developer, antes de iniciar a tokenização com a Apple, o seu backend deve validar a sessão Apple Pay com o certificate_id do certificado merchant e os dados que a Apple envia ao frontend. Para isso, envie uma solicitação com sua Public Key de testeChave pública que é utilizada no frontend para acessar informações e criptografar dados. Você pode acessá-la através de Suas integrações > Dados da integração, indo até a seção Credenciais, localizada à direita da tela, e clicando em Teste. Alternativamente, você também poderá acessá-la a partir de Suas integrações > Dados da aplicação > Testes > Credenciais de teste. ao 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.seu-identificador",
    "domainName": "seu-dominio.com",
    "displayName": "Minha loja",
    "initiative": "web",
    "initiativeContext": "seu-dominio.com",
    "validationURL": "https://apple-pay-gateway.apple.com/paymentservices/startSession"
  }'

Parâmetro	Tipo	Descrição	Obrigatoriedade
`X-Product-ID`	Header	Identificador do produto.	Obrigatório
`X-Public-key`	Header	Header com sua Public Key de testeChave pública que é utilizada no frontend para acessar informações e criptografar dados. Você pode acessá-la através de Suas integrações > Dados da integração, indo até a seção Credenciais, localizada à direita da tela, e clicando em Teste. Alternativamente, você também poderá acessá-la a partir de Suas integrações > Dados da aplicação > Testes > Credenciais de teste..	Obrigatório
`id`	String	ID do certificado tipo merchant obtido ao obter os certificados do Apple Developer.	Obrigatório
`merchantIdentifier`	String	Merchant ID configurado na Apple.	Obrigatório
`domainName`	String	Domínio do seu site onde o botão Apple Pay é exibido. Deve coincidir com o domínio verificado no Portal Apple Developer e onde o arquivo de verificação está publicado em `.well-known`.	Obrigatório
`displayName`	String	Nome do seu comércio ou loja exibido ao usuário no fluxo de pagamento do Apple Pay.	Obrigatório
`initiative`	String	Valor fixo `web`.	Obrigatório
`initiativeContext`	String	Deve coincidir com o parâmetro `domainName`, que é o domínio do seu site onde o botão Apple Pay é exibido.	Obrigatório
`validationURL`	String	URL que a Apple envia ao seu frontend ao iniciar o fluxo. Envie-a aqui sem modificá-la.	Obrigatório

A API devolve uma resposta com estrutura semelhante ao exemplo a seguir. Inclui merchantSessionIdentifier e outros dados que o seu frontend usará para concluir o fluxo com a Apple:

json
{
  "epochTimestamp": 1768253984908,
  "expiresAt": 1768257584908,
  "merchantSessionIdentifier": "SSH1920C0C97402...7B1B1A97F33C9C3",
  "nonce": "124074e7",
  "merchantIdentifier": "10DDB60D113BB4...CDF76292133",
  "domainName": "seu-dominio.com",
  "displayName": "Minha loja",
  "signature": "308006092...2f5d0c8000000000000"
}

Tokenização do pagamento

Quando o comprador autoriza o pagamento com Apple Pay, a Apple devolve no frontend os dados de pagamento criptografados. Envie esses dados ao seu backend, enviando uma solicitação com sua Public Key de testeChave pública que é utilizada no frontend para acessar informações e criptografar dados. Você pode acessá-la através de Suas integrações > Dados da integração, indo até a seção Credenciais, localizada à direita da tela, e clicando em Teste. Alternativamente, você também poderá acessá-la a partir de Suas integrações > Dados da aplicação > Testes > Credenciais de teste. ao endpoint /platforms/pci/applepay/v1/tokenizeAPI para obter um card token do 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"
      }
    }
  }'

Parâmetro	Tipo	Descrição	Obrigatoriedade
`X-Product-ID`	Header	Identificador do produto.	Obrigatório
`X-Public-key`	Header	Header com sua Public Key de testeChave pública que é utilizada no frontend para acessar informações e criptografar dados. Você pode acessá-la através de Suas integrações > Dados da integração, indo até a seção Credenciais, localizada à direita da tela, e clicando em Teste. Alternativamente, você também poderá acessá-la a partir de Suas integrações > Dados da aplicação > Testes > Credenciais de teste..	Obrigatório
`payment_method.type`	String	Tipo de meio de pagamento. Para pagamentos com Apple Pay, o valor fixo é `applepay`.	Obrigatório
`payment_method.payment_data`	String	Dados de pagamento que a Apple envia ao frontend, devolvidos em formato Base64. Quando o usuário autoriza o pagamento no dispositivo Apple, o navegador dispara o evento `onpaymentauthorized` e, a partir disso, dentro de evento `payment.token.paymentData` estará um objeto `JavaScript` com os dados do cartão criptografados pela Apple. O objeto retornado deverá ser convertido para uma string `JSON` e depois codificado em Base64.	Obrigatório
`transaction_identifier`	String	Identificador da transação que a Apple envia ao frontend. É uma string hexadecimal única e gerada pela Apple para cada transação.	Obrigatório
`device.meli.session_id`	String	Identificador de sessão do dispositivo. Deve ser inicializado na página antes do clique no botão Apple Pay. O valor fica disponível na variável `global window.MP_DEVICE_SESSION_ID` e tem como origem o SDK de device fingerprint do Mercado Pago (Armor).	Opcional

A API devolve uma resposta com estrutura semelhante ao exemplo a seguir:

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

Parâmetro	Tipo	Descrição	Obrigatoriedade
`id`	String	Token do cartão. Use-o como `token` ao criar o pagamento com a Orders API.	Obrigatório
`bin`	String	Primeiros dígitos do cartão.	Obrigatório

Criar o pagamento

Crie o pagamento enviando uma solicitação com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. ao endpoint /v1/ordersAPI com os valores descritos na tabela a seguir.

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": "COP",
    "external_reference": "ext_ref_1234",
    "payer": {
      "email": "comprador@email.com",
      "identification": {
        "type": "NIT",
        "number": "123456789"
      }
    },
    "transactions": {
      "payments": [
        {
          "amount": "100.00",
          "payment_method": {
            "id": "visa",
            "type": "credit_card",
            "token": "ID_RETORNADO_PELA_TOKENIZACAO",
            "installments": 1
          }
        }
      ]
    }
  }'

Parâmetro	Tipo	Descrição	Obrigatoriedade
`Authorization`	Header	Header com seu Access Token de testeChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste..	Obrigatório
`X-Idempotency-Key`	Header	Valor único por requisição (UUID v4) para evitar pagamentos duplicados.	Obrigatório
`type`	Body. String	Tipo de order. Valor fixo `online`.	Obrigatório
`processing_mode`	Body. String	Modo de processamento da order. Os valores possíveis são: - `automatic`: para criar e processar a ordem em modo automático. - `manual`: para criar a order e processá-la posteriormente. Para mais informações, acesse a seção Modelo de integração.	Obrigatório
`total_amount`	Body. String	Valor total da transação.	Obrigatório
`external_reference`	Body. String	Referência para sincronizar a order com o seu sistema.	Opcional
`payer.email`	Body. String	E-mail do comprador.	Obrigatório
`payer.identification.type`	Body. String	Tipo de documento de identificação do comprador. Você pode consultar os valores disponíveis enviando uma requisição ao endpoint Obter tipos de documento.	Obrigatório
`payer.identification.number`	Body. String	Número do documento de identificação do comprador.	Obrigatório
`transactions.payments[].amount`	Body. String	Valor da transação.	Obrigatório
`transactions.payments[].payment_method.id`	Body. String	Identificador do meio de pagamento. Neste caso, é a bandeira de cada cartão. Você pode consultar a lista completa de identificadores disponíveis enviando uma requisição ao endpoint Obter meios de pagamento.	Obrigatório
`transactions.payments[].payment_method.type`	Body. String	Tipo de meio de pagamento. Para pagamentos com cartão de crédito, deve ser `credit_card`, e para pagamentos com cartão de débito, deve ser `debit_card`.	Obrigatório
`transactions.payments[].payment_method.token`	Body. String	Token do cartão obtido na etapa Tokenização do pagamento.	Obrigatório
`transactions.payments[].payment_method.installments`	Body. Integer	Número de parcelas em que o pagamento será dividido.	Obrigatório

Para conhecer todos os parâmetros disponíveis, consulte a referência da Orders API.

AnteriorIntroduçãoConheça os diferentes modelos de integração do Apple Pay e escolha o que melhor se adapte ao seu negócio.

PróximoIntegração via Mercado Pago para aplicações móveisIntegre o Apple Pay como meio de pagamento com processamento próprio do token para aplicações móveis.