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:

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"
  }
}