Skip to main content

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

Recorrência: por enquanto o Apple Pay está disponível apenas para pagamentos avulsos. Cobranças recorrentes com Apple Pay ainda não são suportadas.

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

Elegibilidade na App Store: a Apple só permite Apple Pay dentro de apps para bens físicos e serviços consumidos fora do app (delivery, transporte, ingressos, e-commerce, pagamento de contas etc.). Conteúdo digital, funcionalidades do app e assinaturas de conteúdo devem usar In-App Purchase, conforme a regra 3.1.1 das App Review Guidelines. Confirme o enquadramento do seu produto antes de integrar.
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)
Guarde esse identificador — ele será usado nas etapas seguintes.
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:
  1. Emita o CSR pelo POST /v1/certificates e salve o campo signingRequestPem como um arquivo .csr:
    Emitir CSR
  2. No Apple Developer Portal, abra o seu Merchant ID e, em Apple Pay Payment Processing Certificate, clique em Create Certificate e envie o .csr.
  3. Baixe o certificado emitido pela Apple (apple_pay.cer) e ative-o pelo POST /v1/certificates/{id}/activate, enviando o arquivo em base64:
    Ativar certificado
A ativação valida na hora que o certificado corresponde ao CSR emitido; com status 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.
Cada CSR emite exatamente um certificado na Apple. Para trocar de certificado (rotação, revogação ou mudança de Merchant ID), emita um novo CSR pelo mesmo endpoint. Não use certificados criados a partir de CSRs próprios — a ativação os rejeita, e tokens gerados com eles não podem ser decriptados.
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 POST /v1/payment-method-domains:
Registrar domínio
O domínio é criado com status 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.br e exemplo.com.br contam 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.
Consulte seus domínios e os respectivos status a qualquer momento com 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 verificationFile.content da resposta anterior, em texto puro, no caminho indicado:
Caminho do arquivo
Requisitos para a verificação da Apple funcionar:
  • 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
Mantenha o arquivo hospedado permanentemente. A Apple revalida os domínios periodicamente — se o arquivo sair do ar, o Apple Pay para de funcionar no seu site.
3

Dispare a verificação

Com o arquivo no ar, chame o POST /v1/payment-method-domains/{id}/validate:
Verificar domínio
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 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:
  1. onvalidatemerchant: repasse o validationURL (fornecido pelo Safari) ao seu backend, que chama o POST /v1/payments/apple-pay/validate-merchant e devolve o merchant session ao ApplePaySession. A validação só é aceita para domínios verified.
  2. onpaymentauthorized: envie o payment.token.paymentData (em base64) no campo applePay da 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 ApplePaySession seja criado por uma ação do usuário (clique/toque no botão). Chame session.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 o paymentData 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.
Envie card ou applePay, nunca os dois na mesma requisição. Com applePay, o próprio token faz o papel de credencial e de autenticação: CVV e 3DS são dispensados.

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ínio verified no GET /v1/payment-method-domains e o arquivo de associação no ar.

Boas Práticas

  • Chame a API pelo seu backend. O paymentData deve ser encaminhado do app/site para o seu servidor e de lá para a UvviPay — client-id/client-secret nunca 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