Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and USDC payments, automate payouts, embed multi-asset accounts into your product or service, or power your internet marketplace.

Circle API Notifications

This document list and describes the events and data models used in 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 subsequent to payment creation. 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": {...}
}

The payment payload 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.

ACH Account Verification Flow

Failed

Following structure represents the notifications for failed ACH Accounts.

{
   "clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
   "notificationType": "ach",
   "ach": {...}
}

The ach payload will be an ACH Account Object.

Approved

Following structure represents the notifications for approved ACH Accounts.

{
   "clientId": "c60d2d5b-203c-45bb-9f6e-93641d40a599",
   "notificationType": "ach",
   "ach": {...}
}

The ach payload will be an ACH Account 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 months ago


Circle API Notifications


This document list and describes the events and data models used in used in Circle Notifications.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.