Skip to main content
O Apple Pay permite que o cliente pague com um cartão que já está na Wallet do iPhone, do iPad ou do Mac, sem digitar número, validade ou CVV. Na Finvia, a integração é pass-through: o token cifrado gerado pelo dispositivo do cliente vem para a Finvia e é repassado ao processador, que mantém a relação com a Apple e faz a decifragem. Por isso, você não precisa de conta no Apple Developer Program, de Merchant ID nem de certificados.
Para o negócio: o Apple Pay é uma forma de pagamento com cartão de crédito. A venda segue as regras do cartão (parcelamento, estorno, webhooks) e aparece como cobrança de cartão. Ela só aceita reais (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.
1

Registre o domínio (backend, chave secreta)

Seu backend chama 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).
2

Hospede o arquivo de verificação

Você publica o conteúdo do arquivo em /.well-known/apple-developer-merchantid-domain-association no seu domínio.
3

Valide o domínio (backend, chave secreta)

Seu backend chama POST /v1/apple-pay/domains/{id}/validate. O processador confere o arquivo e o domínio passa a verified.
4

Valide a sessão a cada compra (navegador, chave pública)

Quando o cliente toca no botão, o Apple Pay JS dispara onvalidatemerchant. O navegador chama POST /v1/apple-pay/validate-merchant com a chave pública e devolve à Apple a sessão recebida, sem alterar.
5

O cliente autoriza o pagamento

O cliente confirma com Face ID, Touch ID ou no iPhone. O Apple Pay JS entrega o payment.token no evento onpaymentauthorized.
6

Crie a cobrança (backend, chave secreta)

O navegador envia o token ao seu backend, que chama POST /v1/charges com o token em paymentMethod.wallet. A Finvia repassa o token ao processador e devolve paid ou refused.
As rotas estão na Referência: registrar, listar, consultar e validar domínio, e validar sessão.
Para o negócio: registrar o primeiro domínio é o passo que liga o Apple Pay na sua integração. A partir dele, a conta passa a usar o modelo em que a sessão é validada pela Finvia (validate-merchant).

Pré-requisitos

É o SDK da Apple que leva o Apple Pay para fora do Safari. Um botão feito só com CSS funciona apenas no WebKit (Safari e navegadores do iOS).

Onde o botão aparece

A integração é a mesma em todos esses casos: o 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.
Cada hostname é um registro próprio: 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

O registro do primeiro domínio muda o modelo de Apple Pay da sua conta para pass-through no mesmo instante. Se você já operava com certificado próprio, siga a ordem da seção “Migração”, no fim desta página, antes de registrar.

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.
Resposta 201 Created:
Para o desenvolvedor: o domain é só o hostname, com até 255 caracteres. Sem https://, sem porta, sem caminho e sem IP. Se vier com algum desses, a API responde 400 com APPLE_PAY_INVALID_DOMAIN. O valor é gravado em minúsculas. Envie só o campo domain no corpo.
Registrar de novo é seguro. Registrar o mesmo hostname na mesma conta é idempotente: a API devolve o registro que já existe, também com 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óprio status e 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 status que 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 de verificationFile.content neste endereço:
Requisitos:
  • Caminho sem extensão (não é .txt).
  • Content-Type: text/plain.
  • HTTPS válido, resposta 200, sem redirect (nem HTTP para HTTPS, nem para www).
  • Acesso público, sem autenticação.
Confira antes de validar:

Etapa 3: validar o domínio

A resposta é o mesmo objeto da Etapa 1, com 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:
O domínio está pronto quando 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 evento onvalidatemerchant, 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.
Regras do Safari: avalie 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.
Modo Teste: uma chave 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.
Para o desenvolvedor: a chave pública pode ficar no código do navegador, porque ela só é aceita nas rotas que pedem por ela. A chave secreta nunca vai para o front-end. O label mostrado na folha do Apple Pay vem de total.label.

Etapa 5: criar a cobrança

Envie o objeto payment.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.
Exemplo do lado do backend, recebendo o token do navegador:
Node.js
A Finvia não decifra o conteúdo de 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

Configure 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

Não. No modelo pass-through, a relação com a Apple é do processador. Você só registra e verifica o domínio pela API da Finvia.
Sim. A chave pública (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.
Sim, se o botão aparecer nos dois. Cada hostname é um registro próprio e precisa ser verificado.
O campo installments é obrigatório na cobrança com Apple Pay, com a mesma regra do cartão digitado: um inteiro de 1 a 12.
Com a chave 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/domains com status: "verified") e sessão validada pelo POST /v1/apple-pay/validate-merchant sem 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 4444333322221112 em 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 refunded e charge.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

Continuam iguais: as chaves 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.
1

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.
2

Deixe a rota do arquivo pronta

Prepare a rota que vai servir /.well-known/apple-developer-merchantid-domain-association em text/plain, sem redirect. O conteúdo vem no passo seguinte.
3

Registre cada hostname

Registre cada hostname onde o botão aparece (Etapa 1). Guarde id e verificationFile.content.
4

Hospede e valide

Hospede o arquivo (Etapa 2) e valide cada domínio até verified (Etapa 3).
5

Publique e teste

Publique o novo frontend e faça uma compra real de valor baixo.
Para voltar ao modelo anterior depois da virada, fale com o suporte. Se você também vende pelo link de pagamento da Finvia, não há nada a fazer nele.

Veja também

Criar uma cobrança

Campos do objeto wallet.

Cartão de crédito

Regras de cartão que valem para o Apple Pay.

Apple Pay on the Web

Documentação da Apple sobre o Apple Pay JS.

Diretrizes de interface do Apple Pay

Como exibir o botão.