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
| Item | Regra |
|---|---|
| Onde funciona | Safari no iPhone, iPad e Mac, em página HTTPS |
| Bandeiras | Visa e Mastercard |
| Tipo | Crédito. A cobrança é sempre processada como crédito |
| 3DS | Não se aplica. A própria carteira autentica o pagador |
| Recorrência e cartão salvo | Não. Apple Pay vale só para pagamento avulso |
| Dados do pagador | client (nome e CPF/CNPJ) continua obrigatório. O Apple Pay não fornece CPF, então colete antes de abrir a folha |
| Parcelamento | installments 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
Credenciais de API com a permissão de cartão de crédito (
CREDIT_CARD_API). Veja Autenticação.Apple Pay habilitado na sua conta. A DiviPay liga o recurso. Para conferir, consulte
GET /api/charge/credit-card/providere veja seapplePayétrue.Domínio cadastrado pela DiviPay. Envie à DiviPay o host exato de cada página onde o botão vai aparecer (por exemplo
seusite.com.brewww.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.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
200com o conteúdo do arquivo, por HTTPS; - sem redirecionamento (nem de
seusite.com.brparawww.seusite.com.br, nem dehttpparahttps); - sem exigir login nem cookie.
- tem que responder
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.ApplePaySessionexiste eApplePaySession.canMakePayments()retornatrue;- o seu backend confirmou que a conta tem Apple Pay (
applePay: trueemGET /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:
| Campo | Valor |
|---|---|
Versão do ApplePaySession | 3 |
countryCode | 'BR' |
currencyCode | 'BRL' |
supportedNetworks | ['visa', 'masterCard'] |
merchantCapabilities | ['supports3DS', 'supportsCredit'] |
total.amount | o mesmo amount que você enviará à API, como texto com duas casas ('200.00') |
total.label | o 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.
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).
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-cardnã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/providerHeaders
| Header | Valor | Obrigatório |
|---|---|---|
| Authorization | Bearer | Sim |
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
curl -X GET https://api.divipay.com.br/api/charge/credit-card/provider \
-H "Authorization: Bearer SEU_TOKEN"Resposta
{
"providerType": "PAG_SEGURO",
"integrationId": "8f0b6d3e-2d57-4f0e-a3a1-6b1c0f4d9e11",
"applePay": true,
"pagseguro": {
"sessionId": "abc123xyz789",
"publicKey": "-----BEGIN PUBLIC KEY-----..."
}
}| Campo | Descrição |
|---|---|
| applePay | true 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/sessionHeaders
| Header | Valor | Obrigatório |
|---|---|---|
| Authorization | Bearer | Sim |
| Content-Type | application/json | Sim |
Body Parameters
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| validationURL | string | event.validationURL do onvalidatemerchant, sem alterar | Sim |
| domain | string | Host 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 ignorados | Sim |
Exemplo de Requisição
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
| Status | Mensagem | Causa |
|---|---|---|
| 400 | validationURL inválida | A URL não é https ou o host não é um gateway oficial do Apple Pay. Envie exatamente o event.validationURL |
| 400 | Domínio não habilitado para Apple Pay | O domain não está cadastrado para as suas credenciais (ou é inválido) |
| 422 | Apple Pay não habilitado para esta conta | Sua 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 |
| 422 | Apple Pay indisponível | O certificado de identidade da DiviPay está ausente ou vencido. Fale com a DiviPay |
| 502 | Não foi possível iniciar o Apple Pay | A 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
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| applePay | object | Pagamento com a carteira Apple Pay | Sim |
| applePay.paymentData | object | event.payment.token.paymentData do onpaymentauthorized, como objeto JSON, sem alterar | Sim |
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
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
| Status | Mensagem | Causa |
|---|---|---|
| 400 | card.applePay.paymentData não é um paymentData válido do Apple Pay | O 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 |
| 400 | Envie applePay sem outros dados de cartão | applePay veio junto com cardNumber, cardToken ou encryptedCard |
| 400 | paymentData do Apple Pay inválido | O token passou pela validação do corpo, mas está fora do formato esperado |
| 400 | Apple Pay aceita só pagamento à vista | installments maior que 1, quando o parcelamento no Apple Pay não estiver habilitado |
| 400 | IP não informado ou IP interno não permitido | client.ip ausente, ou é um IP interno. Envie o IP público do pagador |
| 422 | Apple Pay não habilitado para esta conta | A sua conta não tem Apple Pay (recurso desligado, provedor que não é PagBank, ou sem Merchant ID com certificado válido) |
| 422 | Merchant ID não cadastrado nesta conta | O 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 |
| 412 | Pagamento 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
- Use o ambiente Sandbox (
https://pay-sandbox.hge.app) com as credenciais de sandbox. - 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.
- Publique o arquivo de verificação do sandbox no domínio de homologação, no mesmo caminho
/.well-known/. - 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.

