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

Não há retry automático. Entregas que falham ficam registradas e podem ser reenviadas manualmente via POST /v1/users/webhooks/{webhookEventId}/retry.

Verificação e Segurança

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

Eventos disponíveis

Síntese dos 28 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 via Pix direto e cobrança vinculada a uma assinatura.
payment.overdueCiclo vencido sem pagamento. A assinatura passa a `DEFAULT` quando estava `ACTIVE`, ou a `PAST_DUE` quando estava `PENDING` ou `TRIALING`.
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.failedTentativa de pagamento falhou. Schema próprio: não carrega a base de assinatura e usa `accountId`.
charge.createdCobrança gerada. Traz a base da assinatura mais os dados da cobrança — atenção: `status` aqui é o status da COBRANÇA.

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.
subscription.item_addedNovo item adicionado à assinatura.
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 expirada. O evento é assinável e o caminho de envio existe no backend; confirme com o time se algum fluxo já o dispara.
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.

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 via Pix direto e cobrança vinculada a uma assinatura.

ver payload

Cobrança avulsa (Pix direto)

{
  "event": "payment.success",
  "timestamp": "2026-09-05T12:00:00.000Z",
  "accountId": "4231833",
  "chargeId": "cha_1771511282731_9p1wo3tql",
  "amount": 10.5,
  "paymentMethod": "PIX",
  "paymentId": "E13935893202609051200s0290d93572",
  "paidAt": "2026-09-05T12:00:00.000Z",
  "metadata": {
    "orderId": "pedido-1001"
  },
  "payer": {
    "name": "João da Silva",
    "taxId": "12345678901",
    "bank": "13935893",
    "account": "410900056",
    "branch": "0001",
    "accountType": "CACC"
  }
}

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,
  "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"
}
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,
  "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"
  }
}
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,
  "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

Tentativa de pagamento falhou. Schema próprio: não carrega a base de assinatura e usa `accountId`.

ver payload
{
  "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. Traz a base da assinatura mais os dados da cobrança — atenção: `status` aqui é o status da COBRANÇA.

ver payload
{
  "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,
  "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": "ONE_TIME_ITEM",
  "pixCollectionType": "COBV",
  "emvQrCode": "00020101021226960014br.gov.bcb.pix…",
  "dueDate": "2026-10-05T00:00:00Z"
}

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,
  "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,
  "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,
  "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,
  "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.

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,
  "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.item_added

Novo item adicionado à assinatura.

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,
  "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.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,
  "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,
  "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,
  "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 expirada. O evento é assinável e o caminho de envio existe no backend; confirme com o time se algum fluxo já o dispara.

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,
  "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": null,
  "customer": {
    "customerId": "cus_1786746719497_9px4bs9dh",
    "name": "Lucas Ferreira Valente",
    "email": "lucas@example.com",
    "taxId": "12354358903",
    "phone": "4197424445"
  }
}
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,
  "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
  }
}
Essa página foi útil?