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

# Validar sessão Apple Pay

> Chamada feita pelo navegador no evento onvalidatemerchant: devolve a sessão de merchant da Apple que abre a folha de pagamento.

A cada compra, quando o cliente toca no botão Apple Pay, o Apple Pay JS dispara o evento `onvalidatemerchant` e pede uma sessão de merchant. O seu front-end chama esta rota com a `validationURL` recebida da Apple e o hostname da página, e repassa a resposta para `session.completeMerchantValidation()`. Sem esse passo, a folha de pagamento não abre.

> [!NOTE]
>
> **Para o negócio:** esta é a única chamada do fluxo feita pelo navegador do cliente. Ela usa a chave pública, que pode ficar no código do site. A cobrança continua sendo criada pelo seu backend, com a chave secreta.

## Autenticação com a chave pública

Esta rota usa **Basic com a chave pública** (`pk_` em produção ou `pk_test_` no Modo Teste) como usuário e senha vazia: `Authorization: Basic base64("pk_...:")`. A chave secreta (`sk_`) não deve ir para o navegador.

* A conta dona da chave pública precisa estar ativa.
* A sessão é sempre validada no provedor real, mesmo com `pk_test_`, porque a folha do Safari só abre com uma sessão real. A cobrança feita depois com a chave de teste cai no ambiente de teste.

## Quando usar

| Situação | O que fazer |
| - | - |
| Evento `onvalidatemerchant` disparado | Chame esta rota uma vez e repasse a resposta à Apple |
| Cliente fechou e abriu a folha de novo | Uma nova sessão gera um novo `onvalidatemerchant`: chame de novo |
| Teste em laço ou várias chamadas por clique | Evite: há limite de tentativas por IP |

## Antes de chamar

* O hostname da página está registrado e `verified` na conta da chave pública ([Registrar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio.md) e [Validar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-dominio.md)).
* A conta já registrou pelo menos um domínio. Sem nenhum, a API responde `422` `APPLE_PAY_PROVIDER_NOT_ENABLED`.

## Corpo da requisição

**validationUrl** `string` *required*

O valor de `event.validationURL` recebido no `onvalidatemerchant`. Precisa ser `https`, com host `apple.com` ou um subdomínio dele, sem porta e com até 2048 caracteres. Repasse sem alterar.

**domain** `string` *required*

O hostname da página, `window.location.hostname`, com até 255 caracteres. Precisa ser um domínio registrado e verificado na conta da chave pública. Ex.: `checkout.minhaloja.com.br`.

## Respostas

A resposta `200` é o objeto de sessão de merchant da Apple. Ele é **opaco**: não leia nem altere os campos. Repasse o objeto inteiro, como veio, para `session.completeMerchantValidation()`.

| HTTP | Significado | Código ou mensagem |
| - | - | - |
| `200` | Sessão criada | Objeto de sessão da Apple |
| `400` | `validationUrl` fora das regras (não `https`, host fora de `apple.com`, com porta ou longa demais) | `APPLE_PAY_INVALID_VALIDATION_URL` |
| `400` | `domain` inválido | `APPLE_PAY_INVALID_DOMAIN` |
| `400` | Domínio de outra conta, não registrado ou ainda não verificado | `APPLE_PAY_DOMAIN_NOT_VERIFIED` |
| `401` | Chave pública inválida | `Unauthorized` |
| `422` | A conta ainda não registrou nenhum domínio | `APPLE_PAY_PROVIDER_NOT_ENABLED` |
| `422` | Processador de Apple Pay não configurado para a sua conta | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` |
| `429` | Limite de tentativas atingido: 20 por IP a cada 5 minutos, além de um teto global da plataforma | `APPLE_PAY_RATE_LIMITED` |
| `500` | Falha de autenticação entre a Finvia e o processador | `APPLE_PAY_PROVIDER_AUTH_FAILED` |
| `503` | Processador indisponível | `APPLE_PAY_PROVIDER_UNAVAILABLE` |

Os erros `APPLE_PAY_*` vêm no formato `{ "code": "...", "message": "..." }`, sem `statusCode`. Erros de validação de campo vêm como `{ "statusCode": 400, "message": [...], "error": "Bad Request" }`. Em qualquer erro, chame `session.abort()` e ofereça outra forma de pagamento.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` `APPLE_PAY_DOMAIN_NOT_VERIFIED` | O `domain` enviado é diferente do registrado (ex.: `www`), é de outra conta ou ainda não está `verified` | Confira com [`GET /v1/apple-pay/domains`](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios) e valide o domínio |
| `422` `APPLE_PAY_PROVIDER_NOT_ENABLED` | Nenhum domínio registrado na conta | Registre o primeiro domínio: é o registro que habilita o fluxo |
| `429` `APPLE_PAY_RATE_LIMITED` | Mais de 20 tentativas do mesmo IP em 5 minutos | Chame uma vez por `onvalidatemerchant`, sem repetir em laço |
| `401` | Chave pública errada ou com a chave secreta no lugar | Use a `pk_` (ou `pk_test_`) da mesma conta que registrou o domínio |
| A folha abre e fecha em seguida | A resposta foi alterada antes de chegar à Apple | Passe o JSON recebido direto para `completeMerchantValidation()` |

```javascript Navegador theme={null}
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 falhou');
    session.completeMerchantValidation(await response.json());
  } catch (error) {
    session.abort();
  }
};
```

```http REST (JSON) theme={null}
POST /v1/apple-pay/validate-merchant HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_PUBLICA:">
Content-Type: application/json

{
  "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
  "domain": "checkout.minhaloja.com.br"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/apple-pay/validate-merchant" \
  -u "$FINVIA_PUBLIC_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain": "checkout.minhaloja.com.br"
  }'
```

```json 200 theme={null}
{
  "epochTimestamp": 1761588000000,
  "expiresAt": 1761591600000,
  "merchantSessionIdentifier": "...",
  "nonce": "...",
  "merchantIdentifier": "...",
  "domainName": "checkout.minhaloja.com.br",
  "displayName": "...",
  "signature": "..."
}
```

```json 400 theme={null}
{
  "code": "APPLE_PAY_DOMAIN_NOT_VERIFIED",
  "message": "..."
}
```

> [!NOTE]
>
> O exemplo `200` mostra a forma usual da sessão da Apple, com valores omitidos. O conteúdo é definido pela Apple e pode mudar: trate o objeto como opaco.

## Veja também

> [card] [Guia de Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md)
>
> Fluxo completo no navegador e no backend.

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

> [card] [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)
>
> Onde obter a chave pública.

> [card] [Listar domínios](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios.md)
>
> Confira os domínios verificados.


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