Apple Pay

​

Visão geral

​

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). O botão funciona em Safari, Chrome, Edge e Firefox, inclusive em domínio personalizado (white-label).
• API de Pagamentos: integração própria no seu app iOS ou site, descrita neste guia.

​

Aceitar Apple Pay

​

Configuração no app iOS

curl -X POST https://api.uvvipay.com.br/v1/certificates \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "type": "apple_pay_payment_processing" }'

{
  "id": "e279effc-8ce9-4ccd-878f-7d7867edab59",
  "type": "apple_pay_payment_processing",
  "status": "issued",
  "signingRequestPem": "-----BEGIN CERTIFICATE REQUEST-----\nMIHi...\n-----END CERTIFICATE REQUEST-----\n",
  "publicKeyFingerprint": "V4Y/pw2fZ2RYKD0kvWpq4ixRRvgQw0Up9g2b6DqjfBo="
}

curl -s -X POST https://api.uvvipay.com.br/v1/certificates \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "type": "apple_pay_payment_processing" }' \
  | jq -r '.signingRequestPem' > apple-pay.csr

curl -X POST https://api.uvvipay.com.br/v1/certificates/e279effc-8ce9-4ccd-878f-7d7867edab59/activate \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d "{ \"certificate\": \"$(base64 -i apple_pay.cer | tr -d '\n')\" }"

base64 -i apple_pay.cer | tr -d '\n' | pbcopy

{ "certificate": "MIIEcDCCBBWgAwIBAgIIH..." }

openssl x509 -inform DER -in apple_pay.cer -noout -pubkey \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -binary | base64
# esperado: o mesmo valor de publicKeyFingerprint

​

Status do certificado

​

Rotacionar ou substituir o certificado

1. Emita um novo CSR (etapa 2).
2. Crie o novo certificado no portal da Apple com esse CSR (etapa 3). Não revogue o antigo ainda.
3. Ative o novo certificado na UvviPay (etapa 4).
4. Faça 1 pagamento de teste no app e confirme a aprovação.
5. Revogue o certificado antigo na UvviPay pelo POST /v1/certificates/{id}/revoke.
6. Revogue o certificado antigo no portal da Apple, na seção Apple Pay Payment Processing Certificate do Merchant ID.

​

Configuração na web

1. Registrar o domínio na UvviPay e hospedar 1 arquivo de verificação.
2. Confirmar a verificação do domínio.
3. Criar 1 endpoint no seu backend para validar a sessão.
4. Carregar o Apple Pay JS SDK na página do checkout.
5. Montar o botão no frontend com a Apple Pay JS API.

​

Navegadores compatíveis

​

Quem fala com quem

​

Passo a passo do registro

curl -X POST https://api.uvvipay.com.br/v1/payment-method-domains \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "domainName": "checkout.minhaloja.com.br" }'

{
  "id": "527e04aa-43bc-4c68-9fa3-49fc0b3cae34",
  "domainName": "checkout.minhaloja.com.br",
  "status": "pending",
  "verifiedAt": null,
  "lastVerificationError": null,
  "createdAt": "2026-09-10T12:00:00.000Z",
  "verificationFile": {
    "path": "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association",
    "content": "7B227073704964223A2238334635..."
  }
}

https://SEU_DOMINIO/.well-known/apple-developer-merchantid-domain-association

// 1. Salve o conteúdo em public/.well-known/apple-developer-merchantid-domain-association
// 2. Force text/plain no header (o arquivo não tem extensão)
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: "/.well-known/apple-developer-merchantid-domain-association",
        headers: [{ key: "Content-Type", value: "text/plain" }],
      },
    ];
  },
};

export default nextConfig;

# Arquivo salvo em /var/www/apple-pay/apple-developer-merchantid-domain-association
location = /.well-known/apple-developer-merchantid-domain-association {
  alias /var/www/apple-pay/apple-developer-merchantid-domain-association;
  default_type text/plain;
  add_header Cache-Control "no-cache";
}

// Conteúdo salvo em variável de ambiente ou em arquivo versionado
const APPLE_PAY_DOMAIN_ASSOCIATION = process.env.APPLE_PAY_DOMAIN_ASSOCIATION;

app.get("/.well-known/apple-developer-merchantid-domain-association", (req, res) => {
  res.type("text/plain").send(APPLE_PAY_DOMAIN_ASSOCIATION);
});

curl -sS -D - https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association

curl -X POST https://api.uvvipay.com.br/v1/payment-method-domains/527e04aa-43bc-4c68-9fa3-49fc0b3cae34/validate \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET"

{
  "id": "527e04aa-43bc-4c68-9fa3-49fc0b3cae34",
  "domainName": "checkout.minhaloja.com.br",
  "status": "verified",
  "verifiedAt": "2026-09-10T12:05:31.000Z",
  "lastVerificationError": null,
  "createdAt": "2026-09-10T12:00:00.000Z"
}

curl -X DELETE https://api.uvvipay.com.br/v1/payment-method-domains/527e04aa-43bc-4c68-9fa3-49fc0b3cae34 \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET"

​

Criar o endpoint de validação no seu backend

curl -X POST https://api.uvvipay.com.br/v1/payments/apple-pay/validate-merchant \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain": "checkout.minhaloja.com.br"
  }'

app.post("/api/apple-pay/validate-merchant", requireUserSession, async (req, res) => {
  const { validationUrl, domain } = req.body;

  const response = await fetch(
    "https://api.uvvipay.com.br/v1/payments/apple-pay/validate-merchant",
    {
      method: "POST",
      headers: {
        "client-id": process.env.UVVIPAY_CLIENT_ID,
        "client-secret": process.env.UVVIPAY_CLIENT_SECRET,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ validationUrl, domain }),
    }
  );

  const body = await response.json();

  // 400 = domínio não registrado ou não verificado (a mensagem diz qual)
  // 503 = Apple indisponível no momento
  if (!response.ok) {
    return res.status(response.status).json({ message: body.message });
  }

  // Devolva a merchant session sem transformar
  return res.json(body);
});

​

Carregar o Apple Pay JS SDK

<script
  crossorigin
  src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"
></script>

• Use a versão 1.latest ou fixe uma versão igual ou superior a 1.2.0. Versões anteriores não abrem o modal com código.
• Avalie window.ApplePaySession e canMakePayments() depois do evento load do script. Antes disso, fora do Safari, window.ApplePaySession é undefined.
• Se o script falhar (rede, bloqueio de CSP), não exiba o botão.
• Renderize o botão com o web component <apple-pay-button>. O botão em CSS só funciona no Safari.

script-src  applepay.cdn-apple.com
connect-src smp-paymentservices.apple.com

const APPLE_PAY_SDK_URL =
  "https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js";

let sdkPromise = null;

export function loadApplePaySdk() {
  if (sdkPromise) return sdkPromise;

  sdkPromise = new Promise((resolve, reject) => {
    const script = document.createElement("script");
    script.src = APPLE_PAY_SDK_URL;
    script.async = true;
    script.crossOrigin = "anonymous";
    script.onload = () => resolve();
    script.onerror = () => {
      sdkPromise = null; // libera nova tentativa
      script.remove();
      reject(new Error("Falha ao carregar o Apple Pay JS SDK"));
    };
    document.head.appendChild(script);
  });

  return sdkPromise;
}

​

Fluxo no frontend

<!-- Web component registrado pelo SDK. Renderiza igual em todos os navegadores -->
<apple-pay-button
  id="apple-pay-button"
  buttonstyle="black"
  type="pay"
  locale="pt-BR"
  hidden
></apple-pay-button>

// [0] Só avalie a disponibilidade depois do SDK carregar
window.addEventListener("load", () => {
  const applePayAvailable =
    window.ApplePaySession?.canMakePayments() === true;
  if (!applePayAvailable) return;

  const button = document.getElementById("apple-pay-button");
  button.hidden = false;
  // O <apple-pay-button> chama stopPropagation() no clique.
  // Registre o listener no próprio elemento, não em um ancestral.
  button.addEventListener("click", onApplePayButtonClick);
});

function onApplePayButtonClick() {
  const session = new ApplePaySession(3, {
    countryCode: "BR",
    currencyCode: "BRL",
    supportedNetworks: ["visa", "masterCard"],
    merchantCapabilities: ["supports3DS"],
    total: { label: "Minha Loja", amount: "75.00" }, // string com 2 decimais
  });

  session.onvalidatemerchant = async (event) => {
    try {
      const res = await fetch("/api/apple-pay/validate-merchant", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          validationUrl: event.validationURL,
          domain: window.location.hostname,
        }),
      });
      if (!res.ok) throw new Error((await res.json()).message);
      session.completeMerchantValidation(await res.json());
    } catch (error) {
      // [2] Sem abort a folha do Apple Pay fica aberta em "Processando"
      session.abort();
      mostrarErro(error.message);
    }
  };

  session.onpaymentauthorized = async (event) => {
    // [3] paymentData = base64 do JSON de token.paymentData (não do token inteiro)
    const paymentData = btoa(JSON.stringify(event.payment.token.paymentData));
    const network = event.payment.token.paymentMethod.network;

    // Seu backend chama POST /v1/payments com o bloco applePay
    const ok = await processarPagamento(paymentData, network);
    session.completePayment(
      ok ? ApplePaySession.STATUS_SUCCESS : ApplePaySession.STATUS_FAILURE
    );
  };

  // [1] begin() precisa rodar de forma síncrona dentro do handler do clique.
  // Qualquer await antes desta linha bloqueia a sessão.
  session.begin();
}

function ApplePayButton({ onClick }) {
  const ref = useRef(null);

  useEffect(() => {
    const element = ref.current;
    element.addEventListener("click", onClick);
    return () => element.removeEventListener("click", onClick);
  }, [onClick]);

  return (
    <apple-pay-button ref={ref} buttonstyle="black" type="pay" locale="pt-BR" />
  );
}

​

Considerações da integração web

• HTTPS obrigatório em todas as páginas com o botão, inclusive em homologação.
• Disponibilidade: com o SDK carregado, o Apple Pay funciona em Safari, Chrome, Edge e Firefox (ver Navegadores compatíveis). Fora do Safari, o cliente precisa de 1 iPhone com iOS 18 ou superior para escanear o código. Exiba o botão só quando window.ApplePaySession?.canMakePayments() for true, avaliado depois do load do SDK.
• Iframes: se o checkout roda em um iframe, o Safari 17+ exige o atributo allow="payment". Registre os 2 domínios: o da página e o do iframe.
• Domínio da página = domínio registrado: envie window.location.hostname sem alterar. Domínios não registrados recebem 400.
• Aparência do botão: use o web component <apple-pay-button> do SDK e siga as diretrizes da Apple para botões Apple Pay. O botão em CSS (-webkit-appearance: -apple-pay-button) só renderiza no Safari e no WebKit do iOS.
• CSP: libere applepay.cdn-apple.com em script-src e smp-paymentservices.apple.com em connect-src.

​

Testar o Apple Pay na web

1. Confirme status: verified no GET /v1/payment-method-domains.
2. Abra a página no Safari (macOS ou iOS) com 1 cartão real na Wallet.
3. Confirme que o botão aparece. Se não aparecer, confira canMakePayments() e o cadastro do cartão na Wallet.
4. Abra o Web Inspector na aba Network antes de clicar.
5. Clique no botão. A folha do Apple Pay abre em menos de 1 segundo.
6. Confira a chamada ao seu endpoint de validação: status 200 e corpo com a merchant session.
7. Autorize com Touch ID ou Face ID. Confira a chamada de pagamento ao seu backend.
8. Confira o pagamento no painel ou no GET /v1/payments/{id}.
9. Estorne o pagamento de teste pelo PUT /v1/payments/{id}/refund.

1. Tenha em mãos 1 iPhone com iOS 18 ou superior e 1 cartão real na Wallet.
2. Abra a página e o DevTools na aba Network. Confirme o download de apple-pay-sdk.js com status 200.
3. Confirme que o botão <apple-pay-button> aparece. Se não aparecer, execute window.ApplePaySession?.canMakePayments() no console. O esperado é true.
4. Clique no botão. O navegador abre um modal da Apple com 1 código.
5. Escaneie o código com a câmera do iPhone. O iPhone abre a folha do Apple Pay.
6. Autorize com Face ID ou Touch ID no iPhone. O modal do navegador fecha sozinho.
7. Confira a chamada de pagamento ao seu backend e o pagamento no GET /v1/payments/{id}.
8. Estorne o pagamento de teste.

​

Processando o pagamento

import PassKit

let request = PKPaymentRequest()
request.merchantIdentifier = "merchant.com.minhaempresa.app"
request.supportedNetworks = [.visa, .masterCard]
request.merchantCapabilities = .threeDSecure
request.countryCode = "BR"
request.currencyCode = "BRL"
request.paymentSummaryItems = [
  PKPaymentSummaryItem(label: "Minha Loja", amount: NSDecimalNumber(string: "75.00"))
]

// No callback de autorização:
func paymentAuthorizationController(
  _ controller: PKPaymentAuthorizationController,
  didAuthorizePayment payment: PKPayment,
  handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
) {
  let paymentData = payment.token.paymentData.base64EncodedString()
  let network = payment.token.paymentMethod.network?.rawValue ?? ""
  // Envie paymentData e network para o SEU backend, que chama a API da UvviPay
}

import { PaymentRequest } from "react-native-payments";

const paymentRequest = new PaymentRequest(
  [{
    supportedMethods: ["apple-pay"],
    data: {
      merchantIdentifier: "merchant.com.minhaempresa.app",
      supportedNetworks: ["visa", "mastercard"],
      countryCode: "BR",
      currencyCode: "BRL",
    },
  }],
  { total: { label: "Minha Loja", amount: { currency: "BRL", value: "75.00" } } }
);

const response = await paymentRequest.show();
// paymentData = conteúdo do PKPaymentToken.paymentData, em base64
const paymentData = base64Encode(JSON.stringify(response.details.paymentData));
const network = response.details.paymentMethod?.network;

// Envie ao SEU backend, que chama POST /v1/payments com o bloco applePay
await meuBackend.pagarComApplePay({ paymentData, network });
await response.complete("success");

curl -X POST https://api.uvvipay.com.br/v1/payments \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ORDER-12345",
    "amount": 7500,
    "paymentMethod": "credit_card",
    "applePay": {
      "paymentData": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiLi4uIn0=",
      "network": "Visa",
      "installments": 1
    },
    "customer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "document": { "type": "cpf", "number": "12345678900" }
    },
    "items": [
      { "title": "Pedido ORDER-12345", "quantity": 1, "unitPrice": 7500 }
    ]
  }'

​

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. Serve para validar a integração do app/site, mas a autorização financeira de ponta a ponta só acontece com cartão real.
• Web: siga o checklist em Testar o Apple Pay na web. Só domínio verified em HTTPS público funciona; localhost e previews não abrem a folha. Teste no Safari e em pelo menos 1 navegador de terceiros no desktop (fluxo com código no iPhone).

​

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() depois do load do SDK. Só então exiba o botão.
• Use o botão oficial. No iOS, PKPaymentButton; na web, o web component <apple-pay-button> do SDK, com os estilos das Human Interface Guidelines.

​

Erros comuns

​

Veja também

• Criar pagamento: referência completa do POST /v1/payments
• Registrar domínio, Listar domínios e Remover domínio
• 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 para Apple Pay: diretrizes oficiais do botão e da experiência
• Apple Pay JS SDK e botão <apple-pay-button>: documentação oficial do SDK usado em Chrome, Edge e Firefox