Webhooks de Cobrança

Eventos relacionados ao ciclo de vida das cobranças (charges) na FastPay.

Eventos Disponíveis

Evento	Descrição
`charge.created`	Enviado quando uma nova cobrança é criada
`charge.pending`	Enviado quando uma cobrança está aguardando pagamento
`charge.paid`	Enviado quando uma cobrança é paga com sucesso
`charge.refunded`	Enviado após a conclusão de um estorno
`charge.updated`	Canal legado de postback enviado ao `postbackUrl` da cobrança

Status possíveis (`status`)

Valor	Descrição
`pending`	Aguardando pagamento
`paid`	Pago com sucesso
`refused`	Recusado pelo PSP
`failed`	Falha no processamento
`refunded`	Estornado
`in_analysis`	Em análise antifraude
`authentication_required`	Aguardando autenticação 3DS
`pre_chargeback`	Alerta de pré-chargeback recebido — o portador contestou junto ao emissor antes de o chargeback ser formalizado (ver seção Pré-chargeback abaixo)
`chargeback`	Chargeback formalizado (disputa perdida) — ver Bloqueio de Transação

Envelope padrão (charge.created / pending / paid / refunded)

Os eventos charge.created, charge.pending, charge.paid e charge.refunded usam o envelope padrão com campos em snake_case. São entregues via fila (BullMQ) a todos os webhook endpoints configurados do merchant, e adicionalmente ao postback_url da cobrança quando presente.

{
  "id": "<webhookEventId>",
  "event": "charge.paid",
  "livemode": true,
  "data": { ... }
}

Campos do objeto `data` (snake_case)

Campo	Tipo	Descrição
`id`	string	ID da cobrança
`status`	string	Status atual (ver tabela acima)
`psp_ref_id`	string \| null	ID de referência do PSP
`amount`	number	Valor bruto (em reais)
`currency`	string	Código ISO da moeda (ex: `BRL`)
`spread`	number	Spread aplicado
`anticipation_fee_estimated`	number	Taxa de antecipação estimada (cartão de crédito; 0 para outros meios)
`net`	number	Valor líquido (em reais)
`customer`	object \| null	Dados do cliente (ver abaixo)
`payment_method`	object	Dados do meio de pagamento (ver abaixo)
`merchant_id`	string	ID do merchant
`payment_details`	object \| null	Detalhes adicionais do pagamento
`shipping_address`	object \| null	Endereço de entrega (ver abaixo)
`tracking_info`	object \| null	Informações de rastreio (ver abaixo)
`metadata`	object \| null	Metadados definidos pelo merchant
`postback_url`	string \| null	URL de postback configurada na cobrança
`paid_at`	string \| null	Timestamp do pagamento (ISO 8601)
`is_test`	boolean \| null	`true` se cobrança de teste
`created_at`	string	Timestamp de criação (ISO 8601)
`updated_at`	string	Timestamp da última atualização (ISO 8601)
`deleted_at`	string \| null	Timestamp de exclusão, se aplicável

Objeto `customer`

{
  "id": "cu_abc123",
  "name": "Joao Silva",
  "email": "[email protected]",
  "document": {
    "id": "12345678900",
    "type": "cpf"
  },
  "phone": "+5511999999999"
}

Objeto `payment_method` — cartão de crédito

{
  "type": "credit_card",
  "installments": 3,
  "first_six_digits": "411111",
  "last_four_digits": "1111",
  "holder_name": "JOAO SILVA"
}

Objeto `payment_method` — PIX / outros meios

Para cobranças PIX o objeto contém apenas { "type": "pix" }. Dados como QR Code e expiração não são incluídos no payload do webhook (estão disponíveis na resposta da API de criação).

Objeto `shipping_address`

{
  "postalCode": "01310-100",
  "addressLine1": "Av. Paulista, 1000",
  "addressLine2": "Apto 42",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR"
}

Objeto `tracking_info`

{
  "trackingCode": "BR123456789BR",
  "shippingProvider": "Correios",
  "trackingUrl": "https://rastreamento.correios.com.br/...",
  "trackingStatus": "on_the_way"
}

trackingStatus pode ser awaiting_shipment, on_the_way ou delivered.

Payloads por evento

charge.created

Enviado imediatamente após a criação de uma nova cobrança.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.created",
  "livemode": true,
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pending",
    "psp_ref_id": null,
    "amount": 100,
    "currency": "BRL",
    "spread": 0,
    "anticipation_fee_estimated": 0,
    "net": 96.5,
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "[email protected]",
      "document": { "id": "12345678900", "type": "cpf" },
      "phone": null
    },
    "payment_method": { "type": "pix" },
    "merchant_id": "mer_xyz789",
    "payment_details": null,
    "shipping_address": null,
    "tracking_info": null,
    "metadata": null,
    "postback_url": "https://meusite.com/webhooks/fastpay",
    "paid_at": null,
    "is_test": false,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "deleted_at": null
  }
}

charge.pending

Enviado quando a cobrança está aguardando pagamento (ex: PIX gerado).

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.pending",
  "livemode": true,
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pending",
    "psp_ref_id": "pix_e2e_abc123",
    "amount": 100,
    "currency": "BRL",
    "spread": 0,
    "anticipation_fee_estimated": 0,
    "net": 96.5,
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "[email protected]",
      "document": { "id": "12345678900", "type": "cpf" },
      "phone": null
    },
    "payment_method": { "type": "pix" },
    "merchant_id": "mer_xyz789",
    "payment_details": null,
    "shipping_address": null,
    "tracking_info": null,
    "metadata": null,
    "postback_url": "https://meusite.com/webhooks/fastpay",
    "paid_at": null,
    "is_test": false,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:01.000Z",
    "deleted_at": null
  }
}

charge.paid

Enviado quando o pagamento é confirmado com sucesso.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.paid",
  "livemode": true,
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "paid",
    "psp_ref_id": "pix_e2e_abc123",
    "amount": 100,
    "currency": "BRL",
    "spread": 1,
    "anticipation_fee_estimated": 0,
    "net": 95.5,
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "[email protected]",
      "document": { "id": "12345678900", "type": "cpf" },
      "phone": null
    },
    "payment_method": { "type": "pix" },
    "merchant_id": "mer_xyz789",
    "payment_details": null,
    "shipping_address": null,
    "tracking_info": null,
    "metadata": null,
    "postback_url": "https://meusite.com/webhooks/fastpay",
    "paid_at": "2024-01-15T10:35:00.000Z",
    "is_test": false,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:35:00.000Z",
    "deleted_at": null
  }
}

charge.refunded

Enviado após a conclusão bem-sucedida de um estorno.

{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.refunded",
  "livemode": true,
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "refunded",
    "psp_ref_id": "pix_e2e_abc123",
    "amount": 100,
    "currency": "BRL",
    "spread": 1,
    "anticipation_fee_estimated": 0,
    "net": 95.5,
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "[email protected]",
      "document": { "id": "12345678900", "type": "cpf" },
      "phone": null
    },
    "payment_method": { "type": "pix" },
    "merchant_id": "mer_xyz789",
    "payment_details": null,
    "shipping_address": null,
    "tracking_info": null,
    "metadata": null,
    "postback_url": "https://meusite.com/webhooks/fastpay",
    "paid_at": "2024-01-15T10:35:00.000Z",
    "is_test": false,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T11:00:00.000Z",
    "deleted_at": null
  }
}

charge.updated — canal legado de postback

charge.updated é diferente dos demais eventos de cobrança.Ele é entregue exclusivamente ao postbackUrl informado na criação da cobrança — nunca aos webhook endpoints cadastrados no painel. É um canal legado (postback direto) com um envelope e convenção de nomenclatura diferentes.Situações que disparam o charge.updated:

Transação bloqueada pelo fluxo de bloqueio (ver Bloqueio de Transação)
Alerta de pré-chargeback (status: pre_chargeback) — ver seção Pré-chargeback abaixo
Falha de autenticação 3DS
Atualização de status pelo PSP (ex: recusa, falha)

Envelope do charge.updated (camelCase)

O envelope não contém id nem livemode. O objeto data é o charge completo convertido para camelCase:

{
  "event": "charge.updated",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "refused",
    "pspRefId": "card_ref_abc123",
    "amount": 100,
    "currency": "BRL",
    "spread": 0,
    "net": 0,
    "isBlocked": true,
    "customer": {
      "id": "cu_abc123",
      "name": "Joao Silva",
      "email": "[email protected]",
      "document": { "id": "12345678900", "type": "cpf" },
      "phone": null
    },
    "paymentMethod": {
      "type": "credit_card",
      "installments": 1,
      "firstSixDigits": "411111",
      "lastFourDigits": "1111",
      "holderName": "JOAO SILVA"
    },
    "merchantId": "mer_xyz789",
    "paymentDetails": null,
    "shippingAddress": null,
    "trackingInfo": null,
    "metadata": null,
    "postbackUrl": "https://meusite.com/webhooks/fastpay",
    "paidAt": null,
    "isTest": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:31:00.000Z",
    "deletedAt": null
  }
}

O campo isBlocked estará presente no payload quando a cobrança tiver sido bloqueada. Consulte a documentação de Bloqueio de Transação para entender o fluxo completo.

Pré-chargeback (alerta)

Quando a FastPay recebe um alerta de pré-chargeback (programas tipo Ethoca/Verifi — o portador contestou a compra junto ao emissor antes de o chargeback ser formalizado), a cobrança passa para o status pre_chargeback. A transição é notificada via postback charge.updated (à postbackUrl da cobrança) — não há evento dedicado (charge.pre_chargeback não existe) e os webhook endpoints cadastrados no painel não recebem esse evento. O objeto data inclui dois campos específicos do alerta:

Campo	Tipo	Descrição
`chargebackAlertRefunded`	boolean \| null	`true` = o valor já foi estornado ao portador como parte do tratamento do alerta; `false` = disputa aberta sem estorno
`chargebackAlertReason`	string \| null	Motivo/referência informado no alerta (ex.: `"Chargeback - NSU 123456789"`)

Com ou sem estorno. Ao registrar o alerta, a FastPay usa uma flag refund (default true):

Com estorno (refund: true, o caso comum): o valor é devolvido imediatamente ao portador para evitar que o alerta evolua para chargeback formal (e suas taxas/penalidades). O pedido deve ser tratado como estornado.
Sem estorno (refund: false): decisão operacional de contestar/não devolver (ex.: mercadoria já entregue com prova de entrega). A disputa segue aberta; o pedido não deve ser marcado como estornado.

Em ambos os casos o status vai para pre_chargeback — o estorno é uma dimensão ortogonal ao status, lida via chargebackAlertRefunded.

{
  "event": "charge.updated",
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "pre_chargeback",
    "chargebackAlertRefunded": true,
    "chargebackAlertReason": "Chargeback - NSU 123456789",
    "amount": 100,
    "currency": "BRL",
    "merchantId": "mer_xyz789",
    "postbackUrl": "https://meusite.com/webhooks/fastpay",
    "isTest": false
  }
}

Tratamento recomendado. Ao receber charge.updated com status = "pre_chargeback":

chargebackAlertRefunded = true → marque o pedido como estornado (valor já devolvido ao portador);
chargebackAlertRefunded = false → marque como em disputa, sem estorno.

Retentativas do postback legado

O postback legado tenta o envio até 3 vezes em caso de falha, com backoff exponencial: ≈1 s, ≈2 s, ≈4 s entre as tentativas.

Exemplo de Implementação

app.post('/webhooks/fastpay', (req, res) => {
  const { id, event, data } = req.body;

  switch (event) {
    case 'charge.created':
      console.log(`Nova cobrança criada: ${data.id}`);
      break;

    case 'charge.pending':
      console.log(`Cobrança aguardando pagamento: ${data.id}`);
      break;

    case 'charge.paid':
      console.log(`Pagamento confirmado: ${data.id}`);
      // Liberar acesso ao produto/serviço
      // Atualizar status do pedido
      // Enviar email de confirmação
      break;

    case 'charge.refunded':
      console.log(`Estorno concluído: ${data.id}`);
      // Revogar acesso / registrar estorno
      break;

    case 'charge.updated':
      // Canal legado — entregue apenas ao postbackUrl da cobrança
      console.log(`Cobrança atualizada (postback): ${data.id}`);
      if (data.isBlocked) {
        console.log('Cobrança bloqueada');
      }
      break;

    default:
      console.log(`Evento desconhecido: ${event}`);
  }

  res.status(200).send('OK');
});

Introdução

Autenticação

Homologação

Recursos

Webhooks

Webhooks de Cobrança

Eventos Disponíveis

Status possíveis (`status`)

Envelope padrão (charge.created / pending / paid / refunded)

Campos do objeto `data` (snake_case)

Objeto `customer`

Objeto `payment_method` — cartão de crédito

Objeto `payment_method` — PIX / outros meios

Objeto `shipping_address`

Objeto `tracking_info`

Payloads por evento

charge.created

charge.pending

charge.paid

charge.refunded

charge.updated — canal legado de postback

Envelope do charge.updated (camelCase)

Pré-chargeback (alerta)

Retentativas do postback legado

Exemplo de Implementação

Fluxo Típico (PIX)

​Eventos Disponíveis

​Status possíveis (status)

​Envelope padrão (charge.created / pending / paid / refunded)

​Campos do objeto data (snake_case)

​Objeto customer

​Objeto payment_method — cartão de crédito

​Objeto payment_method — PIX / outros meios

​Objeto shipping_address

​Objeto tracking_info

​Payloads por evento

​charge.created

​charge.pending

​charge.paid

​charge.refunded

​charge.updated — canal legado de postback

​Envelope do charge.updated (camelCase)

​Pré-chargeback (alerta)

​Retentativas do postback legado

​Exemplo de Implementação

​Fluxo Típico (PIX)

Eventos Disponíveis

Status possíveis (`status`)

Envelope padrão (charge.created / pending / paid / refunded)

Campos do objeto `data` (snake_case)

Objeto `customer`

Objeto `payment_method` — cartão de crédito

Objeto `payment_method` — PIX / outros meios

Objeto `shipping_address`

Objeto `tracking_info`

Payloads por evento

charge.created

charge.pending

charge.paid

charge.refunded

charge.updated — canal legado de postback

Envelope do charge.updated (camelCase)

Pré-chargeback (alerta)

Retentativas do postback legado

Exemplo de Implementação

Fluxo Típico (PIX)