Skip to main content
Stablecoin Payins and Stablecoin Payouts emit webhook events so your server can react to deposit-address assignment, settled payments, recipient review outcomes, and payout status changes. Subscribe to these events instead of polling for status. All payloads use the following envelope structure.
Envelope fieldTypeDescription
clientIdstringYour Circle client identifier.
notificationTypestringEvent type identifier. See Event types.
versionnumberSchema version. Always 1.
<resourceKey>objectEvent-specific data. The key name varies by event type.

​
Event types

notificationTypeResource keyTrigger
paymentIntentspaymentIntentIntent created, deposit address assigned, or (transient intents) intent completed.
paymentspaymentA payin settles, or a refund changes status. Discriminated by type.
addressBookRecipientsaddressBookRecipientRecipient status changes, such as pending to active.
payoutspayoutPayout status changes, such as pending, complete, or failed.

​
Payment intent events

The paymentIntents notification fires when you create an intent, when Circle assigns the deposit address, and—for transient intents—when the intent reaches complete. Continuous intents stay at active and never advance to complete; reconcile their transfers through the payments event instead. Status values observed in timeline[].status: created, pending, active, complete.
Example paymentIntents payload
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "paymentIntent": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "type": "continuous",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": { "amount": "0.00", "currency": "USD" },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "BASE",
        "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
      }
    ],
    "timeline": [
      { "status": "pending", "time": "2026-04-12T20:13:38.188286Z" },
      { "status": "created", "time": "2026-04-12T20:13:35.579331Z" }
    ]
  }
}

​
Payment events

The payments notification fires whenever an inbound transfer settles or a refund changes status. Payments and refunds share this channel and are discriminated by the type field (payment or refund). The payload links back to its intent through paymentIntentId. Status values: pending, paid.
Example payments payload
{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "payments",
  "version": 1,
  "payment": {
    "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
    "type": "payment",
    "status": "paid",
    "amount": { "amount": "1.00", "currency": "USD" },
    "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "fromAddresses": {
      "chain": "BASE",
      "addresses": ["0x0d4344cff68f72a5b9abded37ca5862941a62050"]
    },
    "depositAddress": {
      "chain": "BASE",
      "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
    },
    "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
  }
}

​
Address book recipient events

The addressBookRecipients notification fires when a recipient’s status changes, such as when review completes and the recipient becomes active. Wait for active before you send a payout to the recipient. Status values: pending, inactive, active, denied.
Example addressBookRecipients payload
{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "addressBookRecipients",
  "version": 1,
  "addressBookRecipient": {
    "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe1",
    "chain": "BASE",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "status": "active",
    "createDate": "2026-05-01T14:16:34.985353Z",
    "updateDate": "2026-05-01T14:18:02.123456Z"
  }
}

​
Payout events

The payouts notification fires when a payout status changes. The payload includes the resolved fees and onchain networkFees. Status values: pending, complete, failed.
Example payouts payload
{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "payouts",
  "version": 1,
  "payout": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe1"
    },
    "amount": { "amount": "3000.14", "currency": "USD" },
    "toAmount": { "amount": "3000.14", "currency": "USD" },
    "fees": { "amount": "0.00", "currency": "USD" },
    "networkFees": { "amount": "0.30", "currency": "USD" },
    "status": "complete",
    "createDate": "2026-05-01T14:20:30.000Z",
    "updateDate": "2026-05-01T14:21:12.000Z"
  }
}