Pagamentos com Apple Pay

Visão Geral

O Apple Pay é um método de pagamento digital que permite aos seus clientes pagar com cartões armazenados de forma segura em seus dispositivos Apple (iPhone, iPad, Mac, Apple Watch). A Autorizou processa pagamentos Apple Pay de forma nativa, oferecendo uma integração simples e sem complicações.

Sem Certificados

Não precisa gerar ou gerenciar certificados Apple

Sem Apple Developer

Não precisa ter conta Apple Developer

Setup Rápido

Apenas forneça domínio e hospede 1 arquivo

Benefícios

✅ Experiência otimizada - Checkout 70% mais rápido que formulários tradicionais
✅ Segurança máxima - Biometria (Face ID/Touch ID) + tokenização
✅ Maior conversão - Menos abandono de carrinho
✅ Suporte amplo - Visa, Mastercard, Elo, Hipercard e outras bandeiras

Como Funciona

Fluxo de Configuração:

Você fornece seu domínio ao suporte da Autorizou
Autorizou registra o domínio e fornece arquivo de verificação
Você hospeda o arquivo em /.well-known/apple-developer-merchantid-domain-association.txt
Pronto! Pode começar a aceitar Apple Pay

Fluxo de Pagamento:

Cliente clica no botão Apple Pay no seu site
Dispositivo valida identidade com Face ID/Touch ID
Apple gera token criptografado do pagamento
Seu sistema envia token para API Autorizou
Autorizou processa pagamento e retorna resultado

A Autorizou cuida de toda a complexidade técnica: certificados Apple, descriptografia de tokens, processamento seguro. Você só precisa integrar o botão no frontend e hospedar um arquivo de verificação.

Requisitos

Domínio HTTPS

Obrigatório - Apple exige SSL válido

Acesso ao Servidor

Para hospedar arquivo de verificação

Dispositivo Apple

Para testar (não funciona em simulador)

Conta Autorizou Ativa

Com método Apple Pay habilitado

Não é necessário ter conta Apple Developer própria. A Autorizou gerencia toda a configuração técnica.

Passo 1: Solicitar Habilitação do Apple Pay

Processo Simplificado: Você NÃO precisa ter conta Apple Developer ou gerar certificados. A Autorizou gerencia tudo isso por você.

A Autorizou gerencia toda a configuração técnica do Apple Pay. Você só precisa fornecer seu domínio e hospedar um arquivo de verificação.

1.1 Solicitar Registro do Seu Domínio

Entre em contato com o suporte da Autorizou através de:

📧 Email: suporte@autorizou.com.br
💬 Chat no dashboard
📱 WhatsApp Business (disponível no dashboard)

Forneça as seguintes informações:

domain

string

required

Domínio onde você vai aceitar pagamentos Apple PayExemplo: checkout.sualoja.com.br ou www.sualoja.com.brImportante: Deve ser o domínio exato onde o botão Apple Pay será exibido

business_name

string

required

Nome da sua empresa/loja que aparecerá no Apple PayExemplo: “Minha Loja” ou “Loja ABC”

1.2 Receber Arquivo de Verificação

Após registrar seu domínio, a Autorizou fornecerá:

✅ Arquivo de verificação apple-developer-merchantid-domain-association.txt
✅ Instruções específicas para seu domínio
✅ Orientações para hospedagem do arquivo

O processo geralmente leva 1 dia útil. Você receberá o arquivo por email com instruções detalhadas.

1.3 Hospedar Arquivo de Verificação

Você precisa hospedar o arquivo recebido em um caminho específico do seu domínio: Local obrigatório:

https://seu-dominio.com.br/.well-known/apple-developer-merchantid-domain-association.txt

Exemplo prático: Se seu domínio é checkout.loja.com.br, o arquivo deve estar acessível em:

https://checkout.loja.com.br/.well-known/apple-developer-merchantid-domain-association.txt

Crie o diretório .well-known

No seu servidor web, crie o diretório .well-known na raiz do domínio

Coloque o arquivo

Copie o arquivo apple-developer-merchantid-domain-association.txt para dentro do diretório .well-known

Configure permissões

Certifique-se de que o arquivo tem permissões de leitura (644) e está acessível via HTTPS

Teste o acesso

Acesse a URL completa no navegador e confirme que o arquivo é baixado sem erros

Requisitos técnicos:

✓ Arquivo acessível via HTTPS (não HTTP)

✓ Retorna status HTTP 200 OK

✓ Sem autenticação necessária (acesso público)

✓ Content-Type correto (geralmente text/plain ou application/octet-stream)

Validar configuração:

Terminal

# Testar se o arquivo está acessível
curl -I https://seu-dominio.com.br/.well-known/apple-developer-merchantid-domain-association.txt

# Deve retornar:
# HTTP/2 200
# ...

Se o arquivo não estiver acessível corretamente, o Apple Pay não funcionará no seu domínio. Verifique configurações de firewall, CDN e servidor web.

1.4 Confirmar com Autorizou

Após hospedar o arquivo:

Confirme com o suporte da Autorizou que o arquivo está acessível
A Autorizou validará o domínio com a Apple
Você receberá confirmação de que pode começar a usar Apple Pay

Esse processo geralmente leva de 1 a 2 dias úteis. A Autorizou cuidará de todos os certificados e configurações técnicas necessárias.

Passo 2: Integração Frontend

2.1 Adicionar Botão Apple Pay

Use o elemento HTML nativo <apple-pay-button> da Apple no seu checkout:

HTML

<apple-pay-button 
  buttonstyle="black" 
  type="buy" 
  locale="pt-BR"
></apple-pay-button>

Documentação completa: Consulte o guia oficial da Apple para implementação detalhada do botão e opções de customização.

2.2 Validar Sessão do Merchant

Durante o fluxo de pagamento Apple Pay, você precisa validar a sessão através da API Autorizou:

JavaScript

// No evento onvalidatemerchant do ApplePaySession
session.onvalidatemerchant = async (event) => {
  try {
    // Chamar endpoint de validação da Autorizou
    const response = await fetch('https://zeus-sandbox.autorizou.dev/api/v1/apple-pay/validate-session', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        validationURL: event.validationURL,
        domainName: window.location.hostname
      })
    });

    const merchantSession = await response.json();
    
    // Completar validação com dados retornados
    session.completeMerchantValidation(merchantSession.sessionData);
  } catch (error) {
    console.error('Erro na validação:', error);
    session.abort();
  }
};

Parâmetros:

validationURL: URL fornecida pela Apple no evento (única por sessão)
domainName: Seu domínio registrado (ex: checkout.sualoja.com.br)

Para ver a documentação completa da validação de sessão, incluindo tratamento de erros, consulte Validar Sessão Apple Pay.

Passo 3: Processar Pagamento na API

Após receber o token Apple Pay no evento onpaymentauthorized, envie-o para o endpoint de criação de pedidos da Autorizou: Endpoint: POST /api/v1/charges/orders Método de pagamento: apple_pay

Parâmetros do Payload

payment.apple_pay.apple_pay_token

string

required

Token obtido de event.payment do evento onpaymentauthorized do ApplePaySessionImportante: Use JSON.stringify() para converter o objeto em string. Deve ser o objeto event.payment completo (não apenas event.payment.token), pois a API extrai internamente token.paymentData.Exemplo:

apple_pay_token: JSON.stringify(event.payment)

payment.apple_pay.statement_descriptor

string

required

Nome que aparece na fatura do cartãoMáximo: 22 caracteresExemplo: MINHA LOJA

payment.apple_pay.capture

boolean

required

Se deve capturar automaticamente o pagamentoValores: true (captura imediata), false (captura manual posterior)

payment.apple_pay.capture_delay_hours

integer

Horas de atraso para captura automáticaObrigatório se: capture = falseMínimo: 0 | Máximo: 168 (7 dias)

Exemplo de Requisição

// No evento onpaymentauthorized
session.onpaymentauthorized = async (event) => {
  try {
    const response = await fetch('https://zeus-sandbox.autorizou.dev/api/v1/charges/orders', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer SEU_TOKEN_API',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        description: 'Compra via Apple Pay',
        code: 'ORDER-123',
        mcc: '5411',
        customer: {
          id: 12345,
          name: 'João Silva',
          email: 'joao@exemplo.com.br'
        },
        payment: {
          amount: 25000, // R$ 250,00
          currency: 'BRL',
          payment_method: 'apple_pay',
          installments: 1,
          apple_pay: {
            apple_pay_token: JSON.stringify(event.payment),
            statement_descriptor: 'MINHA LOJA',
            capture: true
          }
        }
      })
    });

    const result = await response.json();
    
    if (result.payment?.status === 'paid' || result.payment?.status === 'authorized') {
      session.completePayment(ApplePaySession.STATUS_SUCCESS);
    } else {
      session.completePayment(ApplePaySession.STATUS_FAILURE);
    }
  } catch (error) {
    console.error('Erro ao processar pagamento:', error);
    session.completePayment(ApplePaySession.STATUS_FAILURE);
  }
};

Estrutura da Resposta

Quando o pagamento é bem-sucedido, a API retorna HTTP 201 com:

{
  "id": "ord_abc123",
  "hash": "xyz789",
  "status": "paid",
  "is_closed": false,
  "payment": {
    "id": "pay_abc123",
    "hash": null,
    "merchant_reference": "ORDER-123",
    "status": "paid",
    "payment_method": "apple_pay",
    "amount": 25000,
    "installments": 1,
    "currency": "BRL",
    "description": "Compra via Apple Pay",
    "bank_slip": null,
    "credit_card": null,
    "pix": null,
    "pix_recurring": null,
    "google_pay": null,
    "apple_pay": {
      "statement_descriptor": "MINHA LOJA",
      "capture": true,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "three_ds": null,
      "brand": "visa",
      "last_4": "1234",
      "card_type": "credit"
    },
    "refused_reason": null,
    "return_code": null,
    "created_at": "2024-01-15 13:30:00",
    "updated_at": "2024-01-15 13:30:03"
  },
  "fee": {
    "fixed_fee_amount": 0,
    "platform_fee_percentage": 0,
    "platform_fee_amount": 0
  },
  "customer": {
    "id": "cus_abc123",
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  }
}

Salvamento Automático de Carteira Digital: A Autorizou salva automaticamente a carteira digital após o primeiro pagamento bem-sucedido. O campo apple_pay.id na resposta contém o UUID da carteira digital que pode ser usado em cobranças futuras.

Cobranças Recorrentes com Apple Pay

Para cobranças recorrentes, você pode usar o digital_wallet_uuid salvo anteriormente, sem precisar solicitar o token Apple Pay novamente:

// Cobrança recorrente - sem necessidade de Apple Pay Session
const response = await fetch('https://zeus-sandbox.autorizou.dev/api/v1/charges/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_TOKEN_API',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Cobrança recorrente',
    code: 'ORDER-456',
    mcc: '5411',
    customer: {
      id: 12345,
      name: 'João Silva',
      email: 'joao@exemplo.com.br'
    },
    payment: {
      amount: 25000,
      currency: 'BRL',
      payment_method: 'apple_pay',
      installments: 1,
      apple_pay: {
        digital_wallet_uuid: '550e8400-e29b-41d4-a716-446655440000', // UUID salvo anteriormente
        statement_descriptor: 'MINHA LOJA',
        capture: true
      }
    }
  })
});

Documentação completa: Veja todos os parâmetros disponíveis e mais exemplos na documentação de criação de pedidos com Apple Pay.

Testes

Ambiente Sandbox

Para testar Apple Pay em sandbox:

Use um dispositivo Apple real (simulador não suporta Apple Pay)
Adicione cartões de teste na Wallet do dispositivo:
- Acesse Settings → Wallet & Apple Pay → Add Card
- Use cartões de teste da sua conta sandbox da Apple

Apple Pay não funciona em simuladores. Você precisa de um dispositivo físico (iPhone, iPad, Mac com Touch ID, ou Apple Watch).

Cartões de Teste Sandbox

Use os cartões de teste fornecidos pela Apple no sandbox:

Bandeira	Número	CVV	Validade
Visa	4761 1200 1000 0492	Qualquer	Futuro
Mastercard	5204 2477 5000 1471	Qualquer	Futuro
Amex	3782 822463 10005	Qualquer	Futuro

Troubleshooting

Erro: “Apple Pay not available”

Causa: Dispositivo ou navegador não suporta Apple Pay Solução:

Use Safari em dispositivo Apple
Verifique se há cartões configurados na Wallet
Confirme que o domínio está servindo via HTTPS

Erro: “Merchant validation failed”

Causa: Domínio não foi registrado pela Autorizou ou arquivo de verificação não está acessível Solução:

Confirme que você forneceu o domínio ao suporte da Autorizou

Verifique que o arquivo de verificação está acessível via HTTPS:

curl -I https://seu-dominio/.well-known/apple-developer-merchantid-domain-association.txt

Certifique-se de que retorna HTTP 200
Se persistir, entre em contato com o suporte da Autorizou

Erro: “Domain not verified”

Causa: Arquivo de associação de domínio não está acessível Solução:

Verifique se o arquivo está em:

https://seu-dominio/.well-known/apple-developer-merchantid-domain-association.txt

Teste o acesso:

curl -I https://seu-dominio/.well-known/apple-developer-merchantid-domain-association.txt

Deve retornar 200 OK sem autenticação
Certifique-se de que não há regras de firewall bloqueando o acesso

Token Apple Pay não está correto

Causa: Token Apple Pay pode estar malformado ou com o objeto errado Solução:

Certifique-se de passar o objeto event.payment completo (não event.payment.token)
Use JSON.stringify() ao enviar para a API
Verifique se não há caracteres especiais corrompendo o JSON

Estrutura esperada do apple_pay_token: O campo deve receber o JSON.stringify(event.payment), que é o objeto ApplePayPayment completo:

{
  "token": {
    "paymentData": {
      "version": "EC_v1",
      "data": "base64_encoded_data...",
      "signature": "signature_string...",
      "header": {
        "ephemeralPublicKey": "key...",
        "publicKeyHash": "hash...",
        "transactionId": "transaction_id..."
      }
    },
    "paymentMethod": {
      "displayName": "Visa 1234",
      "network": "Visa",
      "type": "credit"
    },
    "transactionIdentifier": "unique_transaction_id"
  },
  "billingContact": {},
  "shippingContact": {}
}

A API extrai e processa internamente o campo token.paymentData. O objeto deve conter obrigatoriamente:

token.paymentData - Dados criptografados do pagamento
token.paymentMethod - Informações do método de pagamento
token.transactionIdentifier - Identificador único da transação

Recursos Adicionais

Apple Pay JS API

Documentação oficial da Apple

Human Interface Guidelines

Guia de design para Apple Pay

Validar Sessão

Endpoint de validação de sessão

Criar Pedido

Criar pedido com Apple Pay

Checklist de Implementação

Configuração Inicial

Domínio fornecido ao suporte da Autorizou
Arquivo de verificação recebido da Autorizou
Arquivo hospedado em /.well-known/apple-developer-merchantid-domain-association.txt
Arquivo acessível via HTTPS e retornando HTTP 200
Confirmação da Autorizou que domínio foi validado com sucesso

Integração Frontend

Botão Apple Pay implementado no checkout
Verificação de disponibilidade do Apple Pay funcionando
Fluxo de validação de sessão implementado
Fluxo de autorização de pagamento implementado
Tratamento de erros implementado

Testes

Testado em sandbox com cartões de teste
Validação de sessão funcionando corretamente
Pagamentos sendo processados com sucesso
Webhooks recebendo notificações corretamente
Testado em diferentes dispositivos Apple (iPhone, iPad, Mac)

Produção

Certificado SSL válido no domínio de checkout
Testado com transações reais em ambiente de produção
Monitoramento e logs configurados
Tratamento de exceções robusto
Experiência do usuário validada

Próximos Passos

Após configurar o Apple Pay:

Configurar webhooks para notificações em tempo real
Consultar detalhes do pagamento
Processar estornos quando necessário
Implementar assinaturas com Apple Pay

​Visão Geral

Sem Certificados

Sem Apple Developer

Setup Rápido

​Benefícios

​Como Funciona

​Requisitos

Domínio HTTPS

Acesso ao Servidor

Dispositivo Apple

Conta Autorizou Ativa

​Passo 1: Solicitar Habilitação do Apple Pay

​1.1 Solicitar Registro do Seu Domínio

​1.2 Receber Arquivo de Verificação

​1.3 Hospedar Arquivo de Verificação

​1.4 Confirmar com Autorizou

​Passo 2: Integração Frontend

​2.1 Adicionar Botão Apple Pay

​2.2 Validar Sessão do Merchant

​Passo 3: Processar Pagamento na API

​Parâmetros do Payload

​Exemplo de Requisição

​Estrutura da Resposta

​Cobranças Recorrentes com Apple Pay

​Testes

​Ambiente Sandbox

​Cartões de Teste Sandbox

​Troubleshooting

​Erro: “Apple Pay not available”

​Erro: “Merchant validation failed”

​Erro: “Domain not verified”

​Token Apple Pay não está correto

​Recursos Adicionais

Apple Pay JS API

Human Interface Guidelines

Validar Sessão

Criar Pedido

​Checklist de Implementação

​Configuração Inicial

​Integração Frontend

​Testes

​Produção

​Próximos Passos

Visão Geral

Benefícios

Como Funciona

Requisitos

Passo 1: Solicitar Habilitação do Apple Pay

1.1 Solicitar Registro do Seu Domínio

1.2 Receber Arquivo de Verificação

1.3 Hospedar Arquivo de Verificação

1.4 Confirmar com Autorizou

Passo 2: Integração Frontend

2.1 Adicionar Botão Apple Pay

2.2 Validar Sessão do Merchant

Passo 3: Processar Pagamento na API

Parâmetros do Payload

Exemplo de Requisição

Estrutura da Resposta

Cobranças Recorrentes com Apple Pay

Testes

Ambiente Sandbox

Cartões de Teste Sandbox

Troubleshooting

Erro: “Apple Pay not available”

Erro: “Merchant validation failed”

Erro: “Domain not verified”

Token Apple Pay não está correto

Recursos Adicionais

Checklist de Implementação

Configuração Inicial

Integração Frontend

Testes

Produção

Próximos Passos