> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autorizou.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagamentos com Apple Pay

> Como aceitar pagamentos Apple Pay através da API Autorizou

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

<CardGroup cols={3}>
  <Card title="Sem Certificados" icon="check">
    Não precisa gerar ou gerenciar certificados Apple
  </Card>

  <Card title="Sem Apple Developer" icon="check">
    Não precisa ter conta Apple Developer
  </Card>

  <Card title="Setup Rápido" icon="check">
    Apenas forneça domínio e hospede 1 arquivo
  </Card>
</CardGroup>

### 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:**

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

**Fluxo de Pagamento:**

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

<Info>
  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.
</Info>

### Requisitos

<CardGroup cols={2}>
  <Card title="Domínio HTTPS" icon="lock">
    Obrigatório - Apple exige SSL válido
  </Card>

  <Card title="Acesso ao Servidor" icon="server">
    Para hospedar arquivo de verificação
  </Card>

  <Card title="Dispositivo Apple" icon="mobile">
    Para testar (não funciona em simulador)
  </Card>

  <Card title="Conta Autorizou Ativa" icon="credit-card">
    Com método Apple Pay habilitado
  </Card>
</CardGroup>

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

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

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

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](mailto:suporte@autorizou.com.br)
* Chat no dashboard
* WhatsApp Business (disponível no dashboard)

**Forneça as seguintes informações:**

<ParamField body="domain" type="string" required>
  Domínio onde você vai aceitar pagamentos Apple Pay

  **Exemplo:** `checkout.sualoja.com.br` ou `www.sualoja.com.br`

  **Importante:** Deve ser o domínio exato onde o botão Apple Pay será exibido
</ParamField>

<ParamField body="business_name" type="string" required>
  Nome da sua empresa/loja que aparecerá no Apple Pay

  **Exemplo:** "Minha Loja" ou "Loja ABC"
</ParamField>

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

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

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

<Steps>
  <Step title="Crie o diretório .well-known">
    No seu servidor web, crie o diretório `.well-known` na raiz do domínio
  </Step>

  <Step title="Coloque o arquivo">
    Copie o arquivo `apple-developer-merchantid-domain-association.txt` para dentro do diretório `.well-known`
  </Step>

  <Step title="Configure permissões">
    Certifique-se de que o arquivo tem permissões de leitura (644) e está acessível via HTTPS
  </Step>

  <Step title="Teste o acesso">
    Acesse a URL completa no navegador e confirme que o arquivo é baixado sem erros
  </Step>
</Steps>

**Requisitos técnicos:**

<Check>✓ Arquivo acessível via **HTTPS** (não HTTP)</Check>
<Check>✓ Retorna status **HTTP 200 OK**</Check>
<Check>✓ Sem autenticação necessária (acesso público)</Check>
<Check>✓ Content-Type correto (geralmente `text/plain` ou `application/octet-stream`)</Check>

**Validar configuração:**

```bash Terminal theme={null}
# 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
# ...
```

<Warning>
  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.
</Warning>

### 1.4 Confirmar com Autorizou

Após hospedar o arquivo:

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

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

## 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 HTML theme={null}
<apple-pay-button 
  buttonstyle="black" 
  type="buy" 
  locale="pt-BR"
></apple-pay-button>
```

<Info>
  **Documentação completa:** Consulte o [guia oficial da Apple](https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons) para implementação detalhada do botão e opções de customização.
</Info>

### 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 JavaScript theme={null}
// No evento onvalidatemerchant do ApplePaySession
session.onvalidatemerchant = async (event) => {
  try {
    // Chamar endpoint de validação da Autorizou
    const response = await fetch('https://pay.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`)

<Note>
  Para ver a documentação completa da validação de sessão, incluindo tratamento de erros, consulte [Validar Sessão Apple Pay](/api-reference/payments/apple-pay-validate-session).
</Note>

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

<ParamField body="payment.apple_pay.apple_pay_token" type="string" required>
  Token obtido de `event.payment` do evento `onpaymentauthorized` do `ApplePaySession`

  **Importante:** 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:**

  ```javascript theme={null}
  apple_pay_token: JSON.stringify(event.payment)
  ```
</ParamField>

<ParamField body="payment.apple_pay.statement_descriptor" type="string" required>
  Nome que aparece na fatura do cartão

  **Máximo:** 22 caracteres

  **Exemplo:** `MINHA LOJA`
</ParamField>

<ParamField body="payment.apple_pay.capture" type="boolean" required>
  Se deve capturar automaticamente o pagamento

  **Valores:** `true` (captura imediata), `false` (captura manual posterior)
</ParamField>

<ParamField body="payment.apple_pay.capture_delay_hours" type="integer">
  Horas de atraso para captura automática

  **Obrigatório se:** `capture = false`

  **Mínimo:** 0 | **Máximo:** 168 (7 dias)
</ParamField>

### Exemplo de Requisição

```javascript theme={null}
// No evento onpaymentauthorized
session.onpaymentauthorized = async (event) => {
  try {
    const response = await fetch('https://pay.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:

```json theme={null}
{
  "id": "7a4e9c23-6f8b-4d1a-92c5-3b7e6a9d4f18",
  "hash": "AUTOAP01JZX3Y5T4Q8KWVREGH2M9SH",
  "status": "paid",
  "is_closed": true,
  "payment": {
    "id": "c92d5b47-3e8a-4f6c-b174-9a2e5c8b3d61",
    "hash": "AUTPAP01JZX3Y5T4Q8KWVREGH2M9SJ",
    "merchant_reference": "ORDER-123",
    "status": "authorized",
    "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": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  }
}
```

<Check>
  **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.
</Check>

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

```javascript theme={null}
// Cobrança recorrente - sem necessidade de Apple Pay Session
const response = await fetch('https://pay.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
      }
    }
  })
});
```

<Info>
  **Documentação completa:** Veja todos os parâmetros disponíveis e mais exemplos na [documentação de criação de pedidos com Apple Pay](/api-reference/charges/orders/create-order#pagamento-com-apple-pay).
</Info>

## Testes

### Ambiente Sandbox

Para testar Apple Pay em sandbox:

1. **Use um dispositivo Apple real** (simulador não suporta Apple Pay)
2. **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

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

### 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:**

1. Confirme que você forneceu o domínio ao suporte da Autorizou
2. Verifique que o arquivo de verificação está acessível via HTTPS:
   ```bash theme={null}
   curl -I https://seu-dominio/.well-known/apple-developer-merchantid-domain-association.txt
   ```
3. Certifique-se de que retorna HTTP 200
4. 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:**

1. Verifique se o arquivo está em:
   ```
   https://seu-dominio/.well-known/apple-developer-merchantid-domain-association.txt
   ```
2. Teste o acesso:
   ```bash theme={null}
   curl -I https://seu-dominio/.well-known/apple-developer-merchantid-domain-association.txt
   ```
3. Deve retornar `200 OK` sem autenticação
4. 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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Apple Pay JS API" icon="book" href="https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api">
    Documentação oficial da Apple
  </Card>

  <Card title="Human Interface Guidelines" icon="paintbrush" href="https://developer.apple.com/design/human-interface-guidelines/apple-pay">
    Guia de design para Apple Pay
  </Card>

  <Card title="Validar Sessão" icon="api" href="/api-reference/payments/apple-pay-validate-session">
    Endpoint de validação de sessão
  </Card>

  <Card title="Criar Pedido" icon="shopping-cart" href="/api-reference/charges/orders/create-order#pagamento-com-apple-pay">
    Criar pedido com Apple Pay
  </Card>
</CardGroup>

## 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 pagamentos 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:

1. [Configurar webhooks](/api-reference/webhooks/webhook-configuration) para notificações em tempo real
2. [Consultar detalhes do pagamento](/api-reference/charges/payments/get-payment)
3. [Processar estornos](/api-reference/refunds/create-refund) quando necessário
4. [Implementar assinaturas](/api-reference/subscriptions/create-subscription) com Apple Pay