Português

English

Português

English

Appearance

Configuração de domínios para Apple Pay ​

Para habilitar o Apple Pay em sua loja, é necessário disponibilizar o arquivo .well-known/apple-developer-merchantid-domain-association na raiz de cada domínio onde o botão de pagamento será exibido.

Obrigatório em todos os modelos de integração

Esse passo é necessário mesmo se você instala o aplicativo da Appmax via AppStore (modelo integrado, com client_id/external_id por loja). O que muda entre os modelos é apenas quem cadastra o domínio junto à Apple — o arquivo .well-known, você sempre publica. Veja Pagamento com Apple Pay para o fluxo completo e a distinção entre modelos.

Para que serve esse arquivo? ​

Esse arquivo é exigido pela Apple como parte do processo de verificação de domínio. Ele comprova que a Appmax tem autorização para processar pagamentos Apple Pay nos domínios informados.

A Apple utiliza esse arquivo para validar que o domínio está vinculado corretamente ao Merchant ID configurado pela Appmax. Sem ele, o botão "Pagar com Apple Pay" não funciona no ambiente de produção — a PaymentSheet não abre, ou a validação do domínio falha a cada tentativa de transação.

O .well-known não é o Apple Token

O Apple Token é o cartão tokenizado, gerado a cada transação (veja Pagamento com Apple Pay). O .well-known é um arquivo estático, o mesmo em todos os domínios, vinculado ao merchantIdentifier da Appmax — não à transação.

1. Conteúdo do arquivo ​

Salve o texto abaixo em um arquivo chamado apple-developer-merchantid-domain-association (sem extensão). É o mesmo conteúdo para todos os domínios da sua implementação:

7b2276657273696f6e223a312c227073704964223a2238383637324534354136323336423032384645463731323938334343354338354339334633353231433430374142313338414543354144434641334330334442222c22637265617465644f6e223a313735323630333939333937337d

Copie exatamente como está — sem quebra de linha no fim

O conteúdo é validado pela Apple byte a byte: um espaço ou uma quebra de linha a mais invalida a verificação do domínio.

Esta é a causa mais comum de falha, porque praticamente todo editor de texto acrescenta um \n ao salvar, e echo faz o mesmo. O arquivo tem exatamente 228 bytes. Para criar sem quebra de linha, use printf (não echo):

bash
printf '%s' '7b2276657273696f6e...' > apple-developer-merchantid-domain-association

Se o seu editor não permite salvar sem a quebra final, gere o arquivo pela linha de comando.

2. Publicar o arquivo em cada domínio ​

O arquivo deve ser publicado no seguinte caminho em cada domínio onde o Apple Pay será utilizado, sem alterar o nome do arquivo:

https://<domínio-da-loja>/.well-known/apple-developer-merchantid-domain-association

Exemplos:

  • https://dominio1.com.br/.well-known/apple-developer-merchantid-domain-association
  • https://dominio2.com.br/.well-known/apple-developer-merchantid-domain-association
  • https://loja3.com.br/.well-known/apple-developer-merchantid-domain-association

3. Verificar acessibilidade ​

Após publicar o arquivo, confirme que ele está acessível:

bash
curl -sI https://<domínio-da-loja>/.well-known/apple-developer-merchantid-domain-association

A resposta esperada deve conter:

  • HTTP/2 200 OK (ou HTTP/1.1 200 OK)
  • Content-Type: text/plain
  • Nenhum redirecionamento (nem 301/302 de http para https, nem de www para o domínio raiz ou vice-versa)

Confirme também o tamanho, que é o que pega a quebra de linha extra:

bash
# deve imprimir exatamente 228
curl -s https://<domínio-da-loja>/.well-known/apple-developer-merchantid-domain-association | wc -c

O curl -I sozinho não prova nada

Em requisições HEAD, muitos servidores não devolvem Content-Type — então o comando pode passar a impressão de estar tudo certo sem verificar o conteúdo. Rode os dois: o -sI para status e headers, e o wc -c para o byte count.

O arquivo não tem extensão ​

Como o nome do arquivo não tem extensão, muitos servidores e CDNs o entregam como application/octet-stream, ou forçam download como anexo. Pela regra da Apple, ele precisa responder como text/plain. As três situações mais comuns:

Nginx — declare o tipo para esse caminho exato:

nginx
location = /.well-known/apple-developer-merchantid-domain-association {
    default_type text/plain;
    add_header Cache-Control "public, max-age=3600";
}

Apache — no .htaccess da raiz:

apache
<Files "apple-developer-merchantid-domain-association">
    ForceType text/plain
    Header set Cache-Control "public, max-age=3600"
</Files>

Frameworks (Next.js, Nuxt, Laravel) — quando a pasta de arquivos estáticos não permite controlar o header, sirva por uma rota dedicada. Exemplo em Next.js (App Router):

ts
// app/.well-known/apple-developer-merchantid-domain-association/route.ts
export function GET() {
  return new Response(process.env.APPLE_MERCHANT_ASSOCIATION!, {
    headers: {
      'Content-Type': 'text/plain',
      'Cache-Control': 'public, max-age=3600',
    },
  });
}

Atenção ao guardar o conteúdo em variável de ambiente: alguns painéis acrescentam quebra de linha. Um .trim() no valor evita o problema.

4. Cadastro do domínio junto à Apple ​

Com o arquivo publicado e acessível, o cadastro do domínio junto à Apple muda conforme o seu modelo de integração:

  • Modelo integrado (instalação via AppStore): o cadastro é feito pela Appmax, por API, assim que o domínio é informado na instalação do aplicativo (parâmetro domain_name ou domain_names). Basta que o arquivo já esteja publicado quando isso acontecer.
  • Fluxo direto: você mesmo cadastra o domínio no painel de desenvolvedor da Apple, na sua própria conta Apple. A Apple valida o arquivo .well-known na hora do cadastro.

Em ambos os casos, se o domínio da loja mudar, o novo domínio é tratado como um domínio novo — republique o arquivo .well-known nele e registre-o novamente (não é necessário criar um novo merchant).

Boas práticas ​

  • HTTPS é obrigatório: o domínio deve responder apenas via conexão segura.
  • Evite redirecionamentos: a URL deve responder diretamente com status 200, sem passar por www, http→https ou qualquer outro redirect antes de chegar ao arquivo.
  • Não altere o conteúdo do arquivo: ele é validado pela Apple byte a byte.
  • Content-Type: sirva o arquivo como text/plain.
  • Cache-Control sugerido: public, max-age=3600.

Em caso de dúvidas, entre em contato com o suporte técnico da Appmax.