Dashboard

Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos que ocorrem na plataforma ValidaPay. Ao configurar uma URL de webhook, enviaremos uma requisição POST com o payload do evento sempre que ele ocorrer.

Como funciona

1

Configure a URL de webhook no painel em https://app.validapay.com.br/integracao/webhooks

2

Quando um evento ocorre, enviamos um POST para sua URL com o payload em JSON.

3

Sua aplicação deve responder 2xx em menos de 5 segundos para confirmar o recebimento. Esse é o timeout do envio.

4

Falhou? Retentamos sozinhos por até 72 horas, com intervalos crescentes (1, 3, 7, 15 minutos… até 12 horas). Deduplique pelo header X-Webhook-Id, igual em todas as tentativas. Depois disso, reenvie manualmente via POST /v1/users/webhooks/{webhookEventId}/retry ou todos de uma vez via POST /v1/users/webhooks/{webhookId}/redeliver-failed.

Verificação e Segurança

Como verificar a assinatura HMAC (X-Webhook-Signature) antes de confiar no payload.

Eventos disponíveis

Síntese dos 31 eventos documentados na API, agrupados por domínio. Para payloads completos de assinaturas e onboarding, use os links de cada seção.

Pagamentos

Confirmação, falha e cobranças vinculadas a pagamentos avulsos ou recorrentes.

EventoDescrição
payment.successPagamento confirmado. O payload difere entre cobrança avulsa e cobrança de assinatura: a avulsa nunca traz `subscriptionId` e vem com `customer`, `items` e `currentCycle` (com `paidAt`); a de assinatura traz a base da assinatura.
payment.overdueCiclo vencido sem pagamento. A assinatura passa a `DEFAULT` quando estava `ACTIVE`, ou a `PAST_DUE` quando estava `PENDING` ou `TRIALING`.
payment.retryNova tentativa de cobrança de um ciclo em atraso: uma a cada tentativa do cartão e uma a cada nova instrução do Pix Automático. O bloco `retry` diz em que tentativa está, como ela terminou e quando será a próxima — `retry.status` é o desfecho DESTA tentativa, enquanto o `status` da raiz continua sendo o da assinatura. No cartão a 1ª recusa do ciclo sai como `payment.failed` e cada retentativa seguinte como `payment.retry`; retentativa aprovada dispara também `payment.success` e `subscription.renewed`. No Pix Automático ele sai sozinho, no momento em que o débito é instruído.
charge.expiredCobrança expirou sem pagamento. Só ocorre a partir de PENDING, PROCESSING ou AWAITING_PAYMENT; o `status` no payload é o da COBRANÇA.
payment.failedPagamento recusado. Na renovação com cartão, sai na 1ª recusa do ciclo com a base da assinatura e o bloco `retry` (motivo em `retry.failureReason`); as retentativas seguintes saem como `payment.retry`. Na criação, o schema é próprio: não carrega a base de assinatura e usa `accountId`.
charge.createdCobrança gerada. Na cobrança de assinatura, traz a base da assinatura mais os dados da cobrança. Na cobrança avulsa (API por valor, painel ou Pix direto), nunca traz `subscriptionId` nem dados de ciclo: vem com `customer` e `items`, no mesmo formato em todas as rotas. Atenção: `status` aqui é o status da COBRANÇA. O bloco `pix` ou `boleto` já vem com o que é preciso para cobrar, sem um GET adicional.

Assinaturas

Ciclo de vida da assinatura: criação, trial, ativação, renovação, cancelamento e mudanças de plano.

Ver detalhes
EventoDescrição
subscription.createdAssinatura criada, aguardando primeiro pagamento.
subscription.trialAssinatura entrou em período de teste. Não carrega objeto `trial`: o prazo está em `items[].price.trialDays`.
subscription.activatedAssinatura ativada após confirmação de pagamento.
subscription.renewedCiclo renovado e pago. Quando emitido pelo motor de cobrança, acrescenta os campos do próximo ciclo.
subscription.upgradedPlano da assinatura alterado para cima. Traz `chargeId` quando o upgrade gerou cobrança de pro-rata.
subscription.item_addedNovo item adicionado à assinatura. Traz `chargeId` quando a inclusão gerou cobrança.
subscription.item_removedItem removido da assinatura.
subscription.downgrade_scheduledDowngrade agendado para o fim do ciclo.
subscription.canceledAssinatura cancelada. O ciclo corrente continua no payload, com o status em que ficou.
subscription.expiredAssinatura encerrada por falta de pagamento: o ciclo em atraso não foi pago dentro do prazo ou a régua de retentativas do cartão se esgotou.
subscription.cancel_scheduledCancelamento agendado; assinatura segue ativa até o fim do ciclo.

Devoluções

Devolução de Pix e estorno de cartão.

Ver detalhes
EventoDescrição
refund.requestedDevolução registrada e em processamento.
refund.confirmedValor devolvido ao pagador.
refund.failedDevolução recusada ou falhou. O status enviado é `ERROR`.

Onboarding

Etapas da abertura de subconta, do envio da proposta à criação da conta.

Ver detalhes
EventoDescrição
onboarding.createConta da subconta criada.
onboarding.backgroundcheckAnálise de background concluída.
onboarding.documentscopyEtapa de documentoscopia atualizada.
onboarding.proposalStatus final da proposta.

MED

Mecanismo Especial de Devolução do Pix: bloqueios de saldo e contestações.

Ver detalhes
EventoDescrição
med.infraction.updatedInfração do MED atualizada.
med.balance.blockedSaldo bloqueado por ordem do MED.
med.balance.unblockedSaldo desbloqueado.
med.refund.openedProcesso de devolução do MED aberto.
med.refund.closedProcesso de devolução do MED encerrado.

DDA

EventoDescrição
dda.subscription.updatedA inscrição no DDA mudou de estado. Chega alguns minutos após a ativação e pode levar horas no cancelamento.
dda.invoice.receivedBoleto registrado no CPF/CNPJ da conta. Enviado na primeira vez e sempre que o `status` muda; reenvio sem mudança de situação não dispara o evento.

Payload de cada evento

Abra o evento para ver o corpo exato que a ValidaPay envia. Os mesmos payloads estão no contrato OpenAPI, na seção webhooks.

Pagamentos

payment.success

Pagamento confirmado. O payload difere entre cobrança avulsa e cobrança de assinatura: a avulsa nunca traz `subscriptionId` e vem com `customer`, `items` e `currentCycle` (com `paidAt`); a de assinatura traz a base da assinatura.

ver payload

Cobrança avulsa via Pix direto (POST /v1/charges/pix)

{
  "event": "payment.success",
  "timestamp": "2026-09-05T12:00:00.000Z",
  "accountNumber": "4231833",
  "accountId": "4231833",
  "chargeId": "cha_1771511282731_9p1wo3tql",
  "invoiceId": null,
  "type": "ONE_TIME_ITEM",
  "amount": 10.5,
  "currency": "BRL",
  "transactionId": "4000782515",
  "customerId": "cus_1790435193764_3dixre16i",
  "email": "joao@example.com",
  "taxId": "12345678901",
  "metadata": {
    "orderId": "pedido-1001"
  },
  "customer": {
    "customerId": "cus_1790435193764_3dixre16i",
    "name": "João da Silva",
    "email": "joao@example.com",
    "taxId": "12345678901",
    "phone": "11999990000"
  },
  "items": [
    {
      "name": "Cobrança avulsa",
      "description": null,
      "quantity": 1,
      "amount": 10.5,
      "discount": 0
    }
  ],
  "status": "PAID",
  "paymentType": "PIX",
  "dueDate": null,
  "paymentMethod": "PIX",
  "paymentId": "E13935893202609051200s0290d93572",
  "paidAt": "2026-09-05T12:00:00.000Z",
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 10.5,
    "status": "PAID",
    "chargeDate": null,
    "paymentMethod": "pix",
    "paidAt": "2026-09-05T12:00:00.000Z"
  },
  "payer": {
    "name": "João da Silva",
    "taxId": "12345678901",
    "bank": "13935893",
    "account": "410900056",
    "branch": "0001",
    "accountType": "CACC"
  }
}

Cobrança avulsa via API por valor ou pelo painel

{
  "event": "payment.success",
  "timestamp": "2026-10-03T17:10:40.990Z",
  "accountNumber": "4231833",
  "accountId": "4231833",
  "chargeId": "cha_1791047440770_nzonv0adh",
  "invoiceId": "inv_1791047440760_060bt2rwm",
  "type": "ONE_TIME_ITEM",
  "amount": 12.34,
  "currency": "BRL",
  "transactionId": "4000782515",
  "customerId": "cus_1790435193764_3dixre16i",
  "email": "joao@example.com",
  "taxId": "12345678901",
  "metadata": null,
  "customer": {
    "customerId": "cus_1790435193764_3dixre16i",
    "name": "João da Silva",
    "email": "joao@example.com",
    "taxId": "12345678901",
    "phone": "11999990000"
  },
  "items": [
    {
      "name": "Consultoria",
      "description": "Sessão avulsa",
      "quantity": 1,
      "amount": 12.34,
      "discount": 0
    }
  ],
  "status": "PAID",
  "paymentType": "BOLETO",
  "dueDate": "2026-10-10",
  "paidAt": "2026-10-08T14:02:11.000Z",
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 12.34,
    "status": "PAID",
    "chargeDate": "2026-10-10",
    "paymentMethod": "boleto",
    "paidAt": "2026-10-08T14:02:11.000Z"
  },
  "item": "Consultoria"
}

Assinatura ou checkout (cobrança com subscriptionId)

{
  "event": "payment.success",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1788634613625_dd5fgel3q",
  "invoiceId": "inv_1788634612997_b6qfdvb4z"
}

Cobrança de assinatura paga na hora com cartão (upgrade, add item)

{
  "event": "payment.success",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1790439670613_zkm9r5gzw",
  "invoiceId": "inv_1790439670421_m3d8q2x7c",
  "invoiceNumber": "FAT-000123",
  "amount": 29.9,
  "type": "PRORATA_UPGRADE",
  "paymentType": "CREDIT_CARD",
  "paidAt": "2026-09-24T15:12:40.118Z"
}
payment.overdue

Ciclo vencido sem pagamento. A assinatura passa a `DEFAULT` quando estava `ACTIVE`, ou a `PAST_DUE` quando estava `PENDING` ou `TRIALING`.

ver payload
{
  "event": "payment.overdue",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "DEFAULT",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "FAILED",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": null,
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  }
}
payment.retry

Nova tentativa de cobrança de um ciclo em atraso: uma a cada tentativa do cartão e uma a cada nova instrução do Pix Automático. O bloco `retry` diz em que tentativa está, como ela terminou e quando será a próxima — `retry.status` é o desfecho DESTA tentativa, enquanto o `status` da raiz continua sendo o da assinatura. No cartão a 1ª recusa do ciclo sai como `payment.failed` e cada retentativa seguinte como `payment.retry`; retentativa aprovada dispara também `payment.success` e `subscription.renewed`. No Pix Automático ele sai sozinho, no momento em que o débito é instruído.

ver payload

Cartão — tentativa recusada

{
  "event": "payment.retry",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "DEFAULT",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "FAILED",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": null,
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1788634613625_dd5fgel3q",
  "invoiceId": "inv_1788634612997_b6qfdvb4z",
  "invoiceNumber": "inv-1788634612997-R2",
  "amount": 89.9,
  "retry": {
    "attempt": 2,
    "maxAttempts": 13,
    "paymentMethod": "CREDIT_CARD",
    "status": "FAILED",
    "retryAt": "2026-08-13T13:00:00.000Z",
    "nextRetryAt": "2026-08-15T13:00:00.000Z",
    "failureReason": "Saldo insuficiente"
  }
}

Pix Automático — nova tentativa instruída

{
  "event": "payment.retry",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "DEFAULT",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "AWAITING_PAYMENT",
    "chargeDate": "2026-08-15T00:00:00.000Z",
    "paidAt": null,
    "paymentMethod": "pix_automatico"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1788872631318_8875wmv5e",
  "invoiceId": "inv_1788872631157_69srdjg7z",
  "amount": 89.9,
  "retry": {
    "attempt": 1,
    "maxAttempts": 3,
    "paymentMethod": "PIX_AUTOMATICO",
    "status": "AWAITING_PAYMENT",
    "retryAt": "2026-08-20",
    "nextRetryAt": "2026-08-22",
    "endToEndId": "E18236120202608201500puLg32eyALI"
  }
}
charge.expired

Cobrança expirou sem pagamento. Só ocorre a partir de PENDING, PROCESSING ou AWAITING_PAYMENT; o `status` no payload é o da COBRANÇA.

ver payload

Cobrança avulsa

{
  "event": "charge.expired",
  "timestamp": "2026-08-21T00:05:12.031Z",
  "accountId": "4231833",
  "chargeId": "cha_1771511282731_9p1wo3tql",
  "invoiceId": null,
  "subscriptionId": null,
  "customerId": null,
  "amount": 10.5,
  "paymentType": "PIX",
  "status": "EXPIRED",
  "dueDate": null,
  "expiresAt": "2026-09-05T23:59:59.000Z",
  "expiredAt": "2026-09-06T00:05:12.031Z",
  "productName": null
}

Cobrança de assinatura

{
  "event": "charge.expired",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "EXPIRED",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1788634613625_dd5fgel3q",
  "invoiceId": "inv_1788634612997_b6qfdvb4z",
  "amount": 89.9,
  "paymentType": "PIX",
  "dueDate": "2026-08-20",
  "expiresAt": "2026-08-20T23:59:59.000Z",
  "expiredAt": "2026-08-21T00:05:12.031Z",
  "productName": "Belary Premium"
}
payment.failed

Pagamento recusado. Na renovação com cartão, sai na 1ª recusa do ciclo com a base da assinatura e o bloco `retry` (motivo em `retry.failureReason`); as retentativas seguintes saem como `payment.retry`. Na criação, o schema é próprio: não carrega a base de assinatura e usa `accountId`.

ver payload

Renovação recusada (cartão)

{
  "event": "payment.failed",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "DEFAULT",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1790435460112_k2m8x1q4z",
  "invoiceId": "inv_1790435459871_p0d3s7w2a",
  "amount": 89.9,
  "retry": {
    "attempt": 1,
    "maxAttempts": 13,
    "paymentMethod": "CREDIT_CARD",
    "status": "FAILED",
    "retryAt": "2026-09-24T13:00:00.000Z",
    "nextRetryAt": "2026-09-25T13:00:00.000Z",
    "failureReason": "Saldo insuficiente"
  }
}

Recusa na criação

{
  "event": "payment.failed",
  "timestamp": "2026-06-20T00:09:17.334Z",
  "accountId": "4231833",
  "customerId": null,
  "name": "João da Silva",
  "email": "joao@example.com",
  "taxId": "11144477735",
  "cellphone": null,
  "item": null,
  "metadata": null,
  "failed": "Pagamento não autorizado"
}
charge.created

Cobrança gerada. Na cobrança de assinatura, traz a base da assinatura mais os dados da cobrança. Na cobrança avulsa (API por valor, painel ou Pix direto), nunca traz `subscriptionId` nem dados de ciclo: vem com `customer` e `items`, no mesmo formato em todas as rotas. Atenção: `status` aqui é o status da COBRANÇA. O bloco `pix` ou `boleto` já vem com o que é preciso para cobrar, sem um GET adicional.

ver payload

Cobrança de assinatura (Pix)

{
  "event": "charge.created",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "PENDING",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": null,
  "metadata": null,
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1788634613625_dd5fgel3q",
  "invoiceId": "inv_1788634612997_b6qfdvb4z",
  "transactionId": "3080767385",
  "amount": 10.5,
  "currency": "BRL",
  "paymentType": "PIX",
  "type": "RECURRING",
  "pixCollectionType": "COBV",
  "emvQrCode": "00020101021226960014br.gov.bcb.pix…",
  "dueDate": "2026-10-05T00:00:00Z",
  "pix": {
    "emv": "00020101021226960014br.gov.bcb.pix…",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASIAAAEiAQAAAAB1xeIbAAAB...",
    "dueDate": "2026-10-05T00:00:00Z",
    "expiresAt": "2026-10-05T23:59:59.000Z"
  }
}

Cobrança avulsa (Pix)

{
  "event": "charge.created",
  "timestamp": "2026-10-03T17:10:40.990Z",
  "accountNumber": "4231833",
  "accountId": "4231833",
  "chargeId": "cha_1791047440770_nzonv0adh",
  "invoiceId": "inv_1791047440760_060bt2rwm",
  "type": "ONE_TIME_ITEM",
  "amount": 12.34,
  "currency": "BRL",
  "transactionId": "4000782515",
  "customerId": "cus_1790435193764_3dixre16i",
  "email": "joao@example.com",
  "taxId": "12345678901",
  "metadata": null,
  "customer": {
    "customerId": "cus_1790435193764_3dixre16i",
    "name": "João da Silva",
    "email": "joao@example.com",
    "taxId": "12345678901",
    "phone": "11999990000"
  },
  "items": [
    {
      "name": "Consultoria",
      "description": "Sessão avulsa",
      "quantity": 1,
      "amount": 12.34,
      "discount": 0
    }
  ],
  "status": "PENDING",
  "paymentType": "PIX",
  "pixCollectionType": "COBV",
  "emvQrCode": "00020101021226980014br.gov.bcb.pix…",
  "dueDate": "2026-10-04T00:00:00Z",
  "paidAt": null,
  "pix": {
    "emv": "00020101021226980014br.gov.bcb.pix…",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASIAAAEiAQAAAAB1xeIbAAAB...",
    "dueDate": "2026-10-04T00:00:00Z",
    "expiresAt": "2026-11-04T02:59:59.999Z"
  }
}

Cobrança avulsa (boleto)

{
  "event": "charge.created",
  "timestamp": "2026-10-03T17:10:40.990Z",
  "accountNumber": "4231833",
  "accountId": "4231833",
  "chargeId": "cha_1788279800000_boleto01",
  "invoiceId": "inv_1788279800000_x7klm2np4",
  "type": "ONE_TIME_ITEM",
  "amount": 120,
  "currency": "BRL",
  "transactionId": "3080767385",
  "customerId": "cus_1790435193764_3dixre16i",
  "email": "joao@example.com",
  "taxId": "12345678901",
  "metadata": null,
  "customer": {
    "customerId": "cus_1790435193764_3dixre16i",
    "name": "João da Silva",
    "email": "joao@example.com",
    "taxId": "12345678901",
    "phone": "11999990000"
  },
  "items": [
    {
      "name": "Consultoria",
      "description": "Sessão avulsa",
      "quantity": 1,
      "amount": 120,
      "discount": 0
    }
  ],
  "status": "PENDING",
  "paymentType": "BOLETO",
  "dueDate": "2026-09-25",
  "paidAt": null,
  "boleto": {
    "transactionId": "3080767385",
    "digitableLine": "34191.79001 01043.510047 91020.150008 2 91070026000",
    "barCode": "34191790010104351004791020150008291070026000",
    "dueDate": "2026-09-25",
    "assignor": "EMPRESA EXEMPLO LTDA",
    "pdfUrl": "https://api.validapay.com.br/v1/charges/cha_1788279800000_boleto01/boleto.pdf",
    "emv": "00020126580014br.gov.bcb.pix…",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASIAAAEiAQAAAAB1xeIbAAAB..."
  }
}

Assinaturas

subscription.created

Assinatura criada, aguardando primeiro pagamento.

ver payload
{
  "event": "subscription.created",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "PENDING",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": null,
  "metadata": {
    "plan": "PREMIUM",
    "checkoutSessionId": "pa_mstiv3jy_b012bc"
  },
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "PENDING",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "coupon": {
    "code": "PRIMEIRO999"
  }
}
subscription.trial

Assinatura entrou em período de teste. Não carrega objeto `trial`: o prazo está em `items[].price.trialDays`.

ver payload
{
  "event": "subscription.trial",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "TRIALING",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 0,
  "nextChargeDate": null,
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "TRIALING",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": 7
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  }
}
subscription.activated

Assinatura ativada após confirmação de pagamento.

ver payload
{
  "event": "subscription.activated",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  }
}
subscription.renewed

Ciclo renovado e pago. Quando emitido pelo motor de cobrança, acrescenta os campos do próximo ciclo.

ver payload
{
  "event": "subscription.renewed",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "nextCycleChargeDate": "2026-09-10T14:45:05.953Z",
  "nextCycleAmount": 89.9
}
subscription.upgraded

Plano da assinatura alterado para cima. Traz `chargeId` quando o upgrade gerou cobrança de pro-rata.

ver payload
{
  "event": "subscription.upgraded",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1790439670613_zkm9r5gzw"
}
subscription.item_added

Novo item adicionado à assinatura. Traz `chargeId` quando a inclusão gerou cobrança.

ver payload
{
  "event": "subscription.item_added",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "chargeId": "cha_1790439834373_z4pnn00s4"
}
subscription.item_removed

Item removido da assinatura.

ver payload
{
  "event": "subscription.item_removed",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  }
}
subscription.downgrade_scheduled

Downgrade agendado para o fim do ciclo.

ver payload
{
  "event": "subscription.downgrade_scheduled",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-09-10T14:45:05.953Z",
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  }
}
subscription.canceled

Assinatura cancelada. O ciclo corrente continua no payload, com o status em que ficou.

ver payload
{
  "event": "subscription.canceled",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "CANCELED",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": null,
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": "2026-08-14T21:05:54.399Z",
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 199.9,
    "status": "CANCELED",
    "chargeDate": "2026-08-14T20:58:39.833Z",
    "paidAt": null,
    "paymentMethod": "pix_automatico"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "cancelReason": "Cancelamento solicitado pelo administrador."
}
subscription.expired

Assinatura encerrada por falta de pagamento: o ciclo em atraso não foi pago dentro do prazo ou a régua de retentativas do cartão se esgotou.

ver payload
{
  "event": "subscription.expired",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "EXPIRED",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": null,
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "UNCOLLECTIBLE",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": null,
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "cancelReason": "DUNNING_EXPIRED"
}
subscription.cancel_scheduled

Cancelamento agendado; assinatura segue ativa até o fim do ciclo.

ver payload
{
  "event": "subscription.cancel_scheduled",
  "timestamp": "2026-08-14T22:31:59.869Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1786746719522_a8h3r7tix",
  "customerId": "cus_1786746719497_9px4bs9dh",
  "status": "ACTIVE",
  "email": "lucas@example.com",
  "taxId": "12354358903",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": null,
  "metadata": {},
  "startDate": "2026-08-14T22:31:59.522Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_1786746719640_j4ekjyjgd",
      "name": "Belary Premium",
      "description": null,
      "type": "RECURRING",
      "amount": 89.9,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_1786738209146_15vvse7x6",
        "amount": 89.9,
        "title": "Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_1786738209087_fhwxkyp6b",
        "name": "Belary Premium",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 89.9,
    "status": "PAID",
    "chargeDate": "2026-08-10T14:45:05.953Z",
    "paidAt": "2026-08-10T14:45:05.953Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "cancelAtPeriodEnd": true,
  "cancelRequestedAt": "2026-08-03T18:25:09.025Z",
  "effectiveAt": "2026-09-03T18:25:09.025Z",
  "cancelReason": "Solicitado pelo cliente"
}

Devoluções

refund.requested

Devolução registrada e em processamento.

ver payload

Devolução de Pix

{
  "event": "refund.requested",
  "timestamp": "2026-08-14T22:33:58.728Z",
  "accountId": "4231833",
  "refundId": "ref_1786746837248_gsoosg37y",
  "chargeId": "cha_1786746721295_f7y0qtzpz",
  "endToEndId": "E18236120202608142232s0290d93572",
  "amount": 9.99,
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "reason": "CUSTOMER_REQUEST",
  "status": "PROCESSING"
}

Estorno de cartão

{
  "event": "refund.requested",
  "timestamp": "2026-08-14T22:33:58.728Z",
  "accountId": "4231833",
  "refundId": "ref_1786746837248_gsoosg37y",
  "chargeId": "cha_1786746721295_f7y0qtzpz",
  "amount": 9.99,
  "reason": "CUSTOMER_REQUEST",
  "status": "PROCESSING",
  "paymentType": "CREDIT_CARD",
  "providerChargeId": "ch_01JQ8R4M2K",
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  }
}
refund.confirmed

Valor devolvido ao pagador.

ver payload
{
  "event": "refund.confirmed",
  "timestamp": "2026-08-14T22:33:58.728Z",
  "accountId": "4231833",
  "refundId": "ref_1786746837248_gsoosg37y",
  "chargeId": "cha_1786746721295_f7y0qtzpz",
  "endToEndId": "E18236120202608142232s0290d93572",
  "amount": 9.99,
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "returnIdentification": "D13935893202608142233X967RIOG07L",
  "status": "CONFIRMED",
  "splitReversals": [
    {
      "accountNumber": "429131213",
      "amount": 2,
      "status": "REVERSED"
    },
    {
      "accountNumber": "429131214",
      "amount": 1,
      "status": "PENDING",
      "debtId": "sdb_1786746837_x9k2"
    }
  ]
}
refund.failed

Devolução recusada ou falhou. O status enviado é `ERROR`.

ver payload
{
  "event": "refund.failed",
  "timestamp": "2026-08-14T22:33:58.728Z",
  "accountId": "4231833",
  "refundId": "ref_1786746837248_gsoosg37y",
  "chargeId": "cha_1786746721295_f7y0qtzpz",
  "endToEndId": "E18236120202608142232s0290d93572",
  "amount": 9.99,
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  },
  "returnIdentification": "D13935893202608252206s2DvmooTPb2",
  "status": "ERROR",
  "error": "ERROR"
}

Onboarding

onboarding.create

Conta da subconta criada.

ver payload
{
  "event": "onboarding.create",
  "timestamp": "2026-08-24T22:00:54.470Z",
  "accountId": "4231833",
  "data": {
    "formId": "03712fd1-bf57-403e-a278-76ca70b2ed1a",
    "proposalId": "c8d1f2a5-871f-46f2-8f98-dd55641ac225",
    "documentNumber": "12354372990",
    "status": "CONFIRMED",
    "account": {
      "number": "483918595",
      "branch": "0001",
      "name": "Guilherme Ferreira Valente"
    }
  }
}
onboarding.backgroundcheck

Análise de background concluída.

ver payload
{
  "event": "onboarding.backgroundcheck",
  "timestamp": "2026-08-24T22:00:54.470Z",
  "accountId": "4231833",
  "data": {
    "formId": "1fc0f2e7-5fe0-4716-a1a2-e3cb31b94035",
    "proposalId": "8ff8f785-a81d-48a5-a7de-6717c4beb099",
    "documentNumber": "67624185000186",
    "proposalType": "PJ",
    "status": "APPROVED"
  }
}
onboarding.documentscopy

Etapa de documentoscopia atualizada.

ver payload
{
  "event": "onboarding.documentscopy",
  "timestamp": "2026-08-24T22:00:54.470Z",
  "accountId": "4231833",
  "data": {
    "formId": "1fc0f2e7-5fe0-4716-a1a2-e3cb31b94035",
    "proposalId": "8ff8f785-a81d-48a5-a7de-6717c4beb099",
    "documentNumber": "67624185000186",
    "proposalType": "PJ",
    "status": "PENDING",
    "url": "https://…/153ece225709906db8c3656b91536f22"
  }
}
onboarding.proposal

Status final da proposta.

ver payload
{
  "event": "onboarding.proposal",
  "timestamp": "2026-08-24T22:00:54.470Z",
  "accountId": "4231833",
  "data": {
    "formId": "1fc0f2e7-5fe0-4716-a1a2-e3cb31b94035",
    "proposalId": "8ff8f785-a81d-48a5-a7de-6717c4beb099",
    "documentNumber": "67624185000186",
    "proposalType": "PJ",
    "status": "APPROVED"
  }
}

MED

med.infraction.updated

Infração do MED atualizada.

ver payload
{
  "event": "med.infraction.updated",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountId": "4231833",
  "caseId": "med_1786746837248_gsoosg37y",
  "infractionId": "3f8c1d92-5b21-4e77-9a0c-1f2b3c4d5e6f",
  "originalEndToEndId": "E18236120202608142232s0290d93572",
  "status": "ACKNOWLEDGED",
  "analysisResult": null,
  "chargeId": "cha_1786746721295_f7y0qtzpz"
}
med.balance.blocked

Saldo bloqueado por ordem do MED.

ver payload
{
  "event": "med.balance.blocked",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountId": "4231833",
  "caseId": "med_1786746837248_gsoosg37y",
  "blockId": "b4b0c9de-2f18-4a55-9f31-7c0d9a1e2b34",
  "infractionId": "3f8c1d92-5b21-4e77-9a0c-1f2b3c4d5e6f",
  "originalEndToEndId": "E18236120202608142232s0290d93572",
  "blockedAmount": 150,
  "blockStatus": "BLOCKED",
  "balanceAfter": 320.55,
  "blockedBalanceAfter": 150
}
med.balance.unblocked

Saldo desbloqueado.

ver payload
{
  "event": "med.balance.unblocked",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountId": "4231833",
  "caseId": "med_1786746837248_gsoosg37y",
  "blockId": "b4b0c9de-2f18-4a55-9f31-7c0d9a1e2b34",
  "infractionId": "3f8c1d92-5b21-4e77-9a0c-1f2b3c4d5e6f",
  "originalEndToEndId": "E18236120202608142232s0290d93572",
  "unblockedAmount": 150,
  "balanceAfter": 470.55,
  "blockedBalanceAfter": 0
}
med.refund.opened

Processo de devolução do MED aberto.

ver payload
{
  "event": "med.refund.opened",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountId": "4231833",
  "caseId": "med_1786746837248_gsoosg37y",
  "medRefundId": "9a7f2c31-8d64-4b0e-a512-6c3d8e9f0a1b",
  "originalEndToEndId": "E18236120202608142232s0290d93572",
  "refundAmount": 150
}
med.refund.closed

Processo de devolução do MED encerrado.

ver payload
{
  "event": "med.refund.closed",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountId": "4231833",
  "caseId": "med_1786746837248_gsoosg37y",
  "medRefundId": "9a7f2c31-8d64-4b0e-a512-6c3d8e9f0a1b",
  "originalEndToEndId": "E18236120202608142232s0290d93572",
  "refundAmount": 150,
  "analysisResult": "TOTALLY_ACCEPTED",
  "returnIdentification": "D13935893202608142233X967RIOG07L",
  "chargeId": "cha_1786746721295_f7y0qtzpz",
  "balanceResult": {
    "balanceAfter": 320.55,
    "blockedBalanceAfter": 0
  }
}

DDA

dda.subscription.updated

A inscrição no DDA mudou de estado. Chega alguns minutos após a ativação e pode levar horas no cancelamento.

ver payload
{
  "event": "dda.subscription.updated",
  "timestamp": "2026-10-03T15:03:18.000Z",
  "accountId": "4231833",
  "data": {
    "documentNumber": "12345678000199",
    "status": "ACTIVE",
    "errorMessage": null
  }
}
dda.invoice.received

Boleto registrado no CPF/CNPJ da conta. Enviado na primeira vez e sempre que o `status` muda; reenvio sem mudança de situação não dispara o evento.

ver payload
{
  "event": "dda.invoice.received",
  "timestamp": "2026-10-03T15:03:18.000Z",
  "accountId": "4231833",
  "data": {
    "barCode": "34191790010104351004791020150008100000018990",
    "digitableLine": "34191790010104351004791020150008100000018990",
    "documentNumber": "12345678000199",
    "payer": {
      "documentNumber": "12345678000199",
      "name": "EMPRESA EXEMPLO LTDA",
      "fantasyName": "",
      "personType": "J"
    },
    "beneficiary": {
      "documentNumber": "33050196000188",
      "name": "CPFL ENERGIA",
      "fantasyName": "CPFL ENERGIA",
      "personType": "J"
    },
    "description": "CPFL ENERGIA",
    "amount": 189.9,
    "dueDate": "2026-10-25T00:00:00Z",
    "registrationDate": "2026-10-17T00:00:00Z",
    "overdueDate": "2026-11-24T00:00:00Z",
    "status": "OPEN",
    "interest": {
      "date": "2026-10-25T00:00:00Z",
      "amount": 2,
      "code": "1",
      "description": "Value (Calendar days)"
    },
    "fine": {
      "date": "2026-10-25T00:00:00Z",
      "amount": 200,
      "code": "2",
      "description": "Percentage"
    },
    "discounts": []
  }
}
Essa página foi útil?