Cancelamento Assíncrono

ATENÇÃO: Esta página é um documento em construção, sujeita a alterações sem aviso prévio, e ainda desacoplada da nossa documentação completa. Caso queira acessar toda nossa documentação, acesse aqui.

A funcionalidade de cancelamento assíncrono altera o modo como os cancelamentos são tratados. Como resultado, os cancelamentos não são mais processados imediatamente. Em vez disso, eles entram em uma fila de processamento assíncrono aguardando pare serem canceladas. Essa abordagem permite melhorar a eficiência do processamento, especialmente em casos de alto volume de transações.

Nota: Esta funcionalidade está disponível apenas para BIN.#

Nessa modalidade a resposta inicial de cancelamento ficará como pendente (PEN) e quando processada terá status de confirmado (CON) ou negado (NEG). Em caso de falha do processo, o status de erro (ERR) seria retornado.

Nota: O processo de cancelamento assíncrono atualmente não é suportado para pré-autorizações.#

Configurações necessárias no Carat#

A loja só conseguirá efetuar o cancelamento assíncrono caso possua permissão para esta operação no back office do Carat. Para isso, é necessário comunicar à equipe de cadastro do Carat a respeito dessa demanda específica.

Exemplo#

Requisição:

curl --location 'https://carat url/e-sitef/api/v2/cancellations/{{nit}}'\
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data
{
"amount":"500"
}
--verbose

Resposta:

{
"code":"0",
"message":"OK. Transaction successful.",
"cancellation":{
"authorizer_code":"000",
"authorizer_message":"Transacao OK",
"status":"PEN",
"nit":" nit",
"order_id":"order_id",
"authorizer_id":"1",
"acquirer_id":"2651",
"acquirer_name":"Bin",
"authorization_number":"181093",
"merchant_usn":"12050620649",
"esitef_usn":"230831024018241",
"sitef_usn":"001201",
"amount":"500",
"payment_type":"C"
}
}

WebHook:

Carat enviará uma solicitação POST em formato JSON para a URL de uma Loja.

Aviso de status da solicitação:

{
"nit":" 123",
"order_id":"333",
"esitef_usn":"11",
"status":"CON"
}

** Esteja ciente de que - por motivos de segurança - para receber um aviso de status, a URL de recebimento deve validar o POST via mTLS.

Para isso, um certificado de cliente deve ser emitido pelo estabelecimento comercial e enviado para instalação no Carat. Caso não seja possível a utilização de validação por mTLS o lojista deve, por segurança, sempre validar o status da transação utilizando a API de consulta de transação.

** O Carat também pode enviar novos parâmetros sem aviso prévio, o que significa que a aplicação do lojista deve estar preparada para receber campos extras e simplesmente ignorá-los.

Fluxo do WebHook:

A notificação não enviará o status, por motivos de segurança. A consulta por meio da API é obrigatória.

Figura 1 – Sucesso na notificação do webhook.

Figura 2 – As tentativas de notificação do webhook falham.

Omnipay API Status vs Treatment & Return#

Authorizer resp codeAuthorizer resp msgStatus Transação
0OKCON
0OKPEN
03Invalid Merchant IDNEG
05InvalidNEG
05ErrorPEN
13Invalid AmountNEG
79Invalid Transaction DateNEG
79Mandatory fields missingNEG
93Original Transaction not FoundNEG
98Invalid Merchant IDNEG
108Invalid Merchant Contract StatusNEG
110Invalid Transaction TypeNEG
112Original transaction has a chargebackNEG
113Insufficient FundsNEG
400System ErrorERR
401System ErrorNEG