BRL), exige o CPF ou CNPJ do cliente e, neste modelo, aceita Visa e Mastercard (Elo em homologação pelo processador).Quando usar
Como funciona
A integração tem três partes: preparar o domínio (feito uma vez), validar a sessão a cada compra e criar a cobrança. O primeiro desenho mostra a preparação do domínio, feita uma vez por hostname: registrar, hospedar o arquivo e validar. O mesmo hostname registrado vale para produção e para o Modo Teste.www.loja.com e loja.com são registros diferentes.
O segundo desenho mostra o que acontece a cada compra, do toque no botão até a resposta da cobrança.
Só a validação da sessão sai do navegador, com a chave pública. A cobrança é sempre criada pelo seu backend, com a chave secreta.
Registre o domínio (backend, chave secreta)
POST /v1/apple-pay/domains com o hostname onde o botão aparece. A Finvia registra o domínio no processador e devolve o arquivo de verificação (verificationFile).Hospede o arquivo de verificação
/.well-known/apple-developer-merchantid-domain-association no seu domínio.Valide o domínio (backend, chave secreta)
POST /v1/apple-pay/domains/{id}/validate. O processador confere o arquivo e o domínio passa a verified.Valide a sessão a cada compra (navegador, chave pública)
onvalidatemerchant. O navegador chama POST /v1/apple-pay/validate-merchant com a chave pública e devolve à Apple a sessão recebida, sem alterar.O cliente autoriza o pagamento
payment.token no evento onpaymentauthorized.Crie a cobrança (backend, chave secreta)
POST /v1/charges com o token em paymentMethod.wallet. A Finvia repassa o token ao processador e devolve paid ou refused.validate-merchant).Pré-requisitos
Onde o botão aparece
onvalidatemerchant chama a mesma rota da Finvia e o token autorizado chega no mesmo formato. A única exigência é avaliar canMakePayments() depois do evento load do SDK, porque fora do Safari é o SDK que define ApplePaySession.
www.loja.com e loja.com são domínios diferentes. Registre exatamente o hostname que o navegador mostra em window.location.hostname.Regras de negócio
Passo a passo
Etapa 1: registrar o domínio
Chame a rota com a chave secreta. A resposta traz o arquivo de verificação que você vai hospedar.201 Created:
201, sem criar outro. Isso vale também quando a tentativa anterior falhou: o registro preservado no processador é reaproveitado. Se verificationFile.content vier null, o registro existe mas não há arquivo para hospedar. Nesse caso, não repita a chamada: fale com o suporte.
Domínio compartilhado por vários merchants
Plataformas de checkout que servem várias lojas em um mesmo hostname (por exemplo,checkout.plataforma.com) registram esse hostname uma vez para cada merchant, com a sk_ de cada um.
- Cada registro é independente: tem o próprio
id, o própriostatuse habilita o pass-through daquele merchant. - O arquivo de verificação é o mesmo para todos os registros da conta, então basta hospedá-lo uma vez por hostname. Os registros seguintes já nascem com o
statusque o hostname tem. - Lojas com domínio próprio registram também o domínio próprio. O navegador sempre envia o hostname real da página no validate-merchant.
Etapa 2: hospedar o arquivo de verificação
Sirva o valor deverificationFile.content neste endereço:
- Caminho sem extensão (não é
.txt). Content-Type: text/plain.- HTTPS válido, resposta
200, sem redirect (nem HTTP para HTTPS, nem parawww). - Acesso público, sem autenticação.
- Node.js (Express)
- Nginx
Etapa 3: validar o domínio
status: "verified" e verifiedAt preenchido.
Se o arquivo não estiver acessível, a API responde 422 com o código APPLE_PAY_DOMAIN_VERIFICATION_FAILED. O domínio passa a status: "failed" e o motivo fica em lastVerificationError. Corrija a hospedagem e chame de novo.
Para consultar a qualquer momento:
GET /v1/apple-pay/domains mostra status: "verified" para o hostname exato da página do checkout.Etapa 4: validar a sessão no navegador
No eventoonvalidatemerchant, envie à Finvia a validationURL recebida da Apple e o hostname da página, autenticando com a chave pública. Devolva a sessão à Apple sem modificar.
ApplePaySession.canMakePayments() depois do evento load do SDK, registre o clique diretamente no elemento <apple-pay-button> e chame session.begin() sem nenhum await antes.pk_test_ valida a sessão no provedor real (a folha do Safari só abre com sessão real), mas a cobrança correspondente cai no processador de teste e nenhum valor é movimentado. O limite de validações é de 20 tentativas por IP a cada 5 minutos, além de um teto global da plataforma.Etapa 5: criar a cobrança
Envie o objetopayment.token na íntegra em paymentMethod.wallet, pela rota padrão POST /v1/charges. A cobrança é criada pelo seu backend, com a chave secreta. Com wallet presente, os campos do cartão (number, holderName, expirationMonth, expirationYear, cvv) não são necessários; installments continua obrigatório.
paymentData: ele é repassado ao processador exatamente como veio. Só a versão EC_v1 do token é aceita, e o pass-through opera apenas em BRL. O 3D Secure não se aplica ao Apple Pay, porque a autenticação já está embutida no token.
A resposta tem o mesmo formato de qualquer cobrança com cartão (id, status, paymentDetails, reason), e o pós-venda (webhooks, estorno, chargeback) segue as regras do cartão de crédito.
Redes suportadas
supportedNetworks no ApplePaySession apenas com as redes suportadas (['visa', 'masterCard']), para o cliente não autorizar um pagamento que será recusado.
Códigos de erro
Erros comuns
Perguntas frequentes
Preciso de conta Apple Developer ou de certificado?
Preciso de conta Apple Developer ou de certificado?
Posso usar a chave pública no código do site?
Posso usar a chave pública no código do site?
pk_) foi feita para o navegador e é usada só no validate-merchant. A cobrança é criada pelo seu backend com a chave secreta, que nunca vai para o front-end.Tenho www.minhaloja.com.br e minhaloja.com.br. Registro os dois?
Tenho www.minhaloja.com.br e minhaloja.com.br. Registro os dois?
Apple Pay aceita parcelamento?
Apple Pay aceita parcelamento?
installments é obrigatório na cobrança com Apple Pay, com a mesma regra do cartão digitado: um inteiro de 1 a 12.Como testo o Apple Pay?
Como testo o Apple Pay?
pk_test_, a sessão é validada no provedor real (o botão precisa abrir no Safari) e a cobrança feita com a sk_test_ cai no processador de teste, sem movimentar valor. No sandbox, a cobrança Apple Pay não tem um número de cartão controlável e, na prática, sai aprovada: não há como forçar uma recusa com o token da Apple. Para testar o tratamento de recusa, use uma cobrança de cartão digitado com o cartão 4444333322221112.Como testar
Execute a seção “Apple Pay” do roteiro de homologação:- AP-01: obter o token de pagamento no front (Apple Pay JS).
- AP-02: cobrança Apple Pay aprovada, com
paid. - AP-03: domínio registrado e verificado (
GET /v1/apple-pay/domainscomstatus: "verified") e sessão validada peloPOST /v1/apple-pay/validate-merchantsem erro. - AP-04: recusa. No sandbox, o token da Apple não permite forçar uma recusa. Demonstre o tratamento de recusa com o cartão
4444333322221112em uma cobrança de cartão digitado, ou registre o cenário como não aplicável no sandbox. - AP-05: estorno de uma cobrança Apple Pay paga, com
refundedecharge.refunded. - AP-06: recebimento do webhook
charge.paid.
Migração: quem já operava com certificado próprio
Esta seção é para quem integrou pelo modelo anterior: conta no Apple Developer Program, Merchant ID próprio, domínio verificado no portal da Apple, Merchant Identity Certificate no seu backend e Payment Processing Certificate entregue à Finvia, que decifrava o token. Esse modelo continua disponível, mas novas integrações e contas migradas usam o fluxo pass-through desta página.O que muda
sk_ e pk_, o parcelamento, os webhooks de cobrança (com three_ds nulo e a possibilidade do status in_analysis) e o rótulo da folha de pagamento, que vem do total.label do seu ApplePaySession.
Ordem da virada
O registro do primeiro domínio coloca a conta no modelo pass-through no mesmo instante. A partir dele, um token gerado pelo seu Merchant ID antigo é recusado pelo processador. Por isso, prepare tudo antes e faça os passos 3 a 5 na mesma janela.Prepare o novo frontend, sem publicar
onvalidatemerchant da Etapa 4, supportedNetworks: ['visa', 'masterCard'], currencyCode: 'BRL', coleta de CPF/CNPJ antes da folha de pagamento e customer.document na cobrança.Deixe a rota do arquivo pronta
/.well-known/apple-developer-merchantid-domain-association em text/plain, sem redirect. O conteúdo vem no passo seguinte.Registre cada hostname
id e verificationFile.content.Hospede e valide
verified (Etapa 3).Publique e teste
Veja também
Criar uma cobrança
wallet.
