> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Pay

> Aceite Apple Pay no seu site sem conta Apple Developer: registre o domínio, valide a sessão no navegador e envie o token na cobrança.

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.

> [!NOTE]
>
> **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

| Situação | Recomendação |
| - | - |
| Checkout web com público que usa iPhone, iPad ou Mac | Ofereça o botão Apple Pay ao lado do cartão e do Pix |
| Venda em reais para clientes no Brasil | Apple Pay atende |
| Venda em outra moeda | Use cartão digitado. O Apple Pay pass-through só aceita `BRL` |
| Cliente com Android | O botão não aparece. Ofereça cartão ou Pix |
| A sua conta já operava Apple Pay com certificado próprio | Leia a seção "Migração", no fim desta página, antes de registrar qualquer domínio |

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

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
sequenceDiagram
    autonumber
    box rgb(243,245,248) Sua aplicação
        participant L as Seu backend (sk_)
        participant D as Seu site (o domínio)
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant P as Processador
    end
    L->>F: POST /v1/apple-pay/domains · domain (só o hostname)
    F->>P: Registra o domínio
    F-->>L: 201 · id · status pending · verificationFile
    Note over L,P: O primeiro domínio registrado já liga o modelo pass-through na conta
    L->>D: Publica verificationFile.content no caminho /.well-known/ indicado
    L->>F: POST /v1/apple-pay/domains/{id}/validate
    F->>P: Pede a conferência do arquivo
    P->>D: Lê o arquivo (HTTPS, 200, text/plain, sem redirect)
    alt Arquivo correto
        F-->>L: 200 · status verified · verifiedAt preenchido
    else Arquivo ausente, alterado ou com redirect
        F-->>L: 422 · APPLE_PAY_DOMAIN_VERIFICATION_FAILED · status failed
        Note over L,D: Corrija a hospedagem e chame a validação de novo
    end
```

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.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
sequenceDiagram
    autonumber
    box rgb(255,246,229) Comprador
        participant C as Comprador
    end
    box rgb(243,245,248) Sua aplicação
        participant N as Navegador com Apple Pay JS
        participant L as Seu backend
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant P as Processador e Apple
    end
    Note over C,N: CPF ou CNPJ já coletado no checkout
    C->>N: Toca no botão Apple Pay
    N->>N: onvalidatemerchant · validationURL
    N->>F: POST /v1/apple-pay/validate-merchant · pk_ · validationUrl + domain
    F->>P: Valida a sessão no provedor
    F-->>N: 200 · sessão da Apple, opaca
    N->>P: completeMerchantValidation · sessão como veio · a folha abre
    C->>P: Autoriza com Face ID, Touch ID ou no iPhone
    P-->>N: onpaymentauthorized · payment.token
    N->>L: Envia o payment.token inteiro, sem alterar
    L->>F: POST /v1/charges · sk_ · wallet + customer.document
    F->>P: Repassa o token cifrado, sem decifrar
    F-->>L: 201 · paid ou refused
    L-->>N: Resultado da cobrança
    N-->>C: completePayment · sucesso ou falha
```

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](https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio.md), [listar](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios.md), [consultar](https://docs.fastpaybrasil.com/referencia/apple-pay/consultar-dominio.md) e [validar](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-dominio.md) domínio, e [validar sessão](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao.md).

> [!NOTE]
>
> **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

| Item | Detalhe |
| - | - |
| Chave secreta (`sk_`) | Para registrar e validar domínios e para criar a cobrança, no backend. Para os domínios, o usuário dono da chave precisa da permissão de domínios Apple Pay (perfis Owner, Manager e Desenvolvedor); sem ela, `403` `Acesso negado`. Para criar a cobrança, a chave precisa ser de um usuário Owner ou Manager |
| Chave pública (`pk_`) | Para validar a sessão a partir do navegador. A conta precisa estar ativa. A chave precisa estar vinculada a **um único merchant**: uma chave compartilhada por vários merchants torna a checagem do domínio ambígua |
| Domínio próprio em HTTPS | Certificado válido e sem redirecionamento no caminho `/.well-known/` |
| Apple Pay JS SDK | Versão 1.2.0 ou superior, com o elemento `<apple-pay-button>` registrado pelo SDK ([documentação da Apple](https://developer.apple.com/documentation/apple_pay_on_the_web)) |
| CPF ou CNPJ do cliente | Coletado no seu checkout **antes** de abrir a folha de pagamento do Apple Pay |

> [!NOTE]
>
> É 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

| Dispositivo do cliente | Navegador | Experiência |
| - | - | - |
| iPhone ou iPad | Safari, Chrome, Edge, Firefox e outros | Folha nativa do Apple Pay no próprio dispositivo (no iOS todos os navegadores usam o WebKit) |
| Mac | Safari | Folha nativa do Apple Pay, com Touch ID ou confirmação no iPhone ou Apple Watch |
| Mac ou PC com Windows | Chrome, Edge, Firefox e outros | O SDK abre um modal com um código. O cliente escaneia com a câmera do iPhone (iOS 18 ou superior) e autoriza no iPhone |
| Android | Qualquer | Sem Apple Pay: `canMakePayments()` retorna `false` e o botão nã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`.

> [!NOTE]
>
> 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

| Regra | Detalhe |
| - | - |
| Moeda | Somente `BRL`. Outra moeda é recusada com `APPLE_PAY_CURRENCY_NOT_SUPPORTED` |
| Documento do cliente | `customer.document` obrigatório. O token da Apple não traz CPF/CNPJ (`APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`) |
| Versão do token | Só `EC_v1` |
| Token | Enviado na íntegra, sem alterar nenhum campo (`APPLE_PAY_TOKEN_INVALID` se vier fora do formato) |
| Parcelas | `installments` continua obrigatório, de `1` a `12` |
| Campos de cartão | Com `wallet`, `number`, `holderName`, `expirationMonth`, `expirationYear` e `cvv` não são exigidos |
| 3D Secure | Não se aplica: a autenticação já vem no token |
| Domínio | Precisa estar `verified` e pertencer ao merchant da chave pública. Um domínio registrado vale para produção e para o Modo Teste |
| Quem cria a cobrança | Sempre o backend, com a chave secreta. A chave pública só valida a sessão |

> [!WARNING]
>
> 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.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/domains" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "checkout.minhaloja.com.br" }'
```

Resposta `201 Created`:

```json theme={null}
{
  "id": "2xYq8Lm3NcR7tVb1KdZ4wP6sQhE",
  "domain": "checkout.minhaloja.com.br",
  "status": "pending",
  "verifiedAt": null,
  "lastVerificationError": null,
  "verificationFile": {
    "path": "https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association",
    "content": "7B227073706964223A22..."
  },
  "createdAt": "2026-10-27T18:00:00.000Z",
  "updatedAt": "2026-10-27T18:00:00.000Z"
}
```

| Campo | Descrição |
| - | - |
| `id` | Identificador do registro. Use na validação (Etapa 3) |
| `status` | `pending` (aguardando verificação), `verified` (pronto para uso) ou `failed` (a última tentativa falhou; veja `lastVerificationError`) |
| `verificationFile.path` | Localização do arquivo informada pelo processador, quando disponível. O caminho que precisa responder é sempre o da Etapa 2 |
| `verificationFile.content` | Conteúdo do arquivo, a ser servido **como está**, sem decodificar |

> [!TIP]
>
> **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:

```text theme={null}
https://<seu-dominio>/.well-known/apple-developer-merchantid-domain-association
```

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:

```bash theme={null}
curl -sI https://checkout.minhaloja.com.br/.well-known/apple-developer-merchantid-domain-association
# HTTP/2 200
# content-type: text/plain
```

> [tab] Node.js (Express)
>
> ```javascript theme={null}
> // Conteúdo recebido em verificationFile.content, guardado em variável de ambiente
> const APPLE_PAY_FILE = process.env.APPLE_PAY_VERIFICATION_CONTENT;
>
> app.get('/.well-known/apple-developer-merchantid-domain-association', (req, res) => {
>   res.type('text/plain').status(200).send(APPLE_PAY_FILE);
> });
> ```

> [tab] Nginx
>
> ```nginx theme={null}
> location = /.well-known/apple-developer-merchantid-domain-association {
>   default_type text/plain;
>   alias /var/www/apple-pay/apple-developer-merchantid-domain-association;
> }
> ```

### Etapa 3: validar o domínio

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate" \
  -u "$FINVIA_API_KEY:"
```

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:

| Rota | Retorno |
| - | - |
| [`GET /v1/apple-pay/domains`](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios) | `{ "data": [...] }` com todos os domínios da conta, do mais recente para o mais antigo, sem paginação |
| [`GET /v1/apple-pay/domains/{id}`](https://docs.fastpaybrasil.com/referencia/apple-pay/consultar-dominio) | Um domínio, com o arquivo de verificação |

> [!TIP]
>
> 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**.

```javascript theme={null}
const session = new ApplePaySession(3, {
  countryCode: 'BR',
  currencyCode: 'BRL',
  supportedNetworks: ['visa', 'masterCard'],
  merchantCapabilities: ['supports3DS'],
  total: { label: 'Minha Loja', amount: '100.50' },
});

session.onvalidatemerchant = async (event) => {
  try {
    const response = await fetch(
      'https://api-global.fastpaybrasil.com/v1/apple-pay/validate-merchant',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: 'Basic ' + btoa('pk_SUA_CHAVE_PUBLICA:'),
        },
        body: JSON.stringify({
          validationUrl: event.validationURL,
          domain: window.location.hostname,
        }),
      },
    );
    if (!response.ok) throw new Error('validate-merchant failed');
    session.completeMerchantValidation(await response.json());
  } catch (error) {
    session.abort();
  }
};

session.onpaymentauthorized = async (event) => {
  // Enviar event.payment.token ao seu backend, que cria a cobrança (Etapa 5)
  const result = await createChargeOnYourBackend(event.payment.token);
  session.completePayment(
    result.status === 'paid'
      ? ApplePaySession.STATUS_SUCCESS
      : ApplePaySession.STATUS_FAILURE,
  );
};

// Chame begin() de forma síncrona dentro do handler de clique do botão.
session.begin();
```

> [!NOTE]
>
> 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.

> [!NOTE]
>
> **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.

> [!TIP]
>
> **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`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar). 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.

```json theme={null}
{
  "amount": 100.5,
  "currency": "BRL",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@email.com",
    "phone": "+5511987654321",
    "document": { "type": "cpf", "id": "52998224725" },
    "address": { "country": "BRA" }
  },
  "paymentMethod": {
    "type": "credit_card",
    "installments": 1,
    "wallet": {
      "type": "applepay",
      "token": {
        "paymentData": {
          "version": "EC_v1",
          "data": "<base64>",
          "signature": "<base64>",
          "header": {
            "ephemeralPublicKey": "<base64>",
            "publicKeyHash": "<base64>",
            "transactionId": "<hex>"
          }
        },
        "paymentMethod": {
          "displayName": "Visa 1234",
          "network": "Visa",
          "type": "credit"
        },
        "transactionIdentifier": "<id>"
      }
    }
  },
  "items": [
    {
      "title": "Produto XYZ",
      "type": "digital",
      "description": "Descrição do produto",
      "unit_price": 100.5,
      "quantity": 1
    }
  ]
}
```

Exemplo do lado do backend, recebendo o token do navegador:

```javascript Node.js theme={null}
app.post('/checkout/apple-pay', async (req, res) => {
  const { token, pedidoId } = req.body; // token = event.payment.token, sem alterações
  const pedido = await buscarPedido(pedidoId);

  const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', {
    method: 'POST',
    headers: {
      Authorization: `Basic ${Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64')}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: pedido.total,
      currency: 'BRL',
      customer: {
        name: pedido.nome,
        email: pedido.email,
        document: { type: 'cpf', id: pedido.cpf }, // coletado antes de abrir o Apple Pay
      },
      paymentMethod: {
        type: 'credit_card',
        installments: 1,
        wallet: { type: 'applepay', token },
      },
      items: pedido.itens,
    }),
  });

  const charge = await response.json();
  res.json({ status: charge.status, chargeId: charge.id });
});
```

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](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md).

## Redes suportadas

| Rede | Situação |
| - | - |
| Visa | Suportada |
| Mastercard | Suportada |
| Elo | Em homologação pelo processador |

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

| Código | HTTP | Quando |
| - | - | - |
| `APPLE_PAY_INVALID_DOMAIN` | 400 | `domain` não é um hostname puro (tem esquema, porta, caminho, é um IP ou é inválido) |
| `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` | 409 | Duas chamadas simultâneas registrando o mesmo hostname para o mesmo dono. Repita a chamada: o registro que venceu a corrida é devolvido |
| `APPLE_PAY_DOMAIN_NOT_FOUND` | 404 | `id` inexistente ou de outra conta |
| `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` | 422 | Arquivo de verificação ausente ou inacessível |
| `APPLE_PAY_DOMAIN_NOT_VERIFIED` | 400 | `validate-merchant` para domínio que não é seu, não registrado ou ainda não verificado |
| `APPLE_PAY_INVALID_VALIDATION_URL` | 400 | `validationUrl` não é uma URL HTTPS em `apple.com` ou subdomínio, sem porta e com até 2048 caracteres |
| `APPLE_PAY_PROVIDER_NOT_ENABLED` | 422 | A conta ainda não está no modelo pass-through: registre o domínio (Etapa 1) para habilitá-lo |
| `APPLE_PAY_RATE_LIMITED` | 429 | Mais de 20 validações de sessão do mesmo IP em 5 minutos, ou teto global da plataforma atingido. Aguarde alguns minutos |
| `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | 422 | O processador de Apple Pay não está configurado para a sua conta. Fale com o suporte |
| `APPLE_PAY_TOKEN_INVALID` | 400 | O objeto enviado em `wallet.token` não está no formato do token da Apple. Envie-o na íntegra, sem reescrever campos |
| `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | 400 | `customer.document` ausente. O token da Apple não traz CPF/CNPJ e o processador exige o documento em toda cobrança: colete-o no seu checkout antes de abrir a folha de pagamento |
| `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | 422 | Cobrança com Apple Pay pass-through em moeda diferente de `BRL` |
| `APPLE_PAY_PROVIDER_REJECTED` | 400 | O processador recusou a operação ou devolveu uma resposta fora do contrato |
| `APPLE_PAY_PROVIDER_UNAVAILABLE` | 503 | Processador indisponível ou limite de requisições atingido no processador. Tente de novo |
| `APPLE_PAY_PROVIDER_AUTH_FAILED` | 500 | Falha de autenticação entre a Finvia e o processador. Fale com o suporte |

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `validate-merchant` responde `400` `APPLE_PAY_DOMAIN_NOT_VERIFIED` | O `domain` enviado é diferente do registrado, é de outro merchant ou ainda não está `verified` | Confira com `GET /v1/apple-pay/domains` e valide o domínio (Etapa 3) |
| `validate-merchant` responde `422` `APPLE_PAY_PROVIDER_NOT_ENABLED` | A conta ainda não está no modelo pass-through | Registre o primeiro domínio (Etapa 1): é o registro que habilita o fluxo |
| `validate-merchant` responde `429` `APPLE_PAY_RATE_LIMITED` | Mais de 20 validações do mesmo IP em 5 minutos | Não repita a chamada em laço: valide a sessão uma vez por clique no botão |
| `403` `Acesso negado` ao registrar ou validar domínio | Usuário dono da chave sem permissão de domínios Apple Pay | Gere a chave com um usuário Owner, Manager ou Desenvolvedor |
| Validação do domínio falha com `422` | Arquivo inacessível ou servido de forma errada | Rode o `curl -sI` da Etapa 2: caminho sem extensão, `text/plain`, sem redirect e conteúdo sem alterações |
| O botão não aparece | Android, SDK não carregado, `canMakePayments()` avaliado cedo demais ou cliente sem cartão na Wallet | Confira a tabela "Onde o botão aparece". Em Chrome, Edge ou Firefox no Mac e no Windows, o botão só existe com o SDK e o elemento `<apple-pay-button>` |
| Cobrança recusada com `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | CPF/CNPJ não enviado | Colete o documento antes de abrir o Apple Pay e envie em `customer.document` |
| Cobrança recusada com `APPLE_PAY_TOKEN_INVALID` | Token alterado ou reescrito no caminho | Envie `event.payment.token` exatamente como veio |

## Perguntas frequentes

> [accordion] Preciso de conta Apple Developer ou de certificado?
>
> 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.

> [accordion] Posso usar a chave pública no código do site?
>
> 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.

> [accordion] Tenho [www.minhaloja.com.br](http://www.minhaloja.com.br) e minhaloja.com.br. Registro os dois?
>
> Sim, se o botão aparecer nos dois. Cada hostname é um registro próprio e precisa ser verificado.

> [accordion] Apple Pay aceita parcelamento?
>
> 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.

> [accordion] Como testo o Apple Pay?
>
> 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](https://docs.fastpaybrasil.com/homologacao/roteiro.md):

* **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

| | Certificado próprio (antes) | Pass-through (agora) |
| - | - | - |
| Conta Apple Developer e Merchant ID | Obrigatórios, seus | Não são necessários: a relação com a Apple é do processador |
| Verificação do domínio | No portal da Apple, com o arquivo `.txt` do seu Merchant ID em `/.well-known/` | Pela API da Finvia (Etapas 1 a 3), com o arquivo do processador no caminho **sem extensão**. O `.txt` antigo pode continuar no ar |
| `onvalidatemerchant` | Resolvido no seu backend com o Merchant Identity Certificate | Chama `POST /v1/apple-pay/validate-merchant` com a chave `pk_` (Etapa 4) e devolve a sessão à Apple sem modificar |
| Certificados | Payment Processing Certificate entregue à Finvia, renovação a cada 25 meses | Nenhum certificado, nada a renovar |
| `supportedNetworks` | Visa, Mastercard, Amex, Discover | Apenas `visa` e `masterCard` (Elo em homologação) |
| Moeda | Qualquer moeda da sua conta | Apenas `BRL` (`APPLE_PAY_CURRENCY_NOT_SUPPORTED`) |
| `customer.document` na cobrança | Opcional | Obrigatório (`APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`): o token da Apple não traz CPF/CNPJ, colete-o antes de abrir a folha de pagamento |
| 3D Secure | Aplicado pela Finvia sobre o cartão decifrado | Não se aplica: `three_ds` vem nulo na resposta e nos webhooks |
| `POST /v1/charges` | `paymentMethod.wallet` com o token na íntegra | Igual, sem mudança de formato |

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

> [card] [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Campos do objeto `wallet`.

> [card] [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md)
>
> Regras de cartão que valem para o Apple Pay.

> [card] [Apple Pay on the Web](https://developer.apple.com/documentation/apple_pay_on_the_web)
>
> Documentação da Apple sobre o Apple Pay JS.

> [card] [Diretrizes de interface do Apple Pay](https://developer.apple.com/design/human-interface-guidelines/apple-pay)
>
> Como exibir o botão.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.