Circle API Notifications
This document list and describes the events and data models used in Circle Notifications.
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
Following structure represents notifications for confirmed refund requests.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payments",
"payment": {...}
}
The payment
payload will be a Refund Object.
Cancel
Following structure represents notifications for confirmed cancel requests.
{
"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.
Reversal
Following structure represents notifications for reversal requests.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payments",
"reversal": {...}
}
The reversal
payload will be a Reversal Object.
Chargebacks
Note that chargebacks are unique to card payments. Following events will trigger a notification for chargebacks:
- A new chargeback is introduced
- The state of existing chargeback is updated and appended to its history (e.g. chargeback is settled)
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "chargebacks",
"chargeback": {...}
}
The chargeback
payload will be a Chargeback 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
Following structure represents the notifications for failed payouts.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "payouts",
"payout": {...}
}
The payout
payload will be a Payout Object.
Returned
Payouts might rarely return from bank after receiving a settlement. In such cases, a notification that looks like the following will be sent.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "returns",
"return": {...}
}
The return
payload will be a Return Object.
Settlement Flow
Settled
Following structure represents the notifications for settlements.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "settlements",
"settlement": {...}
}
The settlement
payload will be a Settlement Object.
Card Verification Flow
Approved
Following structure represents the notifications for approved cards.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "cards",
"card": {...}
}
The card
payload will be a Card Object.
Bank Account (Wire) Verification Flow
Failed
Following structure represents the notifications for failed Bank Accounts (Wires).
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "wire",
"wire": {...}
}
The wire
payload will be a Wire Account Object.
Approved
Following structure represents the notifications for approved Bank Accounts (Wires).
{
"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
Following structure represents the notifications for failed transfers.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "transfers",
"transfer": {...}
}
The transfer
payload will be a Transfer Object.
Completed
Following structure represents the notifications for completed transfers.
{
"clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
"notificationType": "transfers",
"transfer": {...}
}
The transfer
payload will be a Transfer Object.
Updated 4 days ago