> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook events

> Managed Payments webhook event types, payloads, and v1 subscriptions

<Note>
  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](/cpn/references/webhooks/webhook-events).
</Note>

See
[Set up a webhook endpoint](/api-reference/webhook-endpoints#v1-notifications)
to register an endpoint. The
[webhooks overview](/api-reference/webhooks#event-model) 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

```json Example paymentIntents payload theme={null}
{
  "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

```json Example payments payload theme={null}
{
  "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

```json Example addressBookRecipients payload theme={null}
{
  "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

```json Example payouts payload theme={null}
{
  "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:

```json Example fiat withdrawal payload theme={null}
{
  "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](#wire-bank-account-events), 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

```json Example wireTransfer payload theme={null}
{
  "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

```json Example creditTransfer payload theme={null}
{
  "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](/api-reference/cpn/managed-payments/wires/create-account-wire-account).

`wire.status` values:

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

```json Example wire payload theme={null}
{
  "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

```json Example deposits payload theme={null}
{
  "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

<Note>
  This event reports the result of a compliance check. In most cases, it is
  `active` or `rejected`.
</Note>

```json Example accounts payload theme={null}
{
  "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."
  }
}
```