Cancelamento com Idempotência
Para realizar operações de estorno com idempotência, é necessário chamar o endpoint de cancelamento usando o NIT obtido na autorização da venda. Se a requisição for aprovada pela adquirente, o status dessa transação será alterado para EST (estornada).
Nota: O processo de cancelamento exige autenticação com assinatura por padrão. A loja deve ter uma chave pública de criptografia RSA cadastrada no Carat e deverá montar uma assinatura JWT (JSON Web Tokens) a ser enviada no cabeçalho Authorization. Neste caso, as informações da transação de cancelamento serão retornadas diretamente na resposta do serviço. Saiba mais.#
No entanto, em cenários em que a autenticação mútua (mTLS) esteja habilitada para o lojista, a assinatura deixa de ser obrigatória, bastando enviar as credenciais
merchant_idemerchant_key.
Detalhes da chamada#
- Recurso:
/v2/cancellations/{nit} - Método HTTP:
POST - Formato da requisição:
JSON - Formato da resposta:
JSON - Parâmetros de cabeçalho:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | < 15 AN | SIM |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 AN | SIM |
Content-Type | Deve ser enviado com o valor application/json. | = 15 AN | SIM |
Authorization | Deve ser enviada a assinatura de autenticação da loja no formato Bearer {assinatura}. Exemplo: Bearer JHVGytfdgauygdauiw78264284527852897hagdg. Este campo é obrigatório, a não ser que a loja esteja configurada para se comunicar com autenticação mútua (mTLS) junto ao Carat. | < 2000 AN | COND. |
idempotency_key | É como um código aleatório (identificador), com até 80 caracteres, criado pelo integrador que vai usar a API do Carat. | < 80 N | SIM |
Exemplos#
Cancelamento#
Abaixo estão alguns exemplos de chamada do serviço de realização de cancelamento utilizando a ferramenta cURL.
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
IMPORTANTE: Algumas aquirentes podem exigir o envio de dados de cartão na requisição. Nesses casos, o exemplo a seguir mostra como deverá ser feita essa requisição.
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Na resposta da requisição de cancelamento também é retornado um nit. Esse nit é o identificador da transação de cancelamento no Carat. Portanto, o mesmo deve ser usado somente na API de consulta para consultar os dados desse cancelamento.
Cancelamento - Utilizando o mesmo idempotency_key e mesmo payload#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Pode acontecer de vir campos a mais na segunda chamada, mas todos os campos da primeira requisição serão retornados
Resposta:
Cancelamento - Utilizando o mesmo idempotency_key e payload com amount diferente#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Parâmetros de requisição#
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de cancelamento:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
amount | Valor em centavos a ser cancelado. É importante notar que não são todas as adquirentes que suportam estorno com valor menor do que o do pagamento (cancelamento parcial). Caso este campo não seja enviado, o Carat assumirá o valor total do pagamento. | < 12 N | NÃO |
| card | A obrigatoridade deste objeto depende única e exclusivamente da adquirente utilizada na transação. | ||
number | Número do cartão do comprador (PAN). Token gerado pela bandeira (DPAN) para pagamento com Token Bandeira. Saiba mais | < 19 N | SIM |
cryptogram | Criptograma gerado pela bandeira | = 28 AN | NÃO |
expiry_date | Data de vencimento do cartão no formato MMAA. | = 4 N | COND. |
security_code | Código de segurança. | < 5 N | COND. |
Parâmetros de resposta#
Em caso de sucesso, o código de resposta HTTP será 200. Qualquer outro código deve ser interpretado como erro. Na tabela abaixo está a descrição dos parâmetros de resposta do serviço de criação de cancelamento:
| Parâmetro | Descrição | Formato |
|---|---|---|
code | Código de resposta do Carat. Qualquer código diferente de 0(zero) significa falha. Saiba mais. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
cancellation | Estes campos só são retornados ao usar autenticação com assinatura. | |
authorizer_code | Código de resposta do autorizador. | < 10 AN |
authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
status | Status da transação de pagamento no Carat. Saiba mais. | = 3 AN |
nit | Identificador da transação de cancelamento no Carat. | = 64 AN |
order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
customer_receipt | Cupom (via cliente). | < 4000 AN |
merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
acquirer_id | Código da adquirente utilizada na transação. | < 4 N |
acquirer_name | Nome da adquirente utilizada na transação. | < 100 AN |
authorizer_date | Data de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
authorization_number | Número de autorização. | < 6 AN |
merchant_usn | Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o Carat, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja. | < 12 N |
esitef_usn | Número sequencial único da transação de pagamento no Carat. | = 15 N |
sitef_usn | Número sequencial único da transação de pagamento no SiTef. | = 6 N |
host_usn | NSU da autorizadora. | < 15 AN |
tid | ID da transação na adquirente. Este campo só é retornado em transações com adquirentes externas ao SiTef. | < 40 AN |
amount | Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto. | < 12 N |
issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
esitef_date | Data de efetivação do cancelamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
is_host_cancel | Este campo retornará o valor true em caso de cancelamento via host. | < 5 T/F |
payment_type | Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = transferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service | = 1 AN |