Webhook

Receive transaction status change notifications via API

Notification Post is a webhook that sends notifications about changes in transaction status or recurring order creation.

During your Cielo registration, you must set up an endpoint for Cielo to send notifications and you can also configure the events for which you want to receive notifications.

Notified Events

Events that can be notified by payment method are:

Payment MethodEvents that can be notified
Credit CardCapture;
Cancellation;
Queries.
Debit CardCapture;
Queries.
BoletoConciliation;
Manual cancellation

Notification also occurs at events related to Cielo Scheduled Recurrence:

Recurrence Events
Disabled when reaching maximum number of attempts (denied transactions)
Rehabilitation
Finalized / Completion date reached
Deactivation
Creation of the recurring order recurrence transaction.

Events are only notified when you request this type of notification from Cielo Support.

Notification Endpoint

The merchant must report an endpoint (PAYMENT STATUS URL) to Cielo Support so the API can send a notification.

Characteristics of Payment Status URL

  • Must be static;
  • Limit of 255 characters.

Characteristics of Notification Post

  • It is sent every 30 minutes;
  • In the event of a failure, three retries are made.

To increase security, you can register header return information for your endpoint. With this, your endpoint will only accept the notification if Cielo sends the header.

To set up the header information, please inform Cielo Support of the following:

  • KEY - Parameter name
  • VALUE - Static value to be returned

You can register up to 3 types of return information in the header.

The merchant should return in response to the notification: HTTP Status Code 200 OK.

The content of the notification will consist of three fields:

  • RecurrentPaymentId: identifier that represents a set of recurring transactions;
  • PaymentId: payment identification number;
  • ChangeType: specifies the type of notification.

Using this data you can identify the transaction via PaymentId or RecurrentPaymentId and the status change. After the notification, you can get more details about the transaction by getting details via PaymentId or querying for a recurrent payment.

Here's an example of the Notification Post content:

{
  "RecurrentPaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "PaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "ChangeType": 2
}
curl
--header "key: value"
{
   "RecurrentPaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "PaymentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "ChangeType": 2
}
PropertyDescriptionTypeSizeRequired
RecurrentPaymentIdIdentifier representing the Recurring request (only applicable for ChangeType 2 or 4).GUID36No
PaymentIdPayment identification number.GUID36Yes
ChangeTypeSpecifies the type of notification.Number1Yes

ChangeType table

ChangeTypeDescription
1Payment status change.
2Recurrence created.
3Antifraude status change. Exclusive for customers integrated with Antifraude.
4Recurring payment status change (eg automatic deactivation).
5Cancellation denied.
7Chargeback notification. Exclusive for customers integrated with Risk Notification API.
8Fraud alert.