Skip to content

Cobrança com Apple Pay ​

Receba pagamentos com Apple Pay no checkout do seu site. O pagador confirma com Face ID ou Touch ID, sem digitar o cartão.

Para a DiviPay é um pagamento de cartão de crédito como qualquer outro: o saldo, o webhook, a consulta e o estorno funcionam igual. Você não precisa de conta Apple Developer nem de certificado. A DiviPay faz a validação do lojista com a Apple em nome do seu site.

O que você precisa saber antes ​

ItemRegra
Onde funcionaSafari no iPhone, iPad e Mac, em página HTTPS
BandeirasVisa e Mastercard
TipoCrédito. A cobrança é sempre processada como crédito
3DSNão se aplica. A própria carteira autentica o pagador
Recorrência e cartão salvoNão. Apple Pay vale só para pagamento avulso
Dados do pagadorclient (nome e CPF/CNPJ) continua obrigatório. O Apple Pay não fornece CPF, então colete antes de abrir a folha
Parcelamentoinstallments segue as regras do cartão. A API não acrescenta a taxa de parcelamento: envie o amount já com o valor final

Pré-requisitos ​

  1. Credenciais de API com a permissão de cartão de crédito (CREDIT_CARD_API). Veja Autenticação.

  2. Apple Pay habilitado na sua conta. A DiviPay liga o recurso. Para conferir, consulte GET /api/charge/credit-card/provider e veja se applePay é true.

  3. Domínio cadastrado pela DiviPay. Envie à DiviPay o host exato de cada página onde o botão vai aparecer (por exemplo seusite.com.br e www.seusite.com.br; cada um é um cadastro). O cadastro é sempre vinculado às suas credenciais: outro cliente não consegue usar o seu domínio e você não consegue usar o de outro.

  4. Arquivo de verificação publicado no seu domínio. A DiviPay entrega o arquivo apple-developer-merchantid-domain-association. Publique-o em cada host cadastrado, exatamente neste endereço:

    https://seusite.com.br/.well-known/apple-developer-merchantid-domain-association
    • tem que responder 200 com o conteúdo do arquivo, por HTTPS;
    • sem redirecionamento (nem de seusite.com.br para www.seusite.com.br, nem de http para https);
    • sem exigir login nem cookie.

ATENÇÃO

Se o arquivo não estiver acessível, ou o host não estiver cadastrado, o Safari não abre a folha do Apple Pay e o botão fica sem efeito. Teste a URL do arquivo no navegador antes de pedir a liberação.

Fluxo ​

Navegador (seu checkout)        Seu backend                    DiviPay                 Apple
        |                            |                            |                      |
        | 1. clique no botão         |                            |                      |
        |    new ApplePaySession     |                            |                      |
        | 2. onvalidatemerchant ---> | POST .../apple-pay/session |                      |
        |    (validationURL)         | -------------------------> | validação do lojista |
        |                            |                            | -------------------> |
        | <--- merchantSession ----- | <------------------------- | <------------------- |
        |    completeMerchantValidation                           |                      |
        | 3. Face ID / Touch ID      |                            |                      |
        | 4. onpaymentauthorized --> | POST /api/charge/credit-card                      |
        |    (paymentData)           | -------------------------> |                      |
        | <--- resultado ----------- | <------------------------- |                      |
        |    completePayment         |                            |                      |

As chamadas à DiviPay saem sempre do seu backend. O token de acesso nunca vai para o navegador.

No navegador ​

1. Mostrar o botão ​

Mostre o botão só quando as duas condições forem verdadeiras:

  • window.ApplePaySession existe e ApplePaySession.canMakePayments() retorna true;
  • o seu backend confirmou que a conta tem Apple Pay (applePay: true em GET /provider).

Use o botão oficial da Apple (CSS -apple-pay-button ou <apple-pay-button>). Veja as diretrizes de identidade visual.

2. Abrir a folha do Apple Pay ​

Use estes valores, sem alterar:

CampoValor
Versão do ApplePaySession3
countryCode'BR'
currencyCode'BRL'
supportedNetworks['visa', 'masterCard']
merchantCapabilities['supports3DS', 'supportsCredit']
total.amounto mesmo amount que você enviará à API, como texto com duas casas ('200.00')
total.labelo nome que o pagador vê (sua loja)

O new ApplePaySession(...) precisa rodar dentro do clique do botão. Não coloque await nem fetch antes dele, ou o Safari recusa.

javascript
function pagarComApplePay({ amount, label, pedidoId }) {
  const request = {
    countryCode: 'BR',
    currencyCode: 'BRL',
    supportedNetworks: ['visa', 'masterCard'],
    merchantCapabilities: ['supports3DS', 'supportsCredit'],
    total: { label, amount: amount.toFixed(2) }
  };

  const session = new ApplePaySession(3, request);

  // A Apple entrega a URL de validação; seu backend pede a sessão à DiviPay
  session.onvalidatemerchant = async (event) => {
    try {
      const res = await fetch('/apple-pay/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ validationURL: event.validationURL })
      });
      if (!res.ok) throw new Error('Validação recusada');
      session.completeMerchantValidation(await res.json());
    } catch (err) {
      session.abort();
    }
  };

  // O pagador confirmou: mande o token ao seu backend
  session.onpaymentauthorized = async (event) => {
    try {
      const res = await fetch('/apple-pay/pagar', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          pedidoId,
          paymentData: event.payment.token.paymentData
        })
      });
      session.completePayment(
        res.ok ? ApplePaySession.STATUS_SUCCESS : ApplePaySession.STATUS_FAILURE
      );
    } catch (err) {
      session.completePayment(ApplePaySession.STATUS_FAILURE);
    }
  };

  session.begin();
}

TEMPO

Depois da autorização, a folha espera por volta de 30 segundos pelo completePayment. Mantenha o seu backend rápido e sempre chame completePayment, com sucesso ou falha.

No seu backend ​

Os exemplos usam Node.js com Express. O token é o Bearer da DiviPay (veja Autenticação).

javascript
const DIVIPAY = 'https://api.divipay.com.br';

// Passo 2: validação do lojista
app.post('/apple-pay/session', async (req, res) => {
  const token = await obterTokenDiviPay();

  const response = await fetch(`${DIVIPAY}/api/charge/credit-card/apple-pay/session`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      validationURL: req.body.validationURL,
      domain: new URL(req.get('origin')).hostname
    })
  });

  // Devolva o corpo exatamente como veio: o Safari consome esse objeto
  res.status(response.status).json(await response.json());
});

// Passo 4: pagamento
app.post('/apple-pay/pagar', async (req, res) => {
  const token = await obterTokenDiviPay();
  const pedido = await buscarPedido(req.body.pedidoId);

  const response = await fetch(`${DIVIPAY}/api/charge/credit-card`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: pedido.total,
      description: 'Compra Online',
      referenceId: pedido.id,
      callbackUrl: 'https://seusite.com/webhook',
      installments: 1,
      card: {
        applePay: { paymentData: req.body.paymentData }
      },
      client: {
        name: pedido.cliente.nome,
        document: pedido.cliente.cpf,
        email: pedido.cliente.email,
        phone: pedido.cliente.telefone,
        ip: req.ip
      },
      itens: [
        { name: 'Produto Digital', quantity: 1, unitPrice: pedido.total, feePercent: 0 }
      ]
    })
  });

  res.status(response.status).json(await response.json());
});

IMPORTANTE

  • Nunca registre em log o paymentData. Ele é o token de pagamento do portador.
  • O paymentData é de uso único. Para tentar de novo, abra a folha do Apple Pay outra vez e gere um token novo.
  • POST /api/charge/credit-card não é idempotente: cada chamada cria uma nova cobrança. Não faça retentativa automática.

GET /api/charge/credit-card/provider ​

Informa qual provedor de cartão a sua conta usa e se o Apple Pay está disponível.

Endpoint ​

GET https://api.divipay.com.br/api/charge/credit-card/provider

Headers ​

HeaderValorObrigatório
AuthorizationBearerSim

PERMISSÃO

Esta rota exige a permissão MERCADO_PAGO_API nas credenciais, a mesma das outras rotas de consulta do provedor (public-key e session do cartão). Se as suas credenciais só têm CREDIT_CARD_API, peça a liberação à DiviPay ou confirme o Apple Pay tentando a sessão: sem Apple Pay ela responde 422.

Exemplo de Requisição ​

bash
curl -X GET https://api.divipay.com.br/api/charge/credit-card/provider \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta ​

json
{
  "providerType": "PAG_SEGURO",
  "integrationId": "8f0b6d3e-2d57-4f0e-a3a1-6b1c0f4d9e11",
  "applePay": true,
  "pagseguro": {
    "sessionId": "abc123xyz789",
    "publicKey": "-----BEGIN PUBLIC KEY-----..."
  }
}
CampoDescrição
applePaytrue quando a conta aceita Apple Pay: provedor PagBank, recurso ligado e certificados válidos. false caso contrário (inclusive quando a conta não usa PagBank). Não gera erro

POST /api/charge/credit-card/apple-pay/session ​

Faz a validação do lojista com a Apple. Chame esta rota no onvalidatemerchant.

Endpoint ​

POST https://api.divipay.com.br/api/charge/credit-card/apple-pay/session

Headers ​

HeaderValorObrigatório
AuthorizationBearerSim
Content-Typeapplication/jsonSim

Body Parameters ​

CampoTipoDescriçãoObrigatório
validationURLstringevent.validationURL do onvalidatemerchant, sem alterarSim
domainstringHost da página onde o botão está (www.seusite.com.br). Aceita também a origin (https://www.seusite.com.br); maiúsculas, esquema e porta são ignoradosSim

Exemplo de Requisição ​

bash
curl -X POST https://api.divipay.com.br/api/charge/credit-card/apple-pay/session \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "validationURL": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain": "www.seusite.com.br"
  }'

Resposta de Sucesso ​

Status: 201 Created

O corpo é o objeto de sessão que a Apple devolve. Ele é opaco: repasse-o ao navegador sem mexer, e o navegador o entrega ao completeMerchantValidation.

Erros ​

StatusMensagemCausa
400validationURL inválidaA URL não é https ou o host não é um gateway oficial do Apple Pay. Envie exatamente o event.validationURL
400Domínio não habilitado para Apple PayO domain não está cadastrado para as suas credenciais (ou é inválido)
422Apple Pay não habilitado para esta contaSua conta não tem Apple Pay: recurso desligado, provedor que não é PagBank, ou domínio ligado a um Merchant ID que não atende a sua conta
422Apple Pay indisponívelO certificado de identidade da DiviPay está ausente ou vencido. Fale com a DiviPay
502Não foi possível iniciar o Apple PayA Apple recusou a validação ou demorou demais. Confira se o arquivo de verificação está publicado no domínio, sem redirecionamento

Campos ausentes ou com tipo errado respondem 400 no formato de validação.

POST /api/charge/credit-card (com Apple Pay) ​

É a mesma rota de Cartão de Crédito. Para pagar com Apple Pay, o objeto card passa a aceitar uma quarta forma, applePay, no lugar de cardNumber, cardToken e encryptedCard.

Objeto Card com Apple Pay ​

CampoTipoDescriçãoObrigatório
applePayobjectPagamento com a carteira Apple PaySim
applePay.paymentDataobjectevent.payment.token.paymentData do onpaymentauthorized, como objeto JSON, sem alterarSim

Não envie cardNumber, holder, expirationDate, securityCode, cardToken, encryptedCard, antiFraudId nem threedsToken junto com applePay. Os demais campos do corpo (amount, referenceId, client, installments, itens, shipping, splits etc.) são os mesmos do cartão. O client.ip continua obrigatório e precisa ser o IP público do pagador.

Exemplo de Requisição ​

bash
curl -X POST https://api.divipay.com.br/api/charge/credit-card \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200.00,
    "description": "Compra Online",
    "referenceId": "order-789",
    "callbackUrl": "https://seusite.com/webhook",
    "installments": 1,
    "card": {
      "applePay": {
        "paymentData": {
          "version": "EC_v1",
          "data": "...",
          "signature": "...",
          "header": {
            "ephemeralPublicKey": "...",
            "publicKeyHash": "...",
            "transactionId": "..."
          }
        }
      }
    },
    "client": {
      "name": "João Silva",
      "document": "12345678901",
      "email": "joao@email.com",
      "phone": "11999999999",
      "ip": "203.0.113.10"
    },
    "itens": [
      {
        "name": "Produto Digital",
        "quantity": 1,
        "unitPrice": 200.00,
        "feePercent": 0
      }
    ]
  }'

Resposta de Sucesso ​

Status: 201 Created

A resposta tem o mesmo formato da cobrança com cartão, sem o campo cardToken (o Apple Pay não salva cartão). O webhook, a consulta e o estorno também são os do cartão.

Erros ​

StatusMensagemCausa
400card.applePay.paymentData não é um paymentData válido do Apple PayO paymentData não é um objeto, está sem version, data, signature, header.publicKeyHash ou header.transactionId, ou passa de 16 KB. Envie o objeto exatamente como o Safari entregou, sem converter em texto
400Envie applePay sem outros dados de cartãoapplePay veio junto com cardNumber, cardToken ou encryptedCard
400paymentData do Apple Pay inválidoO token passou pela validação do corpo, mas está fora do formato esperado
400Apple Pay aceita só pagamento à vistainstallments maior que 1, quando o parcelamento no Apple Pay não estiver habilitado
400IP não informado ou IP interno não permitidoclient.ip ausente, ou é um IP interno. Envie o IP público do pagador
422Apple Pay não habilitado para esta contaA sua conta não tem Apple Pay (recurso desligado, provedor que não é PagBank, ou sem Merchant ID com certificado válido)
422Merchant ID não cadastrado nesta contaO token foi gerado para um Merchant ID que não é o desta conta. Confira que o validationURL passou pela rota de sessão da DiviPay
412Pagamento não pode ser efetuado. {motivo}O banco emissor recusou o pagamento. O Safari deve receber STATUS_FAILURE

Os erros comuns de cobrança (valor mínimo de R$ 5,00, parcelas acima do máximo do plano, saldo insuficiente para a taxa negativa) são os mesmos do cartão.

Bandeiras e limites ​

  • Aceitas: Visa e Mastercard. A folha só oferece cartões dessas bandeiras.
  • A cobrança é processada como crédito.
  • Sem 3DS: a autenticação é feita pela carteira (Face ID/Touch ID), então a regra de 3DS acima de R$ 400 do cartão não se aplica.
  • Sem recorrência, sem salvar cartão e sem cobrança subsequente.

Testando ​

  1. Use o ambiente Sandbox (https://pay-sandbox.hge.app) com as credenciais de sandbox.
  2. Peça à DiviPay o cadastro do seu domínio de homologação no sandbox: o cadastro de produção não vale lá, e vice-versa.
  3. Publique o arquivo de verificação do sandbox no domínio de homologação, no mesmo caminho /.well-known/.
  4. No Safari, use a carteira de um usuário de teste de sandbox da Apple. A DiviPay confirma com você qual cartão de teste usar.

Próximos Passos ​

Documentação da API DiviPay