Cancelamento

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.

Para realizar operações de estorno, é 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_id e merchant_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âmetroDescriçãoFormatoObrigatório
merchant_idCódigo da loja no Carat. Os códigos de produção e certificação serão diferentes.< 15 ANSIM
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM
Content-TypeDeve ser enviado com o valor application/json.= 15 ANSIM
AuthorizationDeve 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 ANCOND.

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/0a5e7dc9ef8ed24819c06a9bc1ed71f653671c931bd33fa49413477352de40d1' \
--header 'Content-Type: application/json' \
--header 'merchant_id: xxxxxxxxxxxxxxx' \
--header 'merchant_key: xxxxxxxxxxxxxxx' \
--header 'Authorization: Bearer {{assinatura}}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"cancellation": {
"authorizer_code": "200",
"authorizer_message": "Refund successful. [Cód.: 359]",
"status": "CON",
"nit": "1c1caed9c650b298e52e8b1acd7d9eb6b6e85bf029dc285f682b86e6283479ac",
"order_id": "1665693831749",
"customer_receipt":"=== COMPROVANTE ===",
"merchant_receipt":"=== COMPROVANTE ===",
"authorizer_id": "2",
"acquirer_id": "202",
"acquirer_name": "e.Rede REST",
"authorizer_date": "08/09/2022T17:43",
"merchant_usn": "12050620649",
"esitef_usn": "221013109643171",
"host_usn": "828420940",
"tid": "221013109643160",
"amount": "1300",
"payment_type": "C",
"esitef_date": "08/09/2022T17:43",
"is_host_cancel": "false"
}
}

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

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/1bfff28297349381d8fc66fd0162c711ea5a61d932077d0109fe5642e7188e74' \
--header 'Content-Type: application/json' \
--header 'merchant_id: xxxxxxxxxxxxxxx' \
--header 'merchant_key: xxxxxxxxxxxxxxx' \
--header 'Authorization: Bearer {{assinatura}}' \
--data-raw '{
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555"
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"cancellation": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "ece6580e54c4bbef28a2f0267ab385a9c87740479acf717a26e60e8f068c6606",
"order_id": "1662748697539",
"customer_receipt":"=== COMPROVANTE ===",
"merchant_receipt":"=== COMPROVANTE ===",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "09/09/2022T15:39",
"authorization_number": "093557",
"merchant_usn": "12050620649",
"esitef_usn": "220909107099221",
"sitef_usn": "093558",
"host_usn": "999093558 ",
"amount": "1100",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"esitef_date": "09/09/2022T15:39",
"is_host_cancel": "false"
}
}

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 - Token Bandeira#

Algumas bandeiras de cartão possuem uma solução de tokenização que oferece o armazenamento de cartões em cofres na própria bandeira, de forma criptografada. Essa tokenização de bandeira tem o intuito de melhorar a segurança e qualidade das informações de cartão trafegadas, o que acarreta em possíveis aumentos na conversão de aprovação pelos bancos emissores.

ParâmetroDescriçãoFormatoObrigatório
card
numberToken gerado pela bandeira (DPAN)≤ 19 NSim
cryptogramCriptograma gerado pela bandeira.= 28 ANão

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/cancellations/e7403160cca530cadb9567222dc3abed55a1db47de2229453e08244dd97bb33b' \
--header 'Content-Type: application/json' \
--header 'merchant_id: xxxxxxxxxxxxxxx' \
--header 'merchant_key: xxxxxxxxxxxxxxx' \
--header 'Authorization: Bearer {{assinatura}}'
--data-raw '{
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "5555555555555555",
"cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA=="
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"cancellation": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "0e6afaa006d85e259bcc776c8694277b4bc8afb8971295325fe1142aa922220c",
"order_id": "1676900808881",
"customer_receipt":"=== COMPROVANTE ===",
"merchant_receipt":"=== COMPROVANTE ===",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "20/02/2023T10:46",
"authorization_number": "203932",
"merchant_usn": "12050620649",
"esitef_usn": "230220004506181",
"sitef_usn": "203939",
"host_usn": "999203939 ",
"amount": "1100",
"payment_type": "C",
"issuer": "2",
"authorizer_merchant_id": "000000000000005",
"esitef_date": "20/02/2023T10:46",
"is_host_cancel": "false"
}
}

Parâmetros de requisição#

Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de cancelamento:

ParâmetroDescriçãoFormatoObrigatório
amountValor 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 NNÃO
cardA obrigatoridade deste objeto depende única e exclusivamente da adquirente utilizada na transação.
numberNúmero do cartão do comprador (PAN).

Token gerado pela bandeira (DPAN) para pagamento com Token Bandeira. Saiba mais
< 19 NSIM
cryptogramCriptograma gerado pela bandeira= 28 ANNÃO
expiry_dateData de vencimento do cartão no formato MMAA.= 4 NCOND.
security_codeCódigo de segurança.< 5 NCOND.

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âmetroDescriçãoFormato
codeCódigo de resposta do Carat. Qualquer código diferente de 0(zero) significa falha. Saiba mais.< 4 N
messageMensagem de resposta do Carat.< 500 AN
cancellationEstes campos só são retornados ao usar autenticação com assinatura.
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_messageMensagem de resposta do autorizador.< 500 AN
statusStatus da transação de pagamento no Carat. Saiba mais.= 3 AN
nitIdentificador da transação de cancelamento no Carat.= 64 AN
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
customer_receiptCupom (via cliente).< 4000 AN
merchant_receiptCupom (via estabelecimento).< 4000 AN
authorizer_idCódigo da autorizadora utilizada na transação.< 4 N
acquirer_idCódigo da adquirente utilizada na transação.< 4 N
acquirer_nameNome da adquirente utilizada na transação.< 100 AN
authorizer_dateData de efetivação do pagamento retornada pelo autorizador no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
authorization_numberNúmero de autorização.< 6 AN
merchant_usnNú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_usnNúmero sequencial único da transação de pagamento no Carat.= 15 N
sitef_usnNúmero sequencial único da transação de pagamento no SiTef.= 6 N
host_usnNSU da autorizadora.< 15 AN
tidID da transação na adquirente. Este campo só é retornado em transações com adquirentes externas ao SiTef.< 40 AN
amountValor 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
issuerCódigo da bandeira retornado pelo autorizador.< 5 AN
authorizer_merchant_idCódigo de afiliação do lojista na autorizadora.< 100 AN
esitef_dateData de efetivação do cancelamento no Carat no formato DD/MM/AAAA'T'HH:mm. Exemplo: 13/07/2017T16:03= 16 D
is_host_cancelEste campo retornará o valor true em caso de cancelamento via host.< 5 T/F
payment_typeTipo 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