Post de Notificação

O Post de Notificação é um webhook que envia notificações sobre mudanças no status da transação ou sobre criação de pedido recorrente.

Para receber a notificação de alteração de status da transação (ex.: confirmação de pagamento ou devolução), configure o campo "URL de Notificação" durante o cadastro de sua loja e escolha os eventos para os quais deseja receber notificações. O endereço deve ser HTTPS e não se deve utilizar uma porta fora do padrão HTTPS (443).

ℹ️
A URL configurada deve seguir o padrão Content-type: application/json.

Eventos Notificados

Os eventos passíveis de notificação por meio de pagamento são:

Meio de Pagamento	Eventos que podem ser notificados
Cartão de Crédito	Captura; Cancelamento; Sondagem.
Cartão de débito	Captura; Sondagem.
Boleto	Conciliação; Cancelamento manual.
Transferência eletrônica	Confirmadas.

A notificação ocorre também ocorre em eventos relacionados a Recorrência Programada Cielo

Eventos da Recorrência
Desabilitado ao atingir número máximo de tentativas (transações negadas)
Reabilitação
Finalizado / Data de finalização atingida
Desativação
Criação da transação de recorrência do pedido recorrente.

⚠️
Os eventos só serão notificados se você configurar o recebimento desse tipo de alerta. Você pode configurar a URL de notificação diretamente no site Cielo.

Endpoint de Notificação

Você deve informar um endpoint (URL Status Pagamento), para que o Post de Notificação seja executado.

Características da URL Status Pagamento

Deve ser estática;
Limite de 255 caracteres.

Características do Post de notificação

É disparado a cada 30 minutos;
Em caso de falha, são realizadas três novas tentativas.

Para aumentar a segurança, é possível cadastrar uma informação para retorno do header para o seu endpoint. Com isso, seu endpoint só vai aceitar a notificação se a Cielo enviar o header.

Para configurar as informações do header, informe os itens a seguir:

KEY - Nome do parâmetro. Limitado a 256 caracteres.
VALUE - Valor estático a ser retornado. Limitado a 1500 caracteres.

Você pode cadastrar até 3 tipos de informação de retorno no header.

A loja deverá retornar como resposta à notificação: HTTP Status Code 200 OK.

O conteúdo da notificação será formado por três campos:

RecurrentPaymentId: identificador que representa um conjunto de transações recorrentes;
PaymentId: número de identificação do pagamento;
ChangeType: especifica o tipo de notificação.

Com os dados acima, você poderá identificar a transação via PaymentId ou RecurrentPaymentId e a mudança ocorrida. A partir da notificação, você pode consultar mais detalhes sobre a transação na Consulta por PaymentId ou na Consulta de Recorrência.

Veja o exemplo do conteúdo do Post de Notificação:

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

Propriedade	Descrição	Tipo	Tamanho	Obrigatório
`RecurrentPaymentId`	Identificador que representa o pedido Recorrente (aplicável somente para ChangeType 2 ou 4).	GUID	36	Não
`PaymentId`	Número de identificação do pagamento.	GUID	36	Sim
`ChangeType`	Especifica o tipo de notificação. Veja a tabela de Changetype abaixo.	Número	1	Sim

Tabela de ChangeType

ChangeType	Descrição
1	Indica que houve uma alteração no status na transação. Consulte a transação para verificar o status atual.
2	Recorrência criada.
3	Mudança de status do Antifraude. Exclusivo para clientes integrados ao Antifraude.
4	Mudança de status do pagamento recorrente (Ex. desativação automática).
5	Cancelamento negado.
6	Boleto registrado pago a menor.
7	Notificação de chargeback. Exclusivo para clientes integrados à Risk Notification API (legado)*
8	Alerta de fraude.
25	Transação cancelada ou estornada parcialmente.

⚠️
A API Risk Notification está sendo descontinuada. O novo serviço de consulta, aceite e disputa de chargebacks da Cielo é a API de Chargeback.