Assinaturas

Eventos Webhook

Sequência completa, campos e exemplos de payload de cada evento disparado ao longo do ciclo de vida de uma assinatura.

Como cadastrar

Cadastre via POST /v1/users/webhooks ou no painel em Integração → Webhooks.

subscription.createdsubscription.trialsubscription.activatedsubscription.renewedsubscription.canceledsubscription.cancel_scheduledsubscription.upgradedsubscription.item_addedsubscription.downgrade_scheduledcharge.createdpayment.successpayment.failed

Sequências típicas

Boleto / PIX: assinatura recorrente

subscription.createdcharge.created(cliente paga)payment.successsubscription.activated(próximo ciclo)charge.createdpayment.successsubscription.renewed

Cartão: 1º pagamento

subscription.createdcharge.created(cliente paga)payment.successsubscription.activated

Trial

subscription.trial(fim do trial)charge.createdpayment.successsubscription.activated

Upgrade (pro-rata)

POST /prorata (sem webhook)PUT /items/:itemIdcharge.createdpayment.success (boleto/PIX) ou imediato (cartão)subscription.upgraded

Downgrade

PUT /items/:itemIdsubscription.downgrade_scheduled

Add item

POST /itemscharge.createdpayment.successsubscription.item_added

Remove item

DELETE /items/:itemIdsubscription.item_removed

Cancelamento imediato

DELETE /v1/subscriptions/:idsubscription.canceled

Cancelamento no fim do ciclo

DELETE /v1/subscriptions/:id { atPeriodEnd: true }subscription.cancel_scheduled(fim do ciclo)subscription.canceled (cancelReason: SCHEDULED_AT_PERIOD_END)

Inadimplência

charge.createdpayment.failed (1ª recusa)payment.retry (uma vez por retentativa)(aprovada) payment.success + subscription.renewed(régua esgotada) subscription.expired

Relação com operações da API

Operação	Webhooks disparados
Criação via checkout/charges	subscription.created → charge.created → (payment.success) → subscription.activated
DELETE /v1/subscriptions/:id	subscription.canceled
DELETE /v1/subscriptions/:id { atPeriodEnd: true }	subscription.cancel_scheduled → (fim do ciclo) subscription.canceled
PUT /items/:itemId (upgrade)	charge.created → payment.success → subscription.upgraded
PUT /items/:itemId (downgrade)	subscription.downgrade_scheduled
POST /items (add item)	charge.created → payment.success → subscription.item_added
DELETE /items/:itemId (remove item)	subscription.item_removed
POST /prorata	Nenhum (apenas simulação)
Renovação automática	charge.created → payment.success → subscription.renewed

Detalhamento por evento

subscription.created

assinaturastatus típico: PENDING ou AWAITING_PAYMENT

Assinatura recorrente criada, antes do primeiro pagamento confirmado.

Quando: Imediatamente após checkout com itens RECURRING. Não dispara para assinaturas apenas ONE_TIME.

currentCycle é null
nextChargeDate é null: o ciclo seguinte só é agendado depois do primeiro pagamento
Não dispara subscription.created no fluxo trial, apenas subscription.trial

Exemplo de payload

JSON

{
  "event": "subscription.created",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "PENDING",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": null,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.trial

assinaturastatus típico: TRIALING

Período de trial iniciado para um preço com trialDays.

Quando: Checkout com preço que possui período de trial.

currentCycleNumber: 0
currentCycle é null
nextChargeDate é null durante o trial. A data de fim está em items[].price.trialDays
Não existe objeto trial no payload. A duração está em items[].price.trialDays

Exemplo de payload

JSON

{
  "event": "subscription.trial",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "TRIALING",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 0,
  "nextChargeDate": null,
  "metadata": {},
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "TRIALING",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": 7
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.activated

assinaturastatus típico: ACTIVE

Primeiro pagamento confirmado, assinatura ativa.

Quando: Ciclo 1 pago por confirmação assíncrona (boleto/PIX), checkout cartão (síncrono) ou pagamento manual de invoice.

Sequência típica (boleto/PIX): subscription.created → charge.created → payment.success → subscription.activated
No checkout com cartão, payment.success e subscription.activated são enviados juntos logo após charge.created; não dependa da ordem entre os dois

Exemplo de payload

JSON

{
  "event": "subscription.activated",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.renewed

assinaturastatus típico: ACTIVE

Renovação confirmada (ciclo 2 ou superior).

Quando: Pagamento confirmado do ciclo 2+ pelo motor de ciclos ou por confirmação assíncrona.

Campos exclusivos

Campo	Descrição
`nextCycleChargeDate`	Data de cobrança do próximo ciclo
`nextCycleAmount`	Valor previsto do próximo ciclo

Geralmente acompanhado de charge.created e payment.success
nextCycleChargeDate e nextCycleAmount vêm quando o evento é emitido pelo motor de cobrança

Exemplo de payload

JSON

{
  "event": "subscription.renewed",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 3,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 3,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "creditcard"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "nextCycleChargeDate": "2026-09-10T14:45:05.953Z",
  "nextCycleAmount": 99.99
}

subscription.canceled

assinaturastatus típico: CANCELED

Assinatura cancelada via API ou motor de recorrência (dunning).

Quando: DELETE /v1/subscriptions/:id ou cancelamento por inadimplência.

Campos exclusivos

Campo	Descrição
`cancelReason`	Motivo informado ou gerado pelo sistema

currentCycle continua preenchido, com o status em que o ciclo ficou (CANCELED ou PAID)
nextChargeDate é null: assinatura encerrada não tem cobrança futura
Cancelamento agendado que venceu chega com cancelReason: "SCHEDULED_AT_PERIOD_END"
Internamente boleto/PIX pode usar subscription.canceled.boleto_pix, mas o seller sempre recebe subscription.canceled

Exemplo de payload

JSON

{
  "event": "subscription.canceled",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "CANCELED",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": null,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": "2026-07-03T18:25:09.025Z",
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "CANCELED",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": null,
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "cancelReason": "Cancelado pelo cliente"
}

subscription.expired

assinaturastatus típico: EXPIRED

Assinatura encerrada por falta de pagamento.

Quando: Ciclo em atraso não pago dentro do prazo, ou régua de retentativas do cartão esgotada.

Campos exclusivos

Campo	Descrição
`cancelReason`	DUNNING_EXPIRED ou NON_PAYMENT

nextChargeDate é null: assinatura encerrada não tem cobrança futura

Exemplo de payload

JSON

{
  "event": "subscription.expired",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "EXPIRED",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": null,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "UNCOLLECTIBLE",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": null,
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "cancelReason": "DUNNING_EXPIRED"
}

subscription.cancel_scheduled

assinaturastatus típico: ACTIVE (inalterado)

Cancelamento agendado para o fim do período vigente. A assinatura continua ativa até lá.

Quando: DELETE /v1/subscriptions/:id com body { "atPeriodEnd": true }, ou PATCH com { "action": "cancel", "atPeriodEnd": true }.

Campos exclusivos

Campo	Descrição
`cancelAtPeriodEnd`	Sempre true neste evento
`cancelRequestedAt`	Momento em que o cancelamento foi solicitado
`effectiveAt`	Data em que o cancelamento entra em vigor (nextCycleChargeDate); null se não houver próximo ciclo
`nextChargeDate`	Sempre null neste evento: com o cancelamento agendado não há cobrança futura. A data do fim está em effectiveAt
`cancelReason`	Motivo informado na solicitação

A assinatura permanece ACTIVE e o ciclo vigente segue válido até effectiveAt
Não interrompa o acesso do cliente ao receber este evento. Aguarde subscription.canceled
O parâmetro de entrada é atPeriodEnd (booleano true); cancelAtPeriodEnd é o campo devolvido no payload
Sem atPeriodEnd o DELETE cancela imediatamente e dispara subscription.canceled
Reverter o agendamento: PATCH com { "action": "revoke_scheduled_cancel" }. Nesse caso nenhum subscription.canceled é disparado

Exemplo de payload

Ao chegar effectiveAt, um subscription.canceled é disparado com status CANCELED.

JSON

{
  "event": "subscription.cancel_scheduled",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": null,
  "metadata": {},
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "cancelAtPeriodEnd": true,
  "cancelRequestedAt": "2026-07-03T18:25:09.025Z",
  "effectiveAt": "2026-08-03T18:25:09.025Z",
  "cancelReason": "Cancelado pelo cliente",
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.upgraded

assinaturastatus típico: ACTIVE

Upgrade de plano confirmado após pagamento do pro-rata.

Quando: Após PUT /items/:itemId com valor maior e confirmação de pagamento.

Campos exclusivos

Campo	Descrição
`chargeId`	Cobrança do pro-rata, quando o upgrade gerou cobrança

Disparado após applyUpgrade(): items e valores refletem o novo plano

Exemplo de payload

Base igual a subscription.activated; em produção items e valores refletem o upgrade.

JSON

{
  "event": "subscription.upgraded",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "chargeId": "cha_1790439670613_zkm9r5gzw"
}

subscription.item_added

assinaturastatus típico: ACTIVE

Item recorrente ou ONE_TIME adicionado e cobrança confirmada.

Quando: Após POST /items e confirmação via applyAddItem() ou applyOneTimeItem().

Campos exclusivos

Campo	Descrição
`chargeId`	Cobrança do item, quando a inclusão gerou cobrança

Acompanhado de charge.created + payment.success

Exemplo de payload

JSON

{
  "event": "subscription.item_added",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "chargeId": "cha_1790439834373_z4pnn00s4"
}

subscription.item_removed

assinaturastatus típico: ACTIVE

Item removido da assinatura.

Quando: DELETE /items/:itemId. O novo valor passa a valer no próximo ciclo, salvo remoção aplicada ao ciclo corrente.

Só assinável via POST /v1/users/webhooks. O painel ainda não lista este evento

Exemplo de payload

Base igual a subscription.activated; em produção items reflete a assinatura já sem o item.

JSON

{
  "event": "subscription.item_removed",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

subscription.downgrade_scheduled

assinaturastatus típico: ACTIVE

Downgrade agendado para o próximo ciclo, sem cobrança imediata.

Quando: PUT /items/:itemId com valor menor ou quantidade reduzida.

Efetivo em nextCycleChargeDate
Item pode conter scheduledChange no payload enriquecido

Exemplo de payload

JSON

{
  "event": "subscription.downgrade_scheduled",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  }
}

charge.created

cobrançastatus típico: status da COBRANÇA (PENDING, PROCESSING…), não da assinatura

Qualquer cobrança criada vinculada à assinatura.

Quando: 1º ciclo, renovação, pro-rata de upgrade, add item ou item ONE_TIME adicionado à assinatura.

Campos exclusivos

Campo	Descrição
`chargeId`	ID da cobrança
`invoiceId`	ID da fatura, quando houver
`transactionId`	ID da transação
`amount / currency`	Valor em reais (BRL)
`paymentType`	CREDIT_CARD, BOLETO, PIX ou PIX_AUTOMATICO
`type`	RECURRING, PRORATA_UPGRADE, PRORATA_ADD_ITEM, ONE_TIME_ITEM, etc.
`emvQrCode`	Copia-e-cola do Pix, quando paymentType é PIX
`pixCollectionType`	COB ou COBV
`dueDate`	Vencimento da cobrança
`recurrencyId`	Recorrência do Pix Automático, quando houver

Atenção: status neste evento é o da cobrança recém-criada. Filtrar por status === "ACTIVE" não retorna nada
Cobrança avulsa não é assinatura: o charge.created dela não traz subscriptionId nem a base da assinatura, e vem com customer e items (veja o guia de webhooks)

Exemplo de payload

JSON

{
  "event": "charge.created",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "PENDING",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": null,
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": null,
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "chargeId": "cha_1770730676238_example",
  "invoiceId": "inv_1770730676238_example",
  "transactionId": "3080767385",
  "amount": 99.99,
  "currency": "BRL",
  "paymentType": "PIX",
  "type": "RECURRING",
  "pixCollectionType": "COBV",
  "emvQrCode": "00020101021226960014br.gov.bcb.pix…",
  "dueDate": "2026-08-03T00:00:00Z"
}

payment.success

pagamentostatus típico: ACTIVE

Pagamento de uma cobrança da assinatura confirmado.

Quando: Boleto/PIX pago, renovação ou retentativa aprovada no cartão, e upgrade, add item ou cobrança avulsa pagos na hora com cartão. Não dispara no 1º pagamento do checkout com cartão.

Campos exclusivos

Campo	Descrição
`chargeId / invoiceId`	Cobrança e fatura pagas
`type`	Só em cobrança paga na hora com cartão: PRORATA_UPGRADE, PRORATA_ADD_ITEM, ONE_TIME_ITEM ou ONE_OFF
`amount / paymentType / paidAt`	Só em cobrança paga na hora com cartão

Para o 1º pagamento no checkout com cartão, use subscription.activated
nextChargeDate traz a data da próxima cobrança da assinatura

Exemplo de payload

JSON

{
  "event": "payment.success",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "ACTIVE",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "chargeId": "cha_1790439670613_zkm9r5gzw",
  "invoiceId": "inv_1790439670421_m3d8q2x7c"
}

payment.retry

pagamentostatus típico: DEFAULT ou PAST_DUE

Nova tentativa de cobrança de um ciclo em atraso, no cartão ou no Pix Automático.

Quando: Uma vez por tentativa do cartão e uma vez por nova instrução do Pix Automático.

Campos exclusivos

Campo	Descrição
`retry.attempt / retry.maxAttempts`	Tentativa atual e o total previsto pela régua de retentativas
`retry.paymentMethod`	CREDIT_CARD ou PIX_AUTOMATICO
`retry.status`	Desfecho DESTA tentativa: PAID, FAILED ou AWAITING_PAYMENT. Não confundir com o status da raiz, que é o da assinatura
`retry.retryAt`	Quando a tentativa ocorre. No cartão é o instante da cobrança; no Pix Automático, a data em que o débito foi instruído
`retry.nextRetryAt`	Quando será a próxima tentativa. Vem null quando não haverá outra: pagou, recusa definitiva ou régua esgotada
`retry.failureReason`	Motivo da recusa em texto pronto para exibição. Só em tentativa recusada
`retry.endToEndId`	Identificador do débito instruído. Só no Pix Automático

No cartão, a 1ª recusa do ciclo sai como payment.failed com o bloco retry; cada retentativa seguinte sai como payment.retry
Retentativa aprovada no cartão dispara payment.retry (retry.status PAID), payment.success e subscription.renewed
No Pix Automático o evento sai quando o débito é instruído, não quando é pago — a confirmação chega depois em payment.success
Use retry.nextRetryAt para saber se ainda há tentativa pela frente, em vez de comparar attempt com maxAttempts

Exemplo de payload

JSON

{
  "event": "payment.retry",
  "timestamp": "2026-07-03T18:25:09.025Z",
  "accountNumber": "4231833",
  "subscriptionId": "sub_1770730676238_lwubasmvw",
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "status": "DEFAULT",
  "email": "customer@example.com",
  "taxId": "40162317018",
  "interval": "MONTHLY",
  "currentCycleNumber": 1,
  "nextChargeDate": "2026-08-03T18:25:09.025Z",
  "metadata": null,
  "startDate": "2026-07-03T18:25:09.025Z",
  "canceledAt": null,
  "items": [
    {
      "itemId": "item_123456789_example",
      "name": "Produto Exemplo",
      "description": null,
      "type": "RECURRING",
      "amount": 99.99,
      "quantity": 1,
      "discount": 0,
      "status": "ACTIVE",
      "price": {
        "priceId": "price_987654321_example",
        "amount": 99.99,
        "title": "Plano Mensal",
        "recurrenceType": "MONTHLY",
        "trialDays": null
      },
      "product": {
        "productId": "prod_123456_example",
        "name": "Produto Exemplo",
        "type": "RECURRING"
      }
    }
  ],
  "currentCycle": {
    "cycleNumber": 1,
    "amount": 99.99,
    "status": "PAID",
    "chargeDate": "2026-07-03T18:25:09.025Z",
    "paidAt": "2026-07-03T18:25:09.025Z",
    "paymentMethod": "pix"
  },
  "customer": {
    "customerId": "cus_1770483634516_pwj5e9k4f",
    "name": "João Silva",
    "email": "customer@example.com",
    "taxId": "40162317018",
    "phone": "11987654321"
  },
  "chargeId": "cha_1788634613625_dd5fgel3q",
  "invoiceId": "inv_1788634612997_b6qfdvb4z",
  "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"
  }
}

payment.failed

pagamentostatus típico: Renovação: DEFAULT ou PAST_DUE. Criação: schema próprio, sem a base

Pagamento recusado: 1ª tentativa da renovação no cartão ou recusa na criação.

Quando: Na renovação, só na 1ª recusa do ciclo; as seguintes saem como payment.retry.

Campos exclusivos

Campo	Descrição
`chargeId / invoiceId / amount`	Renovação: cobrança recusada
`retry`	Renovação: mesmo bloco do payment.retry, com attempt 1 e o motivo em retry.failureReason
`accountId`	Criação: conta do seller. Este schema usa accountId, não accountNumber
`failed`	Mensagem de erro do pagamento, em texto livre
`name / email / taxId`	Dados do pagador
`customerId / cellphone / item`	Frequentemente null

Na criação, o schema não carrega subscriptionId, items nem currentCycle, e failed é uma string
Use retry.nextRetryAt para saber se haverá nova tentativa

Exemplo de payload

Exemplo do schema de criação. Na renovação o payload segue a base, com chargeId, invoiceId, amount e retry.

JSON

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

Quando o evento possui subscriptionId, o payload é enriquecido com dados vivos (items, customer, currentCycle). Se o enrichment falhar, um payload simplificado é enviado.
Campos adicionais por evento: cancelReason em subscription.canceled; failed em payment.failed; trial em subscription.trial.
Cadastre webhooks via POST /v1/users/webhooks ou no painel em Integração → Webhooks (botão + Webhook).
Valores monetários nos payloads são sempre em reais (BRL), nunca em centavos.

Essa página foi útil?