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

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.