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

# Registrar domínio Apple Pay

> Registra o hostname onde o botão Apple Pay aparece e devolve o arquivo de verificação que você precisa hospedar.

Esta rota é o primeiro passo para aceitar Apple Pay no seu site. Você informa o hostname da página de checkout, a Finvia registra o domínio no processador e devolve o arquivo de verificação. Depois de hospedar o arquivo, você confirma o domínio em [`POST /v1/apple-pay/domains/{id}/validate`](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-dominio).

> [!WARNING]
>
> Registrar o **primeiro domínio** ativa na sua conta o modelo de Apple Pay em que a sessão é validada por [`POST /v1/apple-pay/validate-merchant`](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao). É este passo que liga o Apple Pay na sua integração. Se a sua conta já operava Apple Pay com certificado próprio, leia a seção de migração do [guia de Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) antes de registrar.

## Quando usar

| Situação | O que fazer |
| - | - |
| Primeira integração com Apple Pay | Registre cada hostname onde o botão aparece |
| Novo subdomínio de checkout | Registre o novo hostname. `www` e o domínio raiz são registros diferentes |
| Perdeu o `id` ou o arquivo de verificação | Registre de novo o mesmo hostname: a rota devolve o registro que já existe |

## Antes de chamar

* Use a **chave secreta** (`sk_`) no seu backend, no formato Basic (a chave como usuário, senha vazia).
* O usuário dono da chave precisa da permissão de domínios Apple Pay (perfis **Owner**, **Manager** e **Desenvolvedor**). Sem ela, a API responde `403`.
* O registro não separa produção de teste: um domínio registrado vale para os dois modos.

## Corpo da requisição

**domain** `string` *required*

Hostname onde o botão Apple Pay aparece, com até 255 caracteres. Só o hostname: sem `https://`, sem porta e sem caminho. Endereço IP não é aceito. O valor é gravado em minúsculas. Ex.: `checkout.minhaloja.com.br`.

> [!NOTE]
>
> Não envie outros campos no corpo. Registre exatamente o hostname que o navegador mostra em `window.location.hostname`: cada subdomínio é um registro separado.

## Respostas

A resposta `201` é o objeto Domínio. A rota é idempotente: se a mesma conta registrar de novo o mesmo hostname, recebe o mesmo objeto, também com `201`.

**id** `string`

Identificador do registro. Use na validação e na consulta. Ex.: `2xYq8Lm3NcR7tVb1KdZ4wP6sQhE`.

**domain** `string`

Hostname registrado, em minúsculas. Ex.: `checkout.minhaloja.com.br`.

**status** `string`

Situação do domínio: `pending` (aguardando verificação), `verified` (pronto para uso) ou `failed` (a última verificação falhou; veja `lastVerificationError`).

**verifiedAt** `string | null`

Data e hora da verificação, em ISO 8601. `null` enquanto o domínio não estiver `verified`.

**lastVerificationError** `string | null`

Motivo da última falha de verificação. `null` quando não houve falha.

**verificationFile** `object`

Arquivo que você precisa hospedar no domínio.

**propriedades**

**path** `string | null`

Localização do arquivo informada pelo processador, quando disponível. O caminho que precisa responder é sempre `/.well-known/apple-developer-merchantid-domain-association`.

**content** `string | null`

Conteúdo do arquivo, a ser servido como está, sem decodificar. Se vier `null`, não repita a chamada: fale com o suporte.

**createdAt** `string`

Data e hora do registro, em ISO 8601.

**updatedAt** `string`

Data e hora da última atualização, em ISO 8601.

| HTTP | Significado | Código ou mensagem |
| - | - | - |
| `201` | Domínio registrado (ou registro já existente devolvido) | Objeto Domínio |
| `400` | `domain` não é um hostname válido | `APPLE_PAY_INVALID_DOMAIN` |
| `400` | O processador recusou o registro | `APPLE_PAY_PROVIDER_REJECTED` |
| `400` | Corpo inválido (campo ausente ou acima de 255 caracteres) | Lista de mensagens de validação |
| `401` | Credencial inválida | `Unauthorized` |
| `403` | Usuário dono da chave sem permissão de domínios Apple Pay | `Acesso negado` |
| `409` | Dois registros simultâneos do mesmo hostname (raro) | `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` |
| `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` |

### Formato dos erros

| Tipo de erro | Corpo |
| - | - |
| Erro de negócio (códigos `APPLE_PAY_*`) | `{ "code": "...", "message": "..." }`, sem `statusCode` |
| Validação de campo | `{ "statusCode": 400, "message": [...], "error": "Bad Request" }` |
| Credencial inválida | `{ "statusCode": 401, "message": "Unauthorized" }` |
| Sem permissão | `{ "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" }` |

Trate o erro pelo código HTTP e pelo campo `code`, não pelo texto de `message`.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` `APPLE_PAY_INVALID_DOMAIN` | `domain` com `https://`, porta, caminho ou IP | Envie só o hostname, ex.: `checkout.minhaloja.com.br` |
| `409` `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` | Duas chamadas simultâneas para o mesmo hostname | Repita a chamada: o registro existente é devolvido |
| `403` `Acesso negado` | Chave de usuário sem permissão de domínios Apple Pay | Gere a chave com um usuário Owner, Manager ou Desenvolvedor |
| `422` `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | Conta sem processador de Apple Pay | Fale com o suporte |
| `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 HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "domain": "checkout.minhaloja.com.br"
}
```

```bash cURL 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" }'
```

```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', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ domain: 'checkout.minhaloja.com.br' }),
});

const dominio = await response.json();
// Guarde dominio.id e publique dominio.verificationFile.content no seu site
console.log(dominio.id, dominio.status);
```

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

import requests

payload = {
    "domain": "checkout.minhaloja.com.br",
}

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

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

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

$payload = [
    'domain' => 'checkout.minhaloja.com.br',
];

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

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$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());

        String payload = """
            {
              "domain": "checkout.minhaloja.com.br"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/apple-pay/domains"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .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 payload = """
{
  "domain": "checkout.minhaloja.com.br"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/apple-pay/domains");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

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"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "domain": "checkout.minhaloja.com.br"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/apple-pay/domains", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	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 "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/apple-pay/domains")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "domain" => "checkout.minhaloja.com.br",
})

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

puts response.code
puts response.body
```

```json 201 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"
}
```

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

```json 403 theme={null}
{
  "statusCode": 403,
  "message": "Acesso negado",
  "error": "Forbidden"
}
```

## Veja também

> [card] [Validar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-dominio.md)
>
> Confirme o arquivo hospedado.

> [card] [Guia de Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md)
>
> Fluxo completo, do domínio à cobrança.

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

> [card] [Validar sessão](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao.md)
>
> Chamada feita pelo navegador a cada compra.


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