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:

NameTypeDescriptionSample
clientIdUUIDClient identifierc60d2d5b-203c-45bb-9f6e-93641d40a599
notificationTypeStringThe type of notificationpayments
versionint

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.