Webhook events

Managed Payments uses the v1 Circle APIs notification subscription system, which is separate from the CPN Platform v2 webhook system. For CPN Platform webhook events, see the CPN Platform webhook events reference.

See Set up a webhook endpoint to register an endpoint. The webhooks overview defines the v1 envelope.

Event types

`notificationType`	Resource key	Trigger
`paymentIntents`	`paymentIntent`	An intent is created, gets an address, or receives funds.
`payments`	`payment`	A payment status changes.
`addressBookRecipients`	`addressBookRecipient`	A recipient status changes.
`payouts`	`payout`	A stablecoin payout or fiat withdrawal status changes.
`wireTransfer`	`wireTransfer`	A fiat withdrawal (wire) status changes.
`creditTransfer`	`creditTransfer`	A credit transfer status changes.
`wire`	`wire`	A wire bank account status changes.
`deposits`	`deposit`	A fiat deposit settles to a wallet or sub-account.
`accounts`	`account`	A sub-account status changes to `pending`, `active`, or `rejected`.

Payment intent events

The paymentIntents event fires when an intent is created or gets a deposit address. It also fires when the intent receives funds. timeline[].status values:

created: intent created
pending: awaiting deposit; one-time intents use this state
active: deposit address assigned; continuous intents use this in place of pending
complete: funds received in full
expired: intent expired before completion
failed: intent could not be fulfilled
refunded: funds returned to the sender

Example paymentIntents payload

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "paymentIntent": {
    "type": "continuous",
    "id": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "amountPaid": {
      "amount": "0.00",
      "currency": "USD"
    },
    "amountRefunded": {
      "amount": "0.00",
      "currency": "USD"
    },
    "settlementCurrency": "USD",
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "ETH",
        "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
      }
    ],
    "fees": [
      {
        "type": "blockchainLeaseFee",
        "amount": "0.00",
        "currency": "USD"
      }
    ],
    "timeline": [
      {
        "status": "active",
        "time": "2026-03-23T17:41:23.450386Z"
      },
      {
        "status": "created",
        "time": "2026-03-23T17:41:19.986668Z"
      }
    ],
    "createDate": "2026-03-23T17:41:19.979669Z",
    "updateDate": "2026-03-23T17:41:23.405690Z",
    "merchantWalletId": "12345",
    "currency": "USD"
  }
}

Payment events

The payments event fires when a payment status changes. payment.status values:

pending: payment detected, awaiting confirmation
paid: funds settled to the merchant wallet
failed: payment could not be completed

Example payments payload

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "payments",
  "version": 1,
  "customAttributes": {
    "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291"
  },
  "payment": {
    "id": "021ff661-e7d5-332f-bb9c-e43870608f26",
    "type": "payment",
    "status": "pending",
    "amount": {
      "amount": "5.00",
      "currency": "USD"
    },
    "createDate": "2026-03-23T17:49:54.197Z",
    "updateDate": "2026-03-23T17:49:54.259Z",
    "merchantId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
    "merchantWalletId": "12345",
    "paymentIntentId": "e7b49cb6-1f78-4a0f-8fd6-35fc74dca335",
    "fromAddresses": {
      "chain": "ETH",
      "addresses": ["0x6dbe810e3314546009bd6e1b29f9031211cda5d2"]
    },
    "depositAddress": {
      "chain": "ETH",
      "address": "0xfd5a9f666d96022d13a73e3638fb7ec958696fbe"
    },
    "transactionHash": "0xfbc0f1c8256af3453fd3be7a1491e3581e072022a29ffc78cf129a662182305e"
  }
}

Address book recipient events

The addressBookRecipients event fires when a recipient’s status changes. addressBookRecipient.status values:

pending: recipient submitted, awaiting review
active: recipient approved
inactive: recipient deactivated
denied: recipient rejected
failed: verification failed
pending_verification: additional verification in progress
on_hold: review paused pending more information

Example addressBookRecipients payload

{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "addressBookRecipients",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "addressBookRecipient": {
    "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe",
    "chain": "ETH",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "metadata": {
      "nickname": "test nickname desc",
      "email": "satoshi@circle.com",
      "bns": "testbns"
    },
    "status": "active",
    "updateDate": "2022-09-22T14:16:34.985353Z",
    "createDate": "2022-09-22T14:16:34.985353Z"
  }
}

Payout events

The payouts event fires when a payout status changes. It covers both stablecoin payouts and fiat withdrawals. Read destination.type to tell them apart: an address_book or blockchain destination is a stablecoin payout, and a wire destination is a fiat withdrawal. A fiat withdrawal also carries a fees object and, if the bank returns the funds, a return object. payout.status values:

pending: payout initiated, in progress
complete: funds delivered to the destination
failed: payout could not be completed

Example payouts payload

{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "payouts",
  "version": 1,
  "customAttributes": {
    "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802"
  },
  "payout": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-0a5be9c7ecbe"
    },
    "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": "2020-04-10T02:13:30.000Z",
    "updateDate": "2020-04-10T02:13:30.000Z"
  }
}

A fiat withdrawal carries a bank destination instead:

Example fiat withdrawal payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "payouts",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "payout": {
    "id": "7a2a0284-d705-4311-af07-bc3a1ba93b6f",
    "status": "complete",
    "sourceWalletId": "1000038499",
    "source": { "type": "wallet", "id": "1000038499" },
    "destination": {
      "type": "wire",
      "id": "8c33b3eb-67a4-4f3d-9f4e-2d8a4f1c2b6a",
      "name": "STANDARD CHARTERED BANK ****0010"
    },
    "amount": { "amount": "1000.00", "currency": "USD" },
    "toAmount": { "amount": "1000.00", "currency": "USD" },
    "fees": { "amount": "0.00", "currency": "USD" },
    "trackingRef": "CIR2VKZ9G6",
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:26:02.000Z"
  }
}

The payouts event fires only when a payout reaches a terminal status (complete or failed), not while it’s pending.

Wire transfer events

The wireTransfer event fires when a fiat withdrawal changes status. Circle delivers it as a webhook to Managed Payments accounts, alongside the payouts event for the same withdrawal. It’s separate from the wire event, which reports bank account link status. wireTransfer.status values:

pending: withdrawal initiated, in progress
complete: funds sent to the bank
failed: withdrawal could not be completed

Example wireTransfer payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "wireTransfer",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "wireTransfer": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "amount": { "amount": "1000.00", "currency": "USD" },
    "toAmount": { "amount": "1000.00", "currency": "USD" },
    "fees": { "amount": "0.00", "currency": "USD" },
    "totalAmount": { "amount": "1000.00", "currency": "USD" },
    "transactionType": "wire_withdrawal",
    "status": "complete",
    "location": {
      "type": "wire",
      "id": "8c33b3eb-67a4-4f3d-9f4e-2d8a4f1c2b6a",
      "name": "STANDARD CHARTERED BANK ****0010"
    },
    "fiatTransferType": "wire",
    "trackingRef": "CIR2VKZ9G6",
    "sourceLocation": { "type": "wallet", "id": "1000038499" },
    "createDate": 1784231462474,
    "updateDate": 1784231534908
  }
}

Credit transfer events

The creditTransfer event fires when a credit transfer status changes. A credit transfer draws funds from a line of credit. creditTransfer.status values:

requested: funds requested from the line of credit
disbursed: funds sent to the wallet
paid: transfer repaid in full

Example creditTransfer payload

{
  "clientId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
  "notificationType": "creditTransfer",
  "version": 1,
  "customAttributes": {
    "clientId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd"
  },
  "creditTransfer": {
    "id": "0c206348-1252-4c33-8618-5d85e322a0a3",
    "amount": {
      "amount": "50.00",
      "currency": "USD"
    },
    "status": "disbursed",
    "outstanding": {
      "amount": "50.00",
      "currency": "USD"
    },
    "fees": {
      "amount": "0.00",
      "currency": "USD"
    },
    "dueDate": "2026-02-27T19:37:58.954Z",
    "disbursedDate": "2026-02-20T19:37:58.954Z",
    "createDate": "2026-02-20T19:37:58.358590Z",
    "updateDate": "2026-02-20T19:37:59.321362Z"
  }
}

Credit transfer fields

The creditTransfer object has these fields:

Field	Type	Description
`id`	string (UUID)	ID for the credit transfer.
`amount`	Amount object (`{ amount, currency }`)	Funds drawn from the line of credit.
`status`	enum: `requested`, `disbursed`, `paid`	Current transfer status.
`outstanding`	Amount object (`{ amount, currency }`)	Balance left to repay. Omitted for `requested`.
`fees`	Amount object (`{ amount, currency }`)	Fees due. Omitted for `requested`.
`dueDate`	ISO 8601 timestamp	Date payment is due. Omitted for `requested`.
`disbursedDate`	ISO 8601 timestamp	Date funds reached the wallet. Omitted for `requested`.
`paidDate`	ISO 8601 timestamp	Date the transfer was repaid. Omitted unless `paid`.
`createDate`	ISO 8601 timestamp	Date the transfer was created.
`updateDate`	ISO 8601 timestamp	Date the transfer last changed.

Wire bank account events

The wire event fires when a linked wire bank account changes status. Create the account through the Wires API. wire.status values:

pending: Circle is verifying the account
complete: account linked successfully
failed: account could not be linked

Example wire payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "wire",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "wire": {
    "id": "8c33b3eb-67a4-4f3d-9f4e-2d8a4f1c2b6a",
    "status": "complete",
    "description": "STANDARD CHARTERED BANK ****0010",
    "trackingRef": "CIR2VKZ9G6",
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:25:11.000Z"
  }
}

Deposit events

The deposits event fires when a fiat deposit settles to a wallet or sub-account. The payload includes the deposit id, amount, source, and destination. deposit.status values:

pending: deposit detected, settlement in progress
complete: funds credited to the wallet or sub-account
failed: deposit could not be settled

Example deposits payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "deposits",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "deposit": {
    "id": "df3b8e5f-9579-4c1f-9fa9-deac7f4be55c",
    "status": "complete",
    "amount": { "amount": "1000.00", "currency": "USD" },
    "fromAmount": { "amount": "1000.00", "currency": "USD" },
    "fees": { "amount": "0.00", "currency": "USD" },
    "source": { "type": "wire", "id": "8c33b3eb-67a4-4f3d-9f4e-2d8a4f1c2b6a" },
    "destination": { "type": "wallet", "id": "1000038499" },
    "trackingRef": "CIR2VKZ9G6",
    "createDate": "2026-01-15T18:23:44.000Z",
    "updateDate": "2026-01-15T18:26:02.000Z"
  }
}

Account events

The accounts event reports a sub-account’s status. Use it to learn when a new sub-account is ready. account.status values:

pending: sub-account created, compliance check in progress
active: sub-account ready for use
rejected: sub-account denied

This event reports the result of a compliance check. In most cases, it is active or rejected.

Example accounts payload

{
  "clientId": "00000000-0000-0000-0000-000000000001",
  "notificationType": "accounts",
  "version": 1,
  "customAttributes": { "clientId": "00000000-0000-0000-0000-000000000001" },
  "account": {
    "accountId": "1000038499",
    "entityId": "9a4d6e72-78aa-4b9d-bd84-2cc7c1a8c2d4",
    "clientEntityId": "00000000-0000-0000-0000-000000000001",
    "type": "client",
    "status": "active",
    "description": "Example Trading Ltd."
  }
}

Fiat payouts

Managed Payments

Stablecoin payments

Event types

Payment intent events

Payment events

Address book recipient events

Payout events

Wire transfer events

Credit transfer events

Credit transfer fields

Wire bank account events

Deposit events

Account events

​Event types

​Payment intent events

​Payment events

​Address book recipient events

​Payout events

​Wire transfer events

​Credit transfer events

​Credit transfer fields

​Wire bank account events

​Deposit events

​Account events

Event types

Payment intent events

Payment events

Address book recipient events

Payout events

Wire transfer events

Credit transfer events

Credit transfer fields

Wire bank account events

Deposit events

Account events