Visão Geral
Com o Apple Pay, o usuário paga com os cartões já cadastrados na Wallet do iPhone, iPad, Mac ou Apple Watch, com autenticação por Face ID/Touch ID — sem digitar número de cartão. O seu app ou site recebe do iOS/Safari um token de pagamento criptografado (PKPaymentToken) e o envia para a API da UvviPay, que faz a decriptação e o processamento.
Não há tarifa adicional para processar Apple Pay: a precificação é a mesma das demais transações com cartão de crédito da sua conta. Funciona em apps a partir do iOS 10 e na web com Safari (iOS 10+/macOS Sierra+) — consulte os dispositivos compatíveis e os bancos participantes na documentação da Apple.
Seu sistema nunca vê os dados do cartão. O token do Apple Pay é cifrado pela Apple diretamente para a UvviPay — o número do cartão não passa pelo seu código nem pelos seus servidores, o que reduz drasticamente o seu escopo PCI.
Propriedades da forma de pagamento
Suporte de produto
- Link de Pagamento — o Apple Pay já aparece automaticamente no checkout dos seus links de pagamento, sem nenhuma configuração (sujeito à habilitação do método para a sua conta).
- API de Pagamentos — integração própria no seu app iOS ou site, descrita neste guia.
Aceitar Apple Pay
A configuração depende de onde o botão vai aparecer — escolha o caminho:App iOS
Merchant ID próprio + certificado via CSR da UvviPay + capability no Xcode. Três etapas, uma única vez por app.
Site (web)
Sem conta Apple Developer: registre seus domínios pela API e hospede o arquivo de verificação. O botão roda no Safari com Apple Pay JS.
Configuração — App iOS
A configuração é feita uma única vez por app e envolve três etapas — as duas primeiras no Apple Developer Portal, a terceira no Xcode.1
Registre um Apple Merchant ID
No Apple Developer Portal, acesse Certificates, Identifiers & Profiles → Identifiers → Merchant IDs e crie um novo Merchant ID para o seu app.
- Description: o nome do seu negócio (ex.:
Minha Empresa LTDA) - Identifier: um identificador único no formato reverso do seu domínio, prefixado com
merchant.(ex.:merchant.com.minhaempresa.app)
2
Crie o certificado de processamento com o CSR da UvviPay
O Payment Processing Certificate é o que permite à UvviPay decriptar os tokens do Apple Pay do seu app. A chave privada desse certificado fica sob custódia da UvviPay — por isso o CSR (Certificate Signing Request) deve ser o emitido pela nossa API, e não um gerado por você. Todo o ciclo é self-service:
-
Emita o CSR pelo
POST /v1/certificatese salve o camposigningRequestPemcomo um arquivo.csr:Emitir CSR -
No Apple Developer Portal, abra o seu Merchant ID e, em Apple Pay Payment Processing Certificate, clique em Create Certificate e envie o
.csr. -
Baixe o certificado emitido pela Apple (
apple_pay.cer) e ative-o peloPOST /v1/certificates/{id}/activate, enviando o arquivo em base64:Ativar certificado
active, ele já vale para as transações — sem contato com o suporte. Acompanhe seus certificados (status, validade) pelo GET /v1/certificates.Nenhuma chave ou segredo trafega nesse processo: o CSR e o
.cer são material público. A chave privada nasce e permanece na UvviPay.3
Habilite o Apple Pay no Xcode
No Xcode, abra o target do seu app em Signing & Capabilities, adicione a capability Apple Pay e marque o Merchant ID criado na etapa 1.Com isso o
PKPaymentRequest do seu app já pode usar o seu merchantIdentifier.Configuração — Web
Para exibir o botão Apple Pay no seu site você não precisa de conta Apple Developer nem de Merchant ID próprio: a validação da sessão é feita pela UvviPay. O único requisito é registrar cada domínio onde o botão será exibido. O uso do Apple Pay na web está sujeito às diretrizes de uso aceitável da Apple para sites.A verificação automática de domínios está em fase de habilitação junto à Apple. Se o
validate responder 503, os passos de registro e hospedagem do arquivo permanecem os mesmos — acione o suporte da UvviPay, que conclui a verificação por você.1
Registre seus domínios pela API
Registre cada domínio onde o botão Apple Pay aparecerá com o O domínio é criado com status
POST /v1/payment-method-domains:Registrar domínio
pending, e a resposta já traz o arquivo de verificação que você precisa hospedar (campo verificationFile: caminho exato + conteúdo). Regras de registro:- Registre o domínio exatamente como o usuário o acessa:
www.exemplo.com.breexemplo.com.brcontam como domínios distintos (wwwé um subdomínio). - Cada subdomínio precisa ser registrado individualmente (ex.:
checkout.exemplo.com.br). - Inclua também os domínios de homologação, se quiser testar antes de ir à produção.
GET /v1/payment-method-domains.O registro é idempotente: re-registrar um domínio já cadastrado devolve o registro existente, sem duplicar.
2
Hospede o arquivo de verificação de domínio
Salve o Requisitos para a verificação da Apple funcionar:
verificationFile.content da resposta anterior, em texto puro, no caminho indicado:Caminho do arquivo
- Servido por HTTPS com certificado válido, sem redirecionamentos
- Acessível publicamente (sem autenticação, sem bloqueio por WAF/geolocalização)
- Content-Type de texto simples
3
Dispare a verificação
Com o arquivo no ar, chame o Registramos o domínio junto à Apple na hora — os servidores da Apple buscam o arquivo de verificação no seu domínio durante a chamada. Resposta
POST /v1/payment-method-domains/{id}/validate:Verificar domínio
200 com status verified significa domínio verificado de fato. Em caso de falha, o motivo vem no erro e fica registrado em lastVerificationError — corrija a hospedagem do arquivo e chame novamente.Fluxo no frontend
Com o domínio verificado, o fluxo no seu site usa a Apple Pay JS API em duas chamadas à UvviPay — sempre intermediadas pelo seu backend, que é quem guarda as credenciais:onvalidatemerchant: repasse ovalidationURL(fornecido pelo Safari) ao seu backend, que chama oPOST /v1/payments/apple-pay/validate-merchante devolve o merchant session aoApplePaySession. A validação só é aceita para domíniosverified.onpaymentauthorized: envie opayment.token.paymentData(em base64) no campoapplePayda requisição de pagamento — ver Processando o Pagamento.
Considerações da integração web
- HTTPS obrigatório em todas as páginas que exibem o botão — inclusive em homologação.
- Gesto do usuário: a Apple exige que o
ApplePaySessionseja criado por uma ação do usuário (clique/toque no botão). Chamesession.begin()diretamente no handler do gesto, antes de qualquer código assíncrono ou demorado — invocação automática ou tardia é bloqueada pelo Safari. Pelo mesmo motivo, mantenha curto o intervalo entre o gesto e a confirmação do pagamento (busque preços, frete e totais antes de exibir o botão, não depois do clique). - Disponibilidade: o Apple Pay na web funciona no Safari (macOS/iOS) e em navegadores no iOS 16+. Exiba o botão apenas quando
window.ApplePaySession?.canMakePayments()for verdadeiro. - Iframes: se o checkout roda em um iframe, o Safari 17+ exige o atributo
allow="payment"e que ambos os domínios (página e iframe) estejam registrados. - Domínio exibido = domínio registrado: o hostname enviado na validação deve ser exatamente o da página onde o botão está — domínios não registrados são recusados.
- Aparência do botão: siga as diretrizes da Apple para botões Apple Pay (marca, dimensões e variações claro/escuro).
Processando o Pagamento
Tanto no app quanto na web, ao receber a autorização do usuário envie opaymentData do token (em base64) no campo applePay do POST /v1/payments — no lugar do bloco card:
O campo
applePay.network deve vir de paymentMethod.network do token — a bandeira é informada pela Apple, já que o número tokenizado (DPAN) não passa por validação de BIN convencional.Testando
- Use um cartão real. Não é possível salvar cartões de teste comuns na Wallet — a Apple só provisiona cartões emitidos por bancos participantes. Valide o fluxo com uma transação de valor baixo e estorne em seguida (
PUT /v1/payments/{id}/refund). - Sandbox da Apple: para testar sem cartão real, a Apple oferece o ambiente de sandbox com cartões de teste provisionáveis em contas sandbox — útil para validar a integração do app/site, mas a autorização financeira de ponta a ponta só acontece com cartão real.
- Web: se o botão não aparece, verifique na ordem: dispositivo/navegador compatível,
canMakePayments(), domínioverifiednoGET /v1/payment-method-domainse o arquivo de associação no ar.
Boas Práticas
- Chame a API pelo seu backend. O
paymentDatadeve ser encaminhado do app/site para o seu servidor e de lá para a UvviPay —client-id/client-secretnunca devem ser embarcados no app nem expostos no front-end. - Envie logo após a autorização. O token do Apple Pay tem janela de validade curta; não o armazene para uso posterior.
- Trate o resultado na tela de pagamento (payment sheet). Retorne sucesso ou falha (
PKPaymentAuthorizationResult/session.completePayment) conforme a resposta da API, para o usuário ver o estado correto na animação do Apple Pay. - Verifique a disponibilidade. No iOS, use
canMakePayments(usingNetworks:); na web,ApplePaySession.canMakePayments()— e só então exiba o botão. - Use o botão oficial. No iOS,
PKPaymentButton; na web, os estilos das Human Interface Guidelines.
Erros Comuns
Veja também
- Criar pagamento — referência completa do
POST /v1/payments - Registrar domínio e Listar domínios
- Emitir CSR, Ativar e Listar certificados
- Validar sessão Apple Pay (web)
- Recusas de cartão — como interpretar os motivos de recusa
- Webhooks — notificações de status do pagamento
- Human Interface Guidelines — Apple Pay — diretrizes oficiais do botão e da experiência

