Skip to main content
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.
All Managed Payments webhook payloads use the following v1 envelope structure:
Envelope fieldTypeDescription
clientIdstringYour Circle client identifier.
notificationTypestringEvent type identifier. See Event types.
versionnumberSchema version. Always 1.
customAttributesobjectContains clientId.
<resourceKey>objectEvent-specific data. Key name varies by event type.

​
Event types

notificationTypeResource keyTrigger
paymentIntentspaymentIntentPayment intent created, deposit address ready, or payment received
paymentspaymentPayment status changes (for example, pending or paid)
addressBookRecipientsaddressBookRecipientRecipient status changes (for example, pending or active)
payoutpayoutPayout status changes (for example, pending, complete, or failed)
creditTransfercreditTransferCredit transfer status changes (requested, disbursed, or paid)

​
Payment intent events

The paymentIntents notification fires when a payment intent is created, when a blockchain deposit address becomes available, or when a payment is received against the intent. Status values observed in timeline[].status: created, active
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 notification fires when a payment status changes. Status values: pending, paid
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 notification fires when a recipient’s status changes. Status values: pending, active
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 payout notification fires when a payout status changes. Status values: pending, complete, failed
Example payout payload
{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "payout",
  "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"
  }
}

​
Credit transfer events

The creditTransfer notification fires when a credit transfer status changes. A credit transfer represents a draw from a line of credit. Status values: requested (disbursement requested), disbursed (funds transferred to wallet), paid (fully repaid; fees invoiced at month end)
Example creditTransfer payload
{
  "clientId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd",
  "notificationType": "creditTransfer",
  "version": 1,
  "customAttributes": {
    "clientId": "a49f9b1d-75e0-44a9-b8d2-4293b3f11ebd"
  },
  "creditTransfer": {
    "data": {
      "id": "0c206348-1252-4c33-8618-5d85e322a0a3",
      "amount": {
        "amount": "50.00",
        "currency": "USD"
      },
      "status": "disbursed",
      "outstanding": {
        "amount": "50.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 following table documents every field in the creditTransfer.data object.
FieldTypeDescription
idstring (UUID)Unique identifier for the credit transfer.
amountAmount object ({ amount, currency })Total amount drawn from the line of credit.
statusenum: requested, disbursed, paidCurrent status of the credit transfer.
outstandingAmount object ({ amount, currency })Remaining balance to repay. Omitted when status is requested.
dueDateISO 8601 timestampWhen repayment is due. Omitted when status is requested.
disbursedDateISO 8601 timestampWhen funds were disbursed to the wallet. Omitted when status is requested.
paidDateISO 8601 timestampWhen the credit transfer was fully repaid. Omitted unless status is paid.
createDateISO 8601 timestampWhen the credit transfer was created.
updateDateISO 8601 timestampWhen the credit transfer was last updated.