> ## 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 Recorrentes com Pix

> Como configurar e processar cobranças recorrentes via Pix através da API Autorizou

## Visão Geral

O Pix Recorrente permite que você configure cobranças periódicas automáticas usando Pix como meio de pagamento. Seus clientes autorizam a recorrência uma única vez e os pagamentos subsequentes são processados automaticamente.

<CardGroup cols={3}>
  <Card title="Autorização Única" icon="check">
    Cliente autoriza uma vez via QR Code
  </Card>

  <Card title="Cobranças Automáticas" icon="check">
    Pagamentos processados automaticamente
  </Card>

  <Card title="Gestão Simplificada" icon="check">
    Sem necessidade de novo QR Code a cada cobrança
  </Card>
</CardGroup>

### Benefícios

* **Redução de inadimplência** - Cobranças automáticas sem ação do cliente
* **Melhor experiência** - Cliente autoriza apenas uma vez
* **Flexibilidade** - Suporte para trial, cobranças mensais, anuais, etc.
* **Menor custo** - Taxas Pix geralmente menores que cartão de crédito

### Como Funciona

**Fluxo de Autorização Inicial:**

1. **Você** cria uma assinatura via API com `payment_method: pix_recurring`
2. **API** retorna um QR Code Pix para autorização
3. **Cliente** escaneia o QR Code com app bancário
4. **Cliente** autoriza a recorrência (e paga primeira cobrança se sem trial)
5. **Sistema** processa e armazena token de recorrência
6. **Pronto!** Cobranças futuras serão automáticas

**Fluxo de Cobranças Recorrentes:**

1. **Sistema** agenda cobrança 3 dias antes da data
2. **Sistema** processa a cobrança 2 dias antes da data
3. **Gateway** processa cobrança na data agendada
4. **Webhook** notifica sucesso ou falha da cobrança

<Info>
  A Autorizou gerencia automaticamente todo o ciclo de vida das cobranças: agendamento, processamento, retentativas e notificações via webhook.
</Info>

## Jornadas de Pagamento

O Pix Recorrente suporta duas jornadas distintas:

### Journey 2 (J2) - Com Período de Trial

Para assinaturas que oferecem período de teste gratuito:

<Steps>
  <Step title="Criar assinatura com trial_days">
    Configure `trial_days` no endpoint de criação de assinatura
  </Step>

  <Step title="Cliente autoriza recorrência">
    Cliente escaneia QR Code - **sem pagamento imediato**
  </Step>

  <Step title="Período de trial inicia">
    Assinatura muda para status `TRIAL_STARTED` automaticamente
  </Step>

  <Step title="Primeira cobrança ao fim do trial">
    Sistema processa primeiro pagamento após trial\_days
  </Step>

  <Step title="Cobranças periódicas">
    Pagamentos subsequentes processados automaticamente
  </Step>
</Steps>

**Exemplo: Assinatura com 7 dias de trial**

```
Dia 0: Cliente autoriza (sem pagar) → TRIAL_STARTED
Dia 7: Primeira cobrança automática → PAYMENT_APPROVED
Dia 37: Segunda cobrança (mensal) → PAYMENT_APPROVED
...
```

### Journey 3 (J3) - Sem Trial (Pagamento Imediato)

Para assinaturas que cobram imediatamente:

<Steps>
  <Step title="Criar assinatura sem trial_days">
    Configure `trial_days` como 0
  </Step>

  <Step title="Cliente autoriza e paga">
    Cliente escaneia QR Code - **pagamento imediato**
  </Step>

  <Step title="Primeira cobrança confirmada">
    Assinatura muda para `PAYMENT_APPROVED` após webhook
  </Step>

  <Step title="Cobranças periódicas">
    Pagamentos subsequentes processados automaticamente
  </Step>
</Steps>

**Exemplo: Assinatura mensal sem trial**

```
Dia 0: Cliente paga primeira cobrança → PAYMENT_APPROVED
Dia 30: Segunda cobrança automática → PAYMENT_APPROVED
Dia 60: Terceira cobrança automática → PAYMENT_APPROVED
...
```

## Status do Ciclo de Vida

### Status da Subscription

| Status             | Significado                       | Quando Ocorre                                   |
| ------------------ | --------------------------------- | ----------------------------------------------- |
| `PAYMENT_PENDING`  | Aguardando autorização do cliente | Após criação, antes do cliente escanear QR Code |
| `TRIAL_STARTED`    | Período de trial ativo            | Após autorização em J2 (com trial)              |
| `PAYMENT_APPROVED` | Assinatura ativa e em dia         | Após confirmação de pagamento                   |
| `PAYMENT_REFUSED`  | Última cobrança falhou            | Após falha em cobrança recorrente               |
| `TRIAL_ENDED`      | Trial finalizado                  | Ao fim do período de trial                      |
| `CANCELED`         | Assinatura cancelada              | Após chamada ao endpoint de cancelamento        |

### Status do Payment

| Status            | Significado                           | Quando Ocorre                                                           |
| ----------------- | ------------------------------------- | ----------------------------------------------------------------------- |
| `SCHEDULED`       | Pagamento agendado, ainda não enviado | Criado pelo sistema inicialmente na J2 e 3 dias antes da cobrança na J3 |
| `WAITING_PAYMENT` | Aguardando confirmação do gateway     | Após envio para gateway (2 dias antes) ou QR Code J3                    |
| `AUTHORIZED`      | Pagamento confirmado e concluído      | Após confirmação via webhook                                            |
| `REFUSED`         | Pagamento recusado                    | Após falha na cobrança                                                  |

### Fluxo de Status - Journey 2 (Com Trial)

```mermaid theme={null}
graph LR
    A[PAYMENT_PENDING] --> B[TRIAL_STARTED]
    B --> C[TRIAL_ENDED]
    C --> D[PAYMENT_APPROVED]
    D --> E[PAYMENT_REFUSED]
    E --> D
    D --> F[CANCELED]
    E --> F
```

**Pagamentos J2:**

```
Payment #1: SCHEDULED → WAITING_PAYMENT → AUTHORIZED
Payment #2: SCHEDULED → WAITING_PAYMENT → AUTHORIZED
...
```

### Fluxo de Status - Journey 3 (Sem Trial)

```mermaid theme={null}
graph LR
    A[PAYMENT_PENDING] --> B[PAYMENT_APPROVED]
    B --> C[PAYMENT_REFUSED]
    C --> B
    B --> D[CANCELED]
    C --> D
```

**Pagamentos J3:**

```
Payment #1: WAITING_PAYMENT → AUTHORIZED
Payment #2: SCHEDULED → WAITING_PAYMENT → AUTHORIZED
...
```

## Criando Assinatura com Pix Recorrente

### Endpoint

`POST /api/v1/subscriptions`

### Parâmetros Principais

<ParamField body="mcc" type="string" required>
  Merchant Category Code - Código de categoria do estabelecimento
</ParamField>

<ParamField body="code" type="string" required>
  Código identificador único da assinatura (gerado pelo seu sistema)
</ParamField>

<ParamField body="description" type="string">
  Descrição da assinatura
</ParamField>

<ParamField body="notification_url" type="string">
  URL para recebimento de webhooks
</ParamField>

<ParamField body="offer_id" type="string">
  UUID de uma [oferta recorrente](/api-reference/products/create-offer) (opcional). Quando fornecido, a assinatura herda a régua de preços e o intervalo da oferta.
</ParamField>

<ParamField body="interval" type="string" required>
  Intervalo de cobrança

  **Valores:** `weekly`, `monthly`, `yearly`

  **Nota:** Autorizou suporta apenas esses três intervalos. Não há suporte para `interval_count` ou intervalos customizados.
</ParamField>

<ParamField body="trial_days" type="integer" default={0}>
  Dias de trial gratuito (0 = sem trial, J3)

  **Journey 2:** `trial_days > 0`

  **Journey 3:** `trial_days = 0`
</ParamField>

<ParamField body="customer" type="object" required>
  Objeto com dados do cliente

  <Expandable title="Propriedades">
    <ParamField body="customer.id" type="string" required>
      ID do cliente (UUID)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="payment" type="object" required>
  Objeto com dados do pagamento

  <Expandable title="Propriedades">
    <ParamField body="payment.amount" type="integer" required>
      Valor da primeira cobrança em centavos (ex: 500 = R\$ 5,00)

      **Journey 2:** `amount = 0` (sem cobrança no trial)

      **Journey 3:** `amount = 500` (cobrança imediata)
    </ParamField>

    <ParamField body="payment.currency" type="string" default="BRL">
      Moeda (sempre BRL para Pix)
    </ParamField>

    <ParamField body="payment.payment_method" type="string" required>
      Método de pagamento

      **Valor:** `pix_recurring`
    </ParamField>

    <ParamField body="payment.installments" type="integer" default={1}>
      Número de parcelas (sempre 1 para Pix Recorrente)
    </ParamField>

    <ParamField body="payment.pix_recurring" type="object" required>
      Configurações específicas do Pix Recorrente

      <Expandable title="Propriedades">
        <ParamField body="payment.pix_recurring.recurring_statement" type="string" required>
          Texto que aparecerá no extrato bancário do cliente
        </ParamField>

        <ParamField body="payment.pix_recurring.recurring_amount" type="integer" required>
          Valor das cobranças recorrentes em centavos (ex: 500 = R\$ 5,00)
        </ParamField>

        <ParamField body="payment.pix_recurring.starts_at" type="string" required>
          Data de início da cobrança recorrente (formato: YYYY-MM-DD)
        </ParamField>

        <ParamField body="payment.pix_recurring.ends_at" type="string">
          Data de fim da cobrança recorrente (formato: YYYY-MM-DD)

          **Nota:** Deixe vazio para assinaturas sem data de término
        </ParamField>

        <ParamField body="payment.pix_recurring.retry_policy" type="boolean" default={true}>
          Se habilitado, tentará reprocessar cobranças que falharem
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Exemplo: Assinatura Mensal com 7 dias de Trial (J2)

```bash cURL theme={null}
curl --request POST \
  --url https://pay.autorizou.dev/api/v1/subscriptions \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "mcc": "5734",
    "code": "PIX_AUTO_J2_20251114_001",
    "description": "Plano Pro - Mensal com Trial",
    "notification_url": "https://seu-webhook.com/autorizou/notifications",
    "interval": "monthly",
    "trial_days": 7,
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "payment": {
      "amount": 0,
      "currency": "BRL",
      "payment_method": "pix_recurring",
      "installments": 1,
      "pix_recurring": {
        "recurring_statement": "Plano Pro",
        "recurring_amount": 4990,
        "starts_at": "2025-11-21",
        "ends_at": null,
        "retry_policy": true
      }
    }
  }'
```

### Exemplo: Assinatura Mensal sem Trial (J3)

```bash cURL theme={null}
curl --request POST \
  --url https://pay.autorizou.dev/api/v1/subscriptions \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "mcc": "5734",
    "code": "PIX_AUTO_J3_20251114_001",
    "description": "Plano Pro - Mensal",
    "notification_url": "https://seu-webhook.com/autorizou/notifications",
    "interval": "monthly",
    "trial_days": 0,
    "customer": {
      "id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "payment": {
      "amount": 4990,
      "currency": "BRL",
      "payment_method": "pix_recurring",
      "installments": 1,
      "pix_recurring": {
        "recurring_statement": "Plano Pro",
        "recurring_amount": 4990,
        "starts_at": "2025-12-14",
        "ends_at": null,
        "retry_policy": true
      }
    }
  }'
```

**Resposta J2 (Com Trial):**

```json theme={null}
{
  "id": "7de7f055-47db-4249-ae09-d23a0e7475ad",
  "hash": null,
  "status": "payment_pending",
  "interval": "monthly",
  "next_charge_amount": 2990,
  "installments": 1,
  "next_charge_at": "2025-11-21 00:00:00",
  "start_at": "2025-11-14",
  "end_at": null,
  "trial_days": 7,
  "current_cycle": 0,
  "payment": {
    "id": "7de7f055-47db-4249-ae09-d23a0e7475ad",
    "status": "scheduled",
    "payment_method": "pix_recurring",
    "amount": 0,
    "currency": "BRL",
    "description": "PIX Automático - Journey 2 (Trial)",
    "metadata": {
      "action": {
        "paymentMethodType": "pix",
        "type": "qrCode",
        "qrCodeData": "00020126180014br.gov.bcb.pix..."
      }
    },
    "pix_recurring": {
      "qr_code": "00020126180014br.gov.bcb.pix5204000053039865802BR...",
      "expires_at": null,
      "charge_code": null,
      "recurring_statement": "Assinatura Premium",
      "starts_at": "2025-11-14",
      "ends_at": null,
      "retry_policy": true,
      "recurring_amount": 2990,
      "acquirer_reference": "Q966DNR2M6ZDKQV5"
    },
    "created_at": "2025-11-14 09:29:29"
  },
  "fee": {
    "fixed_fee_amount": 100,
    "platform_fee_percentage": 2.99,
    "platform_fee_amount": 0
  },
  "customer": {
    "id": "ae03951a-c789-45f5-8fb0-77b35639785e",
    "name": "teste pix",
    "email": "testepix1@autorizou.com.br"
  }
}
```

**Resposta J3 (Sem Trial):**

```json theme={null}
{
  "id": "ae8ca40e-e4b2-441b-838b-df71369fd8ba",
  "hash": null,
  "status": "payment_pending",
  "interval": "monthly",
  "next_charge_amount": 2890,
  "installments": 1,
  "next_charge_at": "2025-12-14 00:00:00",
  "start_at": "2025-11-14",
  "end_at": null,
  "trial_days": 0,
  "current_cycle": 1,
  "payment": {
    "id": "ae8ca40e-e4b2-441b-838b-df71369fd8ba",
    "status": "waiting_payment",
    "payment_method": "pix_recurring",
    "amount": 2890,
    "currency": "BRL",
    "description": "PIX Automático - Journey 3 (Pagamento Imediato)",
    "metadata": {
      "action": {
        "paymentMethodType": "pix",
        "type": "qrCode",
        "qrCodeData": "00020101021226970014br.gov.bcb.pix..."
      }
    },
    "pix_recurring": {
      "qr_code": "00020101021226970014br.gov.bcb.pix2575pix-qrcode.gateway.com/location/...",
      "expires_at": null,
      "charge_code": null,
      "recurring_statement": "Assinatura Premium",
      "starts_at": "2025-11-14",
      "ends_at": null,
      "retry_policy": true,
      "recurring_amount": 2890,
      "acquirer_reference": "BLML9LR2M6ZDKQV5"
    },
    "created_at": "2025-11-14 09:25:12"
  },
  "fee": {
    "fixed_fee_amount": 100,
    "platform_fee_percentage": 2.99,
    "platform_fee_amount": 87
  },
  "customer": {
    "id": "ae03951a-c789-45f5-8fb0-77b35639785e",
    "name": "teste pix",
    "email": "testepix1@autorizou.com.br"
  }
}
```

<Info>
  **QR Code:** O QR Code para autorização inicial está disponível em `payment.pix_recurring.qr_code`. Cliente deve escanear para autorizar a recorrência.
</Info>

### Diferenças entre J2 e J3

| Campo                     | Journey 2 (Trial)           | Journey 3 (Sem Trial)   |
| ------------------------- | --------------------------- | ----------------------- |
| `trial_days`              | `7` (ou > 0)                | `0`                     |
| `current_cycle`           | `0`                         | `1`                     |
| `payment.status`          | `scheduled`                 | `waiting_payment`       |
| `payment.amount`          | `0`                         | `2890` (valor real)     |
| `fee.platform_fee_amount` | `0` (sem cobrança no trial) | `87` (taxa sobre valor) |

**Campos importantes da resposta:**

* `id` - ID da assinatura (UUID)
* `status` - Status atual (`payment_pending`, `trial_started`, `payment_approved`, etc.)
* `trial_days` - Dias de trial (0 = J3, >0 = J2)
* `current_cycle` - Ciclo atual (0 = ainda não cobrou, 1+ = já cobrou)
* `next_charge_at` - Data/hora da próxima cobrança
* `payment.status` - `scheduled` (J2) ou `waiting_payment` (J3)
* `payment.amount` - `0` (J2) ou valor real (J3)
* `payment.pix_recurring.qr_code` - QR Code para o cliente escanear
* `payment.pix_recurring.charge_code` - Token de recorrência (preenchido após autorização)
* `payment.pix_recurring.acquirer_reference` - Referência do gateway de pagamento
* `fee` - Informações de taxas da plataforma

## Timing de Processamento

A Autorizou processa cobranças Pix Recorrente seguindo janelas específicas para garantir conformidade com requisitos do gateway de pagamento:

### Constantes de Timing

<CodeGroup>
  ```text Timing Configuration theme={null}
  DAYS_BEFORE_TO_CREATE_SCHEDULED = 3 dias
  DAYS_BEFORE_TO_PROCESS = 2 dias
  MIN_DAYS_BEFORE_DUE = 2 dias
  MAX_DAYS_BEFORE_DUE = 10 dias
  ```
</CodeGroup>

### Linha do Tempo de Processamento

Exemplo para cobrança agendada para **10 de Novembro**:

```
┌────────────────┬──────────────────────────────────────────────────────┐
│ Data           │ Evento                                               │
├────────────────┼──────────────────────────────────────────────────────┤
│ 07 Nov (D-3)   │ Sistema agenda Payment com status SCHEDULED         │
│ 08 Nov (D-2)   │ Sistema processa e envia → WAITING_PAYMENT          │
│ 10 Nov (D-Day) │ Gateway processa cobrança → AUTHORIZED              │
└────────────────┴──────────────────────────────────────────────────────┘
```

### Processamento Automatizado

A Autorizou executa três processos automatizados diariamente:

<AccordionGroup>
  <Accordion title="Agendamento de Pagamentos - 02:00 AM" icon="calendar">
    **Responsabilidade:** Criar pagamentos `SCHEDULED` 3 dias antes da cobrança

    **O que faz:**

    * Busca assinaturas com `next_charge_at` em 3 dias
    * Verifica se já existe payment `SCHEDULED` para aquela data
    * Se não existe, cria novo payment com status `SCHEDULED`
    * Se já existe, não faz nada (rede de segurança)
  </Accordion>

  <Accordion title="Processamento de Pagamentos - 04:00 AM" icon="paper-plane">
    **Responsabilidade:** Enviar payments `SCHEDULED` para gateway 2 dias antes

    **O que faz:**

    * Busca payments com status `SCHEDULED` e `billing_date` em 2 dias
    * Valida que subscription ainda está ativa
    * Muda status: `SCHEDULED` → `WAITING_PAYMENT`
    * Envia requisição para o gateway de pagamento
    * Aguarda confirmação via webhook
  </Accordion>

  <Accordion title="Processamento de Pagamentos Atrasados - 06:00 AM" icon="rotate">
    **Responsabilidade:** Retentar payments com status `REFUSED`

    **O que faz:**

    * Busca payments `REFUSED` de Pix Recorrente
    * Verifica se `retry_attempts < 3`
    * Cria novo payment `SCHEDULED` com nova data
    * Aguarda processamento pelos outros processos automatizados
    * Máximo de 3 tentativas em 7 dias
  </Accordion>
</AccordionGroup>

## Webhooks

A Autorizou envia webhooks para notificar eventos importantes do ciclo de vida das assinaturas:

### Eventos de Subscription

| Evento                     | Quando Ocorre         | Dados Incluídos                 |
| -------------------------- | --------------------- | ------------------------------- |
| `subscription.created`     | Assinatura criada     | subscription completa           |
| `subscription.updated`     | Assinatura atualizada | subscription + campos alterados |
| `subscription.inactivated` | Assinatura inativada  | subscription + motivo           |
| `subscription.deleted`     | Assinatura deletada   | subscription + deleted\_at      |

### Eventos de Payment

| Evento                    | Quando Ocorre             | Dados Incluídos           |
| ------------------------- | ------------------------- | ------------------------- |
| `payment.scheduled`       | Payment agendado          | payment + scheduled\_for  |
| `payment.authorized`      | Pagamento confirmado      | payment + paid\_at        |
| `payment.refused`         | Pagamento recusado        | payment + refusal\_reason |
| `payment.retry_scheduled` | Retry agendado após falha | payment + retry\_attempt  |

### Exemplo de Payload

```json theme={null}
{
  "event": "subscription.updated",
  "type": "subscription",
  "created_at": "2025-11-13 10:00:00",
  "subscription": {
    "id": "c74e2b58-9a1d-4f6e-83c7-5b2e8d4a1f39",
    "status": "payment_approved",
    "interval": "monthly",
    "next_charge_amount": 4990,
    "next_charge_at": "2025-12-13T00:00:00Z"
  }
}
```

<Info>
  Para configurar e testar webhooks, consulte a [documentação completa de webhooks](/api-reference/webhooks/introduction).
</Info>

## Gerenciando Assinaturas

### Cancelar Assinatura

Para cancelar uma assinatura ativa:

**Endpoint:** `POST /api/v1/subscriptions/cancel`

```bash cURL theme={null}
curl --request POST \
  --url https://pay.autorizou.dev/api/v1/subscriptions/cancel \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "subscription_id": "c74e2b58-9a1d-4f6e-83c7-5b2e8d4a1f39"
  }'
```

**Comportamento:**

* Define `canceled_at` com timestamp atual
* Interrompe processamento de cobranças futuras
* Payments `SCHEDULED` não são mais processados
* Envia webhook `subscription.deleted`

<Warning>
  Cancelamento é **irreversível**. Cliente precisará criar nova assinatura para reativar.
</Warning>

### Consultar Assinatura

**Endpoint:** `GET /api/v1/subscriptions/{subscription_id}`

```bash cURL theme={null}
curl --request GET \
  --url https://pay.autorizou.dev/api/v1/subscriptions/sub_abc123 \
  --header 'Authorization: Bearer SEU_TOKEN'
```

### Listar Pagamentos de uma Assinatura

**Endpoint:** `GET /api/v1/subscriptions/{subscription_id}/payments`

```bash cURL theme={null}
curl --request GET \
  --url https://pay.autorizou.dev/api/v1/subscriptions/sub_abc123/payments \
  --header 'Authorization: Bearer SEU_TOKEN'
```

## Tratamento de Falhas

### Política de Retry

Quando uma cobrança falha:

1. **Payment** muda para status `REFUSED`
2. **Subscription** muda para `PAYMENT_REFUSED`
3. **Sistema** agenda retry automático
4. **Máximo 3 tentativas** em janela de 7 dias
5. Após 3 falhas, assinatura permanece `PAYMENT_REFUSED`

### Motivos Comuns de Falha

| Motivo                 | Causa                        | Ação Recomendada                   |
| ---------------------- | ---------------------------- | ---------------------------------- |
| `INSUFFICIENT_FUNDS`   | Saldo insuficiente           | Aguardar retry automático          |
| `EXPIRED_TOKEN`        | Token de recorrência expirou | Cliente deve criar nova assinatura |
| `ACCOUNT_BLOCKED`      | Conta bloqueada              | Cliente deve verificar com banco   |
| `DAILY_LIMIT_EXCEEDED` | Limite diário excedido       | Retry no dia seguinte              |

### Verificando Falhas via Webhook

```json theme={null}
{
  "event": "payment.refused",
  "type": "payment",
  "created_at": "2025-11-13 10:00:00",
  "payment": {
    "id": "d83f5c29-1e6b-4a7d-92f4-6c8a3e5b1d70",
    "status": "refused",
    "refused_reason": "Saldo insuficiente",
    "return_code": "51"
  }
}
```

## Ambiente de Testes

### Sandbox

Use o ambiente sandbox para testar todo o fluxo:

**Base URL:** `https://pay.autorizou.dev/api/v1`

**Como testar:**

1. Use o endpoint `POST /api/v1/subscriptions` conforme documentado acima
2. No campo `payment.payment_method`, use o valor `"pix_recurring"`
3. A API retornará o QR Code em `payment.pix_recurring.qr_code`

```bash theme={null}
# Exemplo de requisição em sandbox
curl --request POST \
  --url https://pay.autorizou.dev/api/v1/subscriptions \
  --header 'Authorization: Bearer SEU_TOKEN_SANDBOX' \
  --header 'Content-Type: application/json' \
  --data '{
    "mcc": "5734",
    "code": "PIX_TEST_001",
    "interval": "monthly",
    "trial_days": 0,
    "customer": {
      "id": "{{CUSTOMER_UUID}}"
    },
    "payment": {
      "amount": 1000,
      "currency": "BRL",
      "payment_method": "pix_recurring",
      "installments": 1,
      "pix_recurring": {
        "recurring_statement": "Teste Assinatura",
        "recurring_amount": 1000,
        "starts_at": "2025-12-14",
        "retry_policy": true
      }
    }
  }'
```

### QR Code de Teste

Em sandbox, o QR Code retornado aponta para ambiente de testes. Portanto, ele não vai funcionar no seu aplicativo bancário.

<Note>
  **Dica de Teste:** Para simular falhas, você pode usar metadados específicos na criação da assinatura. Entre em contato com o suporte para detalhes.
</Note>

## Troubleshooting

### QR Code não gera pagamento

**Causa:** Cliente pode ter escaneado mas não confirmou no app bancário

**Solução:**

1. Verifique se QR Code ainda está válido (30 minutos)
2. Peça ao cliente para confirmar autorização no app
3. Aguarde webhook de confirmação (pode levar alguns segundos)

### Subscription fica em PAYMENT\_PENDING

**Causa:** Cliente não escaneou o QR Code ou autorização não foi processada

**Solução:**

1. Verifique se cliente escaneou o QR Code
2. Confirme que QR Code não expirou
3. Se expirou, crie nova assinatura
4. Verifique logs de webhook para erros

### Payment fica em WAITING\_PAYMENT

**Causa:** Aguardando confirmação do gateway via webhook

**Solução:**

1. Normalmente resolve em alguns segundos
2. Verifique se webhooks estão configurados corretamente
3. Consulte status via `GET /api/v1/payments/{payment_id}`
4. Se persistir por mais de 5 minutos, contate suporte

### Cobranças não processam automaticamente

**Causa:** Processos automatizados não estão executando

**Solução:**

1. Isso é gerenciado pela Autorizou (SaaS)
2. Se detectar atrasos, contate suporte imediatamente
3. Verifique se subscription está ativa (`canceled_at` deve ser null)

## Campos Importantes

Campos principais retornados pela API:

| Campo                           | Descrição                        |
| ------------------------------- | -------------------------------- |
| `payment.acquirer_reference`    | ID único do pagamento no gateway |
| `subscription.charge_code`      | Token de recorrência armazenado  |
| `customer.uuid`                 | Identificador único do cliente   |
| `payment.pix_recurring.qr_code` | QR Code para autorização inicial |

## Recursos Adicionais

<CardGroup cols={2}>
  <Card title="Criar Assinatura" icon="calendar-plus" href="/api-reference/subscriptions/create-subscription">
    Documentação completa do endpoint
  </Card>

  <Card title="Cancelar Assinatura" icon="calendar-xmark" href="/api-reference/subscriptions/cancel-subscription">
    Como cancelar assinaturas
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/introduction">
    Configurar notificações em tempo real
  </Card>

  <Card title="Consultar Pagamento" icon="magnifying-glass" href="/api-reference/charges/payments/get-payment">
    Verificar status de pagamentos
  </Card>
</CardGroup>

## Checklist de Implementação

### Configuração Inicial

* [ ] Conta Autorizou configurada para Pix Recorrente
* [ ] Credenciais de API obtidas (sandbox e produção)
* [ ] Webhooks configurados para receber notificações

### Integração Backend

* [ ] Endpoint de criação de assinatura implementado
* [ ] Endpoint de cancelamento implementado
* [ ] Recebimento de webhooks configurado
* [ ] Tratamento de eventos de pagamento implementado
* [ ] Logs e monitoramento configurados

### Testes

* [ ] Testado criação de assinatura J2 (com trial)
* [ ] Testado criação de assinatura J3 (sem trial)
* [ ] Testado fluxo de autorização via QR Code
* [ ] Testado recebimento de webhooks
* [ ] Testado cancelamento de assinatura
* [ ] Testado falhas e retries

### Produção

* [ ] Testado com pagamentos reais em produção
* [ ] Monitoramento de falhas configurado
* [ ] Processo de suporte ao cliente definido
* [ ] Documentação interna criada

## Próximos Passos

Após implementar Pix Recorrente:

1. [Configurar webhooks](/api-reference/webhooks/introduction) para notificações
2. [Monitorar pagamentos](/api-reference/charges/payments/get-payment) em tempo real
3. [Implementar dashboard](/casos-uso/e-commerce) para gestão de assinaturas
4. [Processar reembolsos](/api-reference/refunds/create-refund) quando necessário