Skip to main content
POST
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.
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. É 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 antes de registrar.

Quando usar

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

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.
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.
string
Identificador do registro. Use na validação e na consulta. Ex.: 2xYq8Lm3NcR7tVb1KdZ4wP6sQhE.
string
Hostname registrado, em minúsculas. Ex.: checkout.minhaloja.com.br.
string
Situação do domínio: pending (aguardando verificação), verified (pronto para uso) ou failed (a última verificação falhou; veja lastVerificationError).
string | null
Data e hora da verificação, em ISO 8601. null enquanto o domínio não estiver verified.
string | null
Motivo da última falha de verificação. null quando não houve falha.
object
Arquivo que você precisa hospedar no domínio.
string
Data e hora do registro, em ISO 8601.
string
Data e hora da última atualização, em ISO 8601.

Formato dos erros

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

Erros comuns

Veja também

Validar domínio

Confirme o arquivo hospedado.

Guia de Apple Pay

Fluxo completo, do domínio à cobrança.

Listar domínios

Todos os domínios da conta.

Validar sessão

Chamada feita pelo navegador a cada compra.