Notifications
Learn about the events and data models used in Circle Notifications.
Circle API Notifications are subscriber endpoints that enable you to easily receive notifications every time the status of a resource changes.
Common Considerations
All current and future implementations of notification messages have the following attributes:
Name | Type | Description | Sample |
---|---|---|---|
clientId | UUID | Client identifier | c60d2d5b-203c-45bb-9f6e-93641d40a599 |
notificationType | String | The type of notification | payments |
version | int |
Current Implementations
This section lists models currently used by existing flows.
Payment Flow
This section introduces the events that may occur after a payment has been created. Each of the events lists the additional fields in a typical notification payload.
Confirmed
Confirmed means that Circle accepts the payment but it is not settled yet. Following structure represents the notifications for confirmed payments.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payments",
"payment": {...}
}
The payment
payload will be a Payment Object.
Failed
A payment might fail due to insufficient balance, invalid credentials, etc. A notification with the following structure is sent for the failed payments.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payments",
"payment": {...}
}
The payment
payload will be a Payment Object.
Refund
Confirmed refund requests notifications are structured as follows:
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payments",
"payment": {...}
}
The payment
payload will be a Refund Object.
Cancel
Confirmed cancel requests notifications are structured as follows:
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payments",
"payment": {...}
}
If the payment has not been captured yet, the payment will be "voided" and a notification of the original payment will be received with a status of failed.
If the payment is already captured, the payment will be "refunded" and the payment
notification will be a Cancel Object.
Payout Flow
Completed
Completed payouts are settled payouts. Therefore, the funds should be available in the destination accounts. Following structure represents the notifications for completed payouts.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payouts",
"payout": {...}
}
The payout
payload will be a Payout Object.
Failed
Failed payouts notifications are structured as follows:
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payouts",
"payout": {...}
}
The payout
payload will be a Payout Object.
Bank Account (Wire) Verification Flow
Failed
Failed Bank Accounts (Wires) notifications are structured as follows:
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "wire",
"wire": {...}
}
The wire
payload will be a Wire Account Object.
Approved
Approved Bank Accounts (Wires) notifications are structured as follows:
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "wire",
"wire": {...}
}
The wire
payload will be a Wire Account Object.
Transfer Flow
Created
A notification with the structure below is sent on transfer creation.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "transfers",
"transfer": {...}
}
The transfer
payload will be a Transfer Object.
Failed
Failed transfers notifications are structured as follows:
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "transfers",
"transfer": {...}
}
The transfer
payload will be a Transfer Object.
Completed
Completed transfers notifications are structured as follows:
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "transfers",
"transfer": {...}
}
The transfer
payload will be a Transfer Object.
Exchange Conversion Flow
For conversions, there will be a notification sent when the conversion status changes from pending
to complete
or failed
.
Completed
Completed conversions notifications are structured as follows:
{
"clientId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b",
"notificationType": "conversions",
"version": 1,
"customAttributes": {
"clientId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b"
},
"conversion": {
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"status": "complete",
"source": {
"type": "wallet",
"id": "0123456789"
},
"from": {
"amount": "1.00",
"currency": "BTC"
},
"to": {
"amount": "45400.41",
"currency": "USD"
},
"createDate": "2020-04-10T02:13:30.000Z"
}
}
Failed
Failed conversions notifications are structured as follows:
{
"clientId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b",
"notificationType": "conversions",
"version": 1,
"customAttributes": {
"clientId": "b1e4e9fe-0bf1-43ad-86c7-3ab993b0051b"
},
"conversion": {
"id": "a844411c-09e9-440f-b52d-663c9bea7040",
"source": {
"type": "wallet",
"id": "1000174786"
},
"from": {
"amount": "1000000000.00",
"currency": "USD"
},
"to": {
"amount": "264188.438215702990903727",
"currency": "ETH"
},
"status": "failed",
"createDate": "2022-06-02T15:02:34.810Z"
}
}
Updated 7 days ago