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

# Estrutura dos Payloads

> Entenda a estrutura completa dos dados recebidos nos webhooks

## Estrutura Base

Todos os webhooks enviados pela Autorizou seguem esta estrutura base:

```json theme={null}
{
  "event": "payment.authorized",
  "type": "payment",
  "created_at": "2024-01-15 10:30:00",
  "payment": { /* Objeto Payment */ },
  "customer": { /* Objeto Customer */ },
  "order": { /* Objeto Order (opcional) */ },
  "subscription": { /* Objeto Subscription (opcional) */ }
}
```

<ParamField path="event" type="string">
  Nome do evento que disparou o webhook

  Exemplos: `payment.authorized`, `payment.refused`, `subscription.created`
</ParamField>

<ParamField path="type" type="string">
  Tipo do recurso principal

  Valores: `payment`, `subscription`
</ParamField>

<ParamField path="created_at" type="string">
  Data e hora em que o evento foi criado

  Formato: `Y-m-d H:i:s` (UTC)
</ParamField>

***

## Objeto Payment

Presente em todos os eventos de pagamento.

```json theme={null}
{
  "payment": {
    "id": "d29b6f81-4e7c-4a5d-93f8-1b6d4a8c2e57",
    "merchant_reference": "pedido-789",
    "status": "authorized",
    "payment_method": "credit_card",
    "amount": 10000,
    "installments": 3,
    "currency": "BRL",
    "description": "Compra na loja virtual",
    "metadata": {
      "order_id": "789",
      "customer_note": "Entrega rápida"
    },
    "credit_card": { /* Presente se payment_method = credit_card */ },
    "bank_slip": { /* Presente se payment_method = bank_slip */ },
    "pix": { /* Presente se payment_method = pix */ },
    "return_code": "00",
    "refused_reason": null,
    "split": [ /* Presente se a venda foi dividida */ ],
    "created_at": "15/01/2024 10:30:00",
    "updated_at": "15/01/2024 10:30:15"
  }
}
```

### Campos do Payment

<ResponseField name="id" type="string">
  ID único do pagamento na Autorizou
</ResponseField>

<ResponseField name="merchant_reference" type="string">
  Referência do pagamento no seu sistema
</ResponseField>

<ResponseField name="status" type="string">
  Status atual do pagamento

  Valores: `pending`, `authorized`, `confirmed`, `refused`, `refunded`, `expired`, etc.
</ResponseField>

<ResponseField name="payment_method" type="string">
  Método de pagamento utilizado

  Valores: `credit_card`, `bank_slip`, `pix`
</ResponseField>

<ResponseField name="amount" type="integer">
  Valor em centavos

  Exemplo: `10000` = R\$ 100,00
</ResponseField>

<ResponseField name="installments" type="integer">
  Número de parcelas
</ResponseField>

<ResponseField name="currency" type="string">
  Código da moeda (ISO 4217)

  Exemplo: `BRL`, `USD`
</ResponseField>

<ResponseField name="description" type="string">
  Descrição do pagamento
</ResponseField>

<ResponseField name="metadata" type="object">
  Dados customizados enviados na criação do pagamento
</ResponseField>

<ResponseField name="return_code" type="string">
  Código de retorno da adquirente (quando disponível)
</ResponseField>

<ResponseField name="refused_reason" type="string">
  Motivo da recusa (quando aplicável)
</ResponseField>

<ResponseField name="split" type="array">
  A divisão **realizada** da venda — presente quando a venda foi dividida (split enviado por você ou
  resolvido pela config da conta). Cada item é uma fatia: quem recebeu quanto, no centavo. Detalhes e
  exemplo em [Split de Pagamento → Split realizado no retorno](/casos-uso/split-pagamento#split-realizado-no-retorno-o-que-você-recebe).

  <Expandable title="campos de cada fatia">
    <ResponseField name="split[].recipient" type="object">
      Recebedor da fatia (`uuid` e `name`). **`null`** = a fatia é do próprio lojista da chave.
    </ResponseField>

    <ResponseField name="split[].amount" type="integer">
      Valor da fatia, em centavos.
    </ResponseField>

    <ResponseField name="split[].interest_amount" type="integer">
      Parte dos juros (centavos) atribuída à fatia, quando aplicável.
    </ResponseField>

    <ResponseField name="split[].percentage" type="integer">
      Percentual (0–100) aplicado no momento da venda. Pode ser `null`.
    </ResponseField>

    <ResponseField name="split[].liable" type="boolean">
      Se esta fatia absorve o prejuízo num chargeback.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  O mesmo bloco `split` vem também na **resposta da criação da cobrança** e no
  `GET /payments/{identifier}` — o contrato é idêntico nas três superfícies.
</Note>

***

## Dados do Cartão de Crédito

Quando `payment_method` é `credit_card`, o objeto `credit_card` está presente:

```json theme={null}
{
  "credit_card": {
    "id": "3f7d2a91-8c4e-4b6f-9a2d-5e8c1f4b7a30",
    "holder": "João Silva",
    "brand": "visa",
    "first_6": "424242",
    "last_4": "4242",
    "exp_month": "12",
    "exp_year": "2025",
    "statement_descriptor": "MINHALOJA*",
    "capture": true,
    "three_ds": null
  }
}
```

<ResponseField name="credit_card.id" type="string">
  ID do cartão tokenizado
</ResponseField>

<ResponseField name="credit_card.holder" type="string">
  Nome do portador do cartão
</ResponseField>

<ResponseField name="credit_card.brand" type="string">
  Bandeira do cartão

  Exemplos: `visa`, `mastercard`, `elo`, `amex`
</ResponseField>

<ResponseField name="credit_card.first_6" type="string">
  Primeiros 6 dígitos do cartão (BIN)
</ResponseField>

<ResponseField name="credit_card.last_4" type="string">
  Últimos 4 dígitos do cartão
</ResponseField>

<ResponseField name="credit_card.exp_month" type="string">
  Mês de expiração (formato: MM)
</ResponseField>

<ResponseField name="credit_card.exp_year" type="string">
  Ano de expiração (formato: YYYY)
</ResponseField>

<ResponseField name="credit_card.statement_descriptor" type="string">
  Texto que aparece na fatura do cliente
</ResponseField>

<ResponseField name="credit_card.capture" type="boolean">
  Se a captura é automática
</ResponseField>

<ResponseField name="credit_card.three_ds" type="object">
  Dados de autenticação 3D Secure (quando aplicável)
</ResponseField>

***

## Dados do Boleto Bancário

Quando `payment_method` é `bank_slip`, o objeto `bank_slip` está presente:

```json theme={null}
{
  "bank_slip": {
    "due_at": "2024-01-20",
    "code": "23793381286008301352987654321000189370000010000",
    "url": "https://api.autorizou.com.br/boletos/abc123.pdf"
  }
}
```

<ResponseField name="bank_slip.due_at" type="string">
  Data de vencimento

  Formato: `Y-m-d`
</ResponseField>

<ResponseField name="bank_slip.code" type="string">
  Código de barras / linha digitável
</ResponseField>

<ResponseField name="bank_slip.url" type="string">
  URL para download do PDF do boleto
</ResponseField>

***

## Dados do PIX

Quando `payment_method` é `pix`, o objeto `pix` está presente:

```json theme={null}
{
  "pix": {
    "expires_at": "2024-01-15 12:00:00",
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "payer_name": "Maria Santos",
    "tax_id": "12345678900"
  }
}
```

<ResponseField name="pix.expires_at" type="string">
  Data e hora de expiração do QR Code

  Formato: `Y-m-d H:i:s`
</ResponseField>

<ResponseField name="pix.qr_code" type="string">
  Código PIX Copia e Cola (payload do QR Code)
</ResponseField>

<ResponseField name="pix.payer_name" type="string">
  Nome do pagador (disponível após pagamento)
</ResponseField>

<ResponseField name="pix.tax_id" type="string">
  CPF/CNPJ do pagador (disponível após pagamento)
</ResponseField>

***

## Objeto Customer

Informações do cliente que realizou o pagamento.

```json theme={null}
{
  "customer": {
    "id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  }
}
```

<ResponseField name="customer.id" type="string">
  ID do cliente na Autorizou
</ResponseField>

<ResponseField name="customer.name" type="string">
  Nome completo do cliente
</ResponseField>

<ResponseField name="customer.email" type="string">
  Email do cliente
</ResponseField>

***

## Objeto Order

Presente quando o pagamento está vinculado a um pedido.

```json theme={null}
{
  "order": {
    "id": "8e5a2c74-9d1f-4b3e-a627-5c8f2e9b4d13",
    "status": "pending",
    "is_closed": false,
    "fee": {
      "fixed_fee_amount": 50,
      "platform_fee_percentage": 3.99,
      "platform_fee_amount": 399
    },
    "customer": {
      "id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
      "name": "João Silva",
      "email": "joao@exemplo.com.br"
    },
    "created_at": "15/01/2024 10:25:00",
    "updated_at": "15/01/2024 10:30:00"
  }
}
```

<ResponseField name="order.id" type="string">
  ID do pedido na Autorizou
</ResponseField>

<ResponseField name="order.status" type="string">
  Status do pedido

  Valores: `pending`, `processing`, `completed`, `cancelled`
</ResponseField>

<ResponseField name="order.is_closed" type="boolean">
  Se o pedido está fechado/finalizado
</ResponseField>

<ResponseField name="order.fee" type="object">
  Informações de taxas do pedido
</ResponseField>

<ResponseField name="order.fee.fixed_fee_amount" type="integer">
  Valor da taxa fixa em centavos
</ResponseField>

<ResponseField name="order.fee.platform_fee_percentage" type="number">
  Percentual da taxa da plataforma
</ResponseField>

<ResponseField name="order.fee.platform_fee_amount" type="integer">
  Valor da taxa da plataforma em centavos
</ResponseField>

***

## Objeto Subscription

Presente em eventos de assinatura ou pagamentos recorrentes.

```json theme={null}
{
  "subscription": {
    "id": "c74e2b58-9a1d-4f6e-83c7-5b2e8d4a1f39",
    "status": "active",
    "plan_id": "plan_premium",
    "interval": "monthly",
    "next_charge_amount": 9900,
    "installments": 1,
    "next_charge_at": "2024-02-15 10:00:00",
    "start_at": "2024-01-15 10:00:00",
    "end_at": null,
    "trial_days": 7,
    "current_cycle": 1,
    "customer": {
      "id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
      "name": "João Silva",
      "email": "joao@exemplo.com.br"
    }
  }
}
```

<ResponseField name="subscription.id" type="string">
  ID da assinatura
</ResponseField>

<ResponseField name="subscription.status" type="string">
  Status da assinatura

  Valores: `active`, `inactive`, `cancelled`, `past_due`
</ResponseField>

<ResponseField name="subscription.plan_id" type="string">
  ID do plano da assinatura
</ResponseField>

<ResponseField name="subscription.interval" type="string">
  Intervalo de cobrança

  Valores: `daily`, `weekly`, `monthly`, `yearly`
</ResponseField>

<ResponseField name="subscription.next_charge_amount" type="integer">
  Valor da próxima cobrança em centavos
</ResponseField>

<ResponseField name="subscription.next_charge_at" type="string">
  Data da próxima cobrança
</ResponseField>

<ResponseField name="subscription.start_at" type="string">
  Data de início da assinatura
</ResponseField>

<ResponseField name="subscription.end_at" type="string">
  Data de término (null se indeterminado)
</ResponseField>

<ResponseField name="subscription.trial_days" type="integer">
  Dias de período de teste
</ResponseField>

<ResponseField name="subscription.current_cycle" type="integer">
  Ciclo atual da assinatura
</ResponseField>

***

## Exemplos Completos

### Pagamento Autorizado (Cartão de Crédito)

```json theme={null}
{
  "event": "payment.authorized",
  "type": "payment",
  "created_at": "2024-01-15 10:30:00",
  "payment": {
    "id": "d29b6f81-4e7c-4a5d-93f8-1b6d4a8c2e57",
    "merchant_reference": "pedido-789",
    "status": "authorized",
    "payment_method": "credit_card",
    "amount": 15000,
    "installments": 3,
    "currency": "BRL",
    "description": "Notebook Dell Inspiron",
    "metadata": {
      "order_id": "789",
      "shipping_method": "express"
    },
    "credit_card": {
      "id": "3f7d2a91-8c4e-4b6f-9a2d-5e8c1f4b7a30",
      "holder": "João Silva",
      "brand": "visa",
      "first_6": "424242",
      "last_4": "4242",
      "exp_month": "12",
      "exp_year": "2025",
      "statement_descriptor": "LOJA*INFORMATICA",
      "capture": true,
      "three_ds": null
    },
    "return_code": "00",
    "refused_reason": null,
    "created_at": "15/01/2024 10:30:00",
    "updated_at": "15/01/2024 10:30:15"
  },
  "customer": {
    "id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  },
  "order": {
    "id": "8e5a2c74-9d1f-4b3e-a627-5c8f2e9b4d13",
    "status": "processing",
    "is_closed": false,
    "fee": {
      "fixed_fee_amount": 50,
      "platform_fee_percentage": 3.99,
      "platform_fee_amount": 599
    },
    "customer": {
      "id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
      "name": "João Silva",
      "email": "joao@exemplo.com.br"
    },
    "created_at": "15/01/2024 10:25:00",
    "updated_at": "15/01/2024 10:30:15"
  }
}
```

### Pagamento Recusado

```json theme={null}
{
  "event": "payment.refused",
  "type": "payment",
  "created_at": "2024-01-15 10:35:00",
  "payment": {
    "id": "f38a6d92-2c5e-4b7a-81d4-9e6c3a5f2b48",
    "merchant_reference": "pedido-790",
    "status": "refused",
    "payment_method": "credit_card",
    "amount": 25000,
    "installments": 1,
    "currency": "BRL",
    "description": "Compra rejeitada",
    "metadata": {},
    "credit_card": {
      "id": "b96e2d54-7a3c-4f8e-91d6-4e7a2c5f8b19",
      "holder": "Maria Santos",
      "brand": "mastercard",
      "first_6": "555555",
      "last_4": "4444",
      "exp_month": "06",
      "exp_year": "2026",
      "statement_descriptor": "LOJA*",
      "capture": true,
      "three_ds": null
    },
    "return_code": "05",
    "refused_reason": "Saldo insuficiente",
    "created_at": "15/01/2024 10:35:00",
    "updated_at": "15/01/2024 10:35:05"
  },
  "customer": {
    "id": "57f0e4ea-b6c3-4e20-a93a-54c840f96a06",
    "name": "Maria Santos",
    "email": "maria@exemplo.com.br"
  }
}
```

### Pagamento PIX Recebido

```json theme={null}
{
  "event": "payment.received",
  "type": "payment",
  "created_at": "2024-01-15 11:00:00",
  "payment": {
    "id": "e4a7c158-9b2d-4e6f-a831-6c9e2b5d8f47",
    "merchant_reference": "pedido-791",
    "status": "confirmed",
    "payment_method": "pix",
    "amount": 5000,
    "installments": 1,
    "currency": "BRL",
    "description": "Camiseta Premium",
    "metadata": {
      "order_id": "791"
    },
    "pix": {
      "expires_at": "2024-01-15 12:00:00",
      "qr_code": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000...",
      "payer_name": "Carlos Oliveira",
      "tax_id": "12345678900"
    },
    "return_code": null,
    "refused_reason": null,
    "created_at": "15/01/2024 10:45:00",
    "updated_at": "15/01/2024 11:00:00"
  },
  "customer": {
    "id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
    "name": "Carlos Oliveira",
    "email": "carlos@exemplo.com.br"
  },
  "order": {
    "id": "5d8b3f92-1c6e-4a7d-b249-8e3f5c7a1d64",
    "status": "completed",
    "is_closed": true,
    "fee": {
      "fixed_fee_amount": 0,
      "platform_fee_percentage": 0.99,
      "platform_fee_amount": 49
    },
    "customer": {
      "id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
      "name": "Carlos Oliveira",
      "email": "carlos@exemplo.com.br"
    },
    "created_at": "15/01/2024 10:45:00",
    "updated_at": "15/01/2024 11:00:00"
  }
}
```

### Boleto Criado

```json theme={null}
{
  "event": "payment.created",
  "type": "payment",
  "created_at": "2024-01-15 09:00:00",
  "payment": {
    "id": "a17d5e83-6f2b-4c9e-95a3-8b4e1d7c2f60",
    "merchant_reference": "pedido-792",
    "status": "pending",
    "payment_method": "bank_slip",
    "amount": 12000,
    "installments": 1,
    "currency": "BRL",
    "description": "Curso online",
    "metadata": {
      "course_id": "curso-123"
    },
    "bank_slip": {
      "due_at": "2024-01-22",
      "code": "23793381286008301352987654321000189370000012000",
      "url": "https://api.autorizou.com.br/boletos/pay_boleto789.pdf"
    },
    "return_code": null,
    "refused_reason": null,
    "created_at": "15/01/2024 09:00:00",
    "updated_at": "15/01/2024 09:00:00"
  },
  "customer": {
    "id": "29b8f5d1-4a7e-4c3f-86b9-2d5a8e1c4f73",
    "name": "Ana Paula",
    "email": "ana@exemplo.com.br"
  }
}
```

### Assinatura Criada

```json theme={null}
{
  "event": "subscription.created",
  "type": "subscription",
  "created_at": "2024-01-15 14:00:00",
  "subscription": {
    "id": "c74e2b58-9a1d-4f6e-83c7-5b2e8d4a1f39",
    "status": "active",
    "plan_id": "plan_premium_monthly",
    "interval": "monthly",
    "next_charge_amount": 9900,
    "installments": 1,
    "next_charge_at": "2024-02-15 14:00:00",
    "start_at": "2024-01-15 14:00:00",
    "end_at": null,
    "trial_days": 7,
    "current_cycle": 1,
    "customer": {
      "id": "29b8f5d1-4a7e-4c3f-86b9-2d5a8e1c4f73",
      "name": "Rafael Costa",
      "email": "rafael@exemplo.com.br"
    }
  }
}
```

***

## Próximos Passos

Agora que você conhece a estrutura dos payloads, você pode implementar o endpoint no seu sistema para receber e processar os webhooks.

<Tip>
  Lembre-se de processar os webhooks de forma idempotente usando o ID do pagamento para evitar processar o mesmo evento múltiplas vezes.
</Tip>