Events

Send billing events to Declined via POST /v1/events. Events drive dunning sequences, recovery attempts, and analytics. Each event requires a unique event_id for idempotency.

Supported event types

  • payment_failed
  • payment_recovered
  • invoice_paid
  • invoice_opened
  • payment_method_updated
  • subscription_canceled
  • subscription_past_due
  • subscription_renewed

Payment failed

Start or continue a recovery sequence when a charge fails:

json
{
  "event_id": "evt_unique_001",
  "type": "payment_failed",
  "customer_id": "cus_123",
  "invoice_id": "inv_456",
  "amount": 24900,
  "currency": "usd",
  "provider": "stripe",
  "metadata": { "attempt_count": 2 }
}

Payment recovered

Notify Declined when a customer pays (outside hosted recovery or via your own checkout). This stops active sequences and marks the invoice paid. See Recoveries for the full guide.

json
{
  "event_id": "evt_unique_002",
  "type": "payment_recovered",
  "customer_id": "cus_123",
  "invoice_id": "inv_456",
  "amount": 24900,
  "currency": "usd",
  "provider": "stripe"
}

Response

json
{
  "id": "pe_abc123",
  "event_id": "evt_unique_001",
  "processed": true
}

cURL example

curl
curl -X POST https://dev.declined.io/api/v1/events \
  -H "Authorization: Bearer decl_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"event_id":"evt_1","type":"payment_failed","customer_id":"cus_1","invoice_id":"inv_1"}'