_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:

NameTypeDescriptionSample
clientIdUUIDClient identifier`c60d2d5b-203c-45bb-9f6e-93641d40a599`
notificationTypeStringThe type of notification`payments`
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.



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.



The `payment` payload will be a [Payment Object](🔗).

### Refund

Confirmed refund requests notifications are structured as follows:



The `payment` payload will be a [Refund Object](🔗).

### Cancel

Confirmed cancel requests notifications are structured as follows:



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.



The `payout` payload will be a [Payout Object](🔗).

### Failed

Failed payouts notifications are structured as follows:



The `payout` payload will be a [Payout Object](🔗).

## **Bank Account (Wire) Verification Flow**

### Failed

Failed Bank Accounts (Wires) notifications are structured as follows:



The `wire` payload will be a [Wire Account Object](🔗).

### Approved

Approved Bank Accounts (Wires) notifications are structured as follows:



The `wire` payload will be a [Wire Account Object](🔗).

## **Transfer Flow**

### Created

A notification with the structure below is sent on transfer creation.



The `transfer` payload will be a [Transfer Object](🔗).

### Failed

Failed transfers notifications are structured as follows:



The `transfer` payload will be a [Transfer Object](🔗).

### Completed

Completed transfers notifications are structured as follows:



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:



### Failed

Failed conversions notifications are structured as follows: