Estrutura dos Payloads

Estrutura Base

Todos os webhooks enviados pela Autorizou seguem esta estrutura base:

{
  "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) */ }
}

event

string

Nome do evento que disparou o webhookExemplos: payment.authorized, payment.refused, subscription.created

type

string

Tipo do recurso principalValores: payment, subscription

created_at

string

Data e hora em que o evento foi criadoFormato: Y-m-d H:i:s (UTC)

Objeto Payment

Presente em todos os eventos de pagamento.

{
  "payment": {
    "id": "pay_abc123def456",
    "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,
    "created_at": "15/01/2024 10:30:00",
    "updated_at": "15/01/2024 10:30:15"
  }
}

Campos do Payment

string

ID único do pagamento na Autorizou

merchant_reference

string

Referência do pagamento no seu sistema

status

string

Status atual do pagamentoValores: pending, authorized, confirmed, refused, refunded, expired, etc.

payment_method

string

Método de pagamento utilizadoValores: credit_card, bank_slip, pix

amount

integer

Valor em centavosExemplo: 10000 = R$ 100,00

installments

integer

Número de parcelas

currency

string

Código da moeda (ISO 4217)Exemplo: BRL, USD

description

string

Descrição do pagamento

metadata

object

Dados customizados enviados na criação do pagamento

return_code

string

Código de retorno da adquirente (quando disponível)

refused_reason

string

Motivo da recusa (quando aplicável)

Dados do Cartão de Crédito

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

{
  "credit_card": {
    "id": "card_xyz789",
    "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
  }
}

credit_card.id

string

ID do cartão tokenizado

credit_card.holder

string

Nome do portador do cartão

credit_card.brand

string

Bandeira do cartãoExemplos: visa, mastercard, elo, amex

credit_card.first_6

string

Primeiros 6 dígitos do cartão (BIN)

credit_card.last_4

string

Últimos 4 dígitos do cartão

credit_card.exp_month

string

Mês de expiração (formato: MM)

credit_card.exp_year

string

Ano de expiração (formato: YYYY)

credit_card.statement_descriptor

string

Texto que aparece na fatura do cliente

credit_card.capture

boolean

Se a captura é automática

credit_card.three_ds

object

Dados de autenticação 3D Secure (quando aplicável)

Dados do Boleto Bancário

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

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

bank_slip.due_at

string

Data de vencimentoFormato: Y-m-d

bank_slip.code

string

Código de barras / linha digitável

bank_slip.url

string

URL para download do PDF do boleto

Dados do PIX

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

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

pix.expires_at

string

Data e hora de expiração do QR CodeFormato: Y-m-d H:i:s

pix.qr_code

string

Código PIX Copia e Cola (payload do QR Code)

pix.payer_name

string

Nome do pagador (disponível após pagamento)

pix.tax_id

string

CPF/CNPJ do pagador (disponível após pagamento)

Objeto Customer

Informações do cliente que realizou o pagamento.

{
  "customer": {
    "id": "cus_123456",
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  }
}

customer.id

string

ID do cliente na Autorizou

customer.name

string

Nome completo do cliente

customer.email

string

Email do cliente

Objeto Order

Presente quando o pagamento está vinculado a um pedido.

{
  "order": {
    "id": "ord_789123",
    "status": "pending",
    "is_closed": false,
    "fee": {
      "fixed_fee_amount": 50,
      "platform_fee_percentage": 3.99,
      "platform_fee_amount": 399
    },
    "customer": {
      "id": "cus_123456",
      "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"
  }
}

order.id

string

ID do pedido na Autorizou

order.status

string

Status do pedidoValores: pending, processing, completed, cancelled

order.is_closed

boolean

Se o pedido está fechado/finalizado

order.fee

object

Informações de taxas do pedido

order.fee.fixed_fee_amount

integer

Valor da taxa fixa em centavos

order.fee.platform_fee_percentage

number

Percentual da taxa da plataforma

order.fee.platform_fee_amount

integer

Valor da taxa da plataforma em centavos

Objeto Subscription

Presente em eventos de assinatura ou pagamentos recorrentes.

{
  "subscription": {
    "id": "sub_abc789",
    "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": "cus_123456",
      "name": "João Silva",
      "email": "joao@exemplo.com.br"
    }
  }
}

subscription.id

string

ID da assinatura

subscription.status

string

Status da assinaturaValores: active, inactive, cancelled, past_due

subscription.plan_id

string

ID do plano da assinatura

subscription.interval

string

Intervalo de cobrançaValores: daily, weekly, monthly, yearly

subscription.next_charge_amount

integer

Valor da próxima cobrança em centavos

subscription.next_charge_at

string

Data da próxima cobrança

subscription.start_at

string

Data de início da assinatura

subscription.end_at

string

Data de término (null se indeterminado)

subscription.trial_days

integer

Dias de período de teste

subscription.current_cycle

integer

Ciclo atual da assinatura

Exemplos Completos

Pagamento Autorizado (Cartão de Crédito)

{
  "event": "payment.authorized",
  "type": "payment",
  "created_at": "2024-01-15 10:30:00",
  "payment": {
    "id": "pay_abc123def456",
    "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": "card_xyz789",
      "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": "cus_123456",
    "name": "João Silva",
    "email": "joao@exemplo.com.br"
  },
  "order": {
    "id": "ord_789123",
    "status": "processing",
    "is_closed": false,
    "fee": {
      "fixed_fee_amount": 50,
      "platform_fee_percentage": 3.99,
      "platform_fee_amount": 599
    },
    "customer": {
      "id": "cus_123456",
      "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

{
  "event": "payment.refused",
  "type": "payment",
  "created_at": "2024-01-15 10:35:00",
  "payment": {
    "id": "pay_refused123",
    "merchant_reference": "pedido-790",
    "status": "refused",
    "payment_method": "credit_card",
    "amount": 25000,
    "installments": 1,
    "currency": "BRL",
    "description": "Compra rejeitada",
    "metadata": {},
    "credit_card": {
      "id": "card_abc456",
      "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": "cus_789456",
    "name": "Maria Santos",
    "email": "maria@exemplo.com.br"
  }
}

Pagamento PIX Recebido

{
  "event": "payment.received",
  "type": "payment",
  "created_at": "2024-01-15 11:00:00",
  "payment": {
    "id": "pay_pix123abc",
    "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": "cus_456789",
    "name": "Carlos Oliveira",
    "email": "carlos@exemplo.com.br"
  },
  "order": {
    "id": "ord_791456",
    "status": "completed",
    "is_closed": true,
    "fee": {
      "fixed_fee_amount": 0,
      "platform_fee_percentage": 0.99,
      "platform_fee_amount": 49
    },
    "customer": {
      "id": "cus_456789",
      "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

{
  "event": "payment.created",
  "type": "payment",
  "created_at": "2024-01-15 09:00:00",
  "payment": {
    "id": "pay_boleto789",
    "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": "cus_987654",
    "name": "Ana Paula",
    "email": "ana@exemplo.com.br"
  }
}

Assinatura Criada

{
  "event": "subscription.created",
  "type": "subscription",
  "created_at": "2024-01-15 14:00:00",
  "subscription": {
    "id": "sub_premium123",
    "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": "cus_sub123",
      "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.

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

​Estrutura Base

​Objeto Payment

​Campos do Payment

​Dados do Cartão de Crédito

​Dados do Boleto Bancário

​Dados do PIX

​Objeto Customer

​Objeto Order

​Objeto Subscription

​Exemplos Completos

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

​Pagamento Recusado

​Pagamento PIX Recebido

​Boleto Criado

​Assinatura Criada

​Próximos Passos

Estrutura Base

Objeto Payment

Campos do Payment

Dados do Cartão de Crédito

Dados do Boleto Bancário

Dados do PIX

Objeto Customer

Objeto Order

Objeto Subscription

Exemplos Completos

Pagamento Autorizado (Cartão de Crédito)

Pagamento Recusado

Pagamento PIX Recebido

Boleto Criado

Assinatura Criada

Próximos Passos