> ## 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 domínio Apple Pay

> Confere o arquivo de verificação hospedado no seu domínio e, se estiver correto, deixa o domínio pronto para o Apple Pay.

Depois de registrar o domínio e hospedar o arquivo de verificação, chame esta rota para que o processador confira o arquivo. Quando a conferência passa, o domínio fica `verified` e o botão Apple Pay pode ser usado nas páginas desse hostname.

## Quando usar

| Situação | O que fazer |
| - | - |
| Acabou de hospedar o arquivo | Chame a validação |
| A validação anterior falhou | Corrija a hospedagem e chame de novo |
| Mudou a infraestrutura do site (CDN, servidor, redirecionamentos) | Valide de novo para confirmar que o arquivo continua acessível |

## Antes de chamar

* Use a **chave secreta** (`sk_`) no seu backend.
* O usuário dono da chave precisa da permissão de domínios Apple Pay (perfis **Owner**, **Manager** e **Desenvolvedor**).
* Publique o conteúdo de `verificationFile.content` em `https://<seu-dominio>/.well-known/apple-developer-merchantid-domain-association`: caminho sem extensão, `Content-Type: text/plain`, HTTPS válido, resposta `200`, sem redirecionamento e 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
```

## Parâmetros de caminho

**id** `string` *required*

Identificador do registro de domínio, devolvido por [`POST /v1/apple-pay/domains`](https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio). Ex.: `2xYq8Lm3NcR7tVb1KdZ4wP6sQhE`.

Esta rota não tem corpo.

## Respostas

A resposta `200` é o objeto Domínio atualizado (os campos estão em [Registrar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio.md#respostas)). Quando a conferência passa, vem `status: "verified"` e `verifiedAt` preenchido.

Quando a conferência falha, a API responde `422` `APPLE_PAY_DOMAIN_VERIFICATION_FAILED`, o domínio passa a `failed`, `verifiedAt` volta a `null` e o motivo fica em `lastVerificationError`. Consulte com [`GET /v1/apple-pay/domains/{id}`](https://docs.fastpaybrasil.com/referencia/apple-pay/consultar-dominio) para ler o motivo.

| HTTP | Significado | Código ou mensagem |
| - | - | - |
| `200` | Domínio verificado | Objeto Domínio |
| `401` | Credencial inválida | `Unauthorized` |
| `403` | Usuário dono da chave sem permissão de domínios Apple Pay | `Acesso negado` |
| `404` | Domínio inexistente ou de outra conta | `APPLE_PAY_DOMAIN_NOT_FOUND` |
| `422` | Arquivo ausente, inacessível ou diferente do esperado | `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` |
| `422` | Processador de Apple Pay não configurado para a sua conta | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` |
| `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`. Os erros `401` e `403` seguem o formato padrão, com `statusCode`.

> [!TIP]
>
> O domínio está pronto quando esta rota responde `200` com `status: "verified"` para o hostname exato da página do checkout.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `422` `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` | Caminho com extensão (`.txt`), redirecionamento HTTP para HTTPS ou para `www`, `Content-Type` diferente de `text/plain` ou conteúdo alterado | Rode o `curl -sI` acima, corrija e valide de novo |
| `404` `APPLE_PAY_DOMAIN_NOT_FOUND` | `id` errado ou de outra conta | Localize o `id` pela [listagem](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios.md) |
| `503` `APPLE_PAY_PROVIDER_UNAVAILABLE` | Processador indisponível no momento | Tente de novo em alguns minutos |

```http REST (JSON) theme={null}
POST /v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

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

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(
  'https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate',
  { method: 'POST', headers: { Authorization: `Basic ${credentials}` } },
);

const body = await response.json();
if (response.status === 200 && body.status === 'verified') {
  console.log('Domínio pronto para o Apple Pay');
} else {
  console.warn('Falha na verificação:', body.code);
}
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate"))
            .header("Authorization", "Basic " + credentials)
            .method("POST", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/apple-pay/domains/2xYq8Lm3NcR7tVb1KdZ4wP6sQhE/validate")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "id": "2xYq8Lm3NcR7tVb1KdZ4wP6sQhE",
  "domain": "checkout.minhaloja.com.br",
  "status": "verified",
  "verifiedAt": "2026-10-27T18:05:00.000Z",
  "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:05:00.000Z"
}
```

```json 422 theme={null}
{
  "code": "APPLE_PAY_DOMAIN_VERIFICATION_FAILED",
  "message": "..."
}
```

## Veja também

> [card] [Validar sessão](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao.md)
>
> Próximo passo: a chamada feita pelo navegador.

> [card] [Guia de Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md)
>
> Exemplos de hospedagem em Node.js e Nginx.


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