Serviço de cancelamento

import ApiDoc from '../../src/components/api-doc/ApiDoc'; import ResponseCodes from './codigos-de-resposta.md';

Após obter um NIT de cancelamento na etapa anterior, a loja poderá realizar o estorno de fato.

Após um cancelamento bem-sucedido, a transação de pagamento mudará seu status para EST (estornada). Dependendo do adquirente, é possível realizar estornos parciais, ou seja, cancelar um valor menor do que o que foi pago. Nesse caso, a transação de pagamento manterá o status CON.

Detalhes da chamada

Recurso: /v1/cancellations/{nit}
Método HTTP: PUT
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

Exemplos

Abaixo estão alguns exemplos de chamada do serviço de cancelamento utilizando a ferramenta cURL.

Cancelamento de pagamento via SiTef

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request PUT "https://{{url}}/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "security_code":"123",
      "number":"5555555555555555",
      "expiry_date":"1222"
   },
   "amount":"1000"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"229",
      "acquirer_name":"Bin",
      "authorizer_date":"09/11/2017T18:23",
      "authorization_number":"092423",
      "merchant_usn":"9062259711",
      "esitef_usn":"171109108051261",
      "sitef_usn":"092424",
      "host_usn":"999092424   ",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005",
      "esitef_date":"09/11/2017T18:23",
      "is_host_cancel":"false"
   }
}

Cancelamento de pagamento via BIN

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request PUT "https://{{url}}/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
&#123;&#125;
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"0",
      "authorizer_message":"Operation Successful",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"10022938077",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"229",
      "acquirer_name":"BIN",
      "merchant_usn":"10022938091",
      "esitef_usn":"171110108163221",
      "amount":"1000",
      "payment_type":"C",
      "authorizer_merchant_id":"zzzzzzzzzzzzzzzzzz",
      "esitef_date":"10/11/2017T14:29",
      "is_host_cancel":"false"
   }
}

Cancelamento via host

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request PUT "https://{{url}}/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "number":"455182001234512345"
   },
   "amount":"2000",
   "acquirer":{
      "host_usn":"123123123",
      "sitef_usn":"123123",
      "authorizer_date":"090917",
      "authorizer_id":"1",
      "tef_product_code":"0001",
      "tef_flow_code":"01",
      "authorization_number":"123456"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK!",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"1",
      "acquirer_id":"229",
      "acquirer_name":"BIN",
      "authorizer_date":"09/11/2017T18:42",
      "authorization_number":"092425",
      "esitef_usn":"171109108051271",
      "sitef_usn":"092425",
      "host_usn":"000092425   ",
      "amount":"2000",
      "payment_type":"C",
      "authorizer_merchant_id":"020001355570001",
      "esitef_date":"09/11/2017T18:42",
      "is_host_cancel":"true"
   }
}

Cancelamento origem externa

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor<br/> <URLPOSTMAN/>

curl
--request PUT "https://{{url}}/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "number":"455182001234512345"
   },
   "amount":"2000",
   "acquirer":{
      "routing_id": "5", 
      "host_usn":"123123123",
      "sitef_usn":"123123",
      "authorizer_date":"090917",
      "authorizer_id":"2",
      "authorization_number":"123456"
   }
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK!",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "customer_receipt":"=== COMPROVANTE ===",
      "merchant_receipt":"=== COMPROVANTE ===",
      "authorizer_id":"2",
      "acquirer_id":"229",
      "acquirer_name":"Bin",
      "authorizer_date":"09/11/2017T18:42",
      "authorization_number":"092425",
      "esitef_usn":"171109108051271",
      "sitef_usn":"092425",
      "host_usn":"000092425   ",
      "amount":"2000",
      "payment_type":"C",
      "authorizer_merchant_id":"020001355570001",
      "esitef_date":"09/11/2017T18:42"
   }
}

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 todos os adquirentes que suportam estorno com valor menor do que o do pagamento (cancelamento parcial).<br/>Caso este campo não seja enviado, o Carat utilizará o valor total do pagamento.	< 12 N	NÃO
`soft_descriptor`	Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais	< 30 AN	NÃO
card
`number`	Número do cartão do comprador (PAN). Obrigatório no cancelamento de pagamentos via SiTef.	< 19 N	COND.
`expiry_date`	Data de vencimento do cartão no formato `MMAA`. Sua obrigatoriedade depende do adquirente escolhido.	= 4 N	COND.
`security_code`	Código de segurança. Obrigatório dependendo do contrato firmado com as redes adquirentes.	< 5 N	COND.
`token`	HASH de um cartão armazenado no Carat. Não é permitido enviar um número de cartão aberto (campo `number`) e um cartão armazenado (campo `token`) na mesma requisição.	= 88 AN	NÃO
`wallet_transaction_id`	ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para as autorizadoras Visa Checkout e VEE (via CardSE via SiTef).<br/>Não é permitido enviar um número de cartão aberto (campo `number`), um cartão armazenado (campo `token`) e um `wallet_transaction_id` na mesma requisição.	< 25 AN	NÃO
acquirer	Os campos desse elemento só devem ser enviados em casos de cancelamentos via host, cancelamentos de origem externa ou cancelamentos de roteamentos via PayPal.
`routing_id`	Informação do roteamento utilizado para o pagamento efetuado fora do Carat. Esta informação, se enviada, é utilizada para identificar o roteamento no SiTef. Esta informação só faz sentido nas transações de origem externa.	< 5 N	NÃO
`host_usn`	NSU do host/autorizadora da transação a ser cancelada. Obrigatório para cancelamentos via host e origem externa.	= 20 N	COND.
`sitef_usn`	NSU do SiTef da transação a ser cancelada. Obrigatório para cancelamentos via host e origem externa.	= 6 N	COND.
`authorizer_date`	Data de efetivação SiTef do pagamento no formato `DD/MM/AAAA`. Obrigatório para cancelamentos via host e origem externa.	= 6 D	COND.
`authorizer_id`	Código da autorizadora no Carat. Deve ser o mesmo valor enviado no pagamento. Obrigatório para cancelamentos via host e origem externa.	< 3 N	COND.
`tef_product_code`	Código do produto TEF obtido no pagamento. Este campo pode receber os seguintes valores:<br/>`0001` - Visa<br/>`0080` - Mastercard<br/> Estes valores podem ser alterados pela Cielo sem aviso prévio. Obrigatório para cancelamentos via host e origem externa para roteamento via Cielo.	< 4 N	COND.
`tef_flow_code`	Código do fluxo TEF obtido no pagamento. Atualmente, este campo pode apenas receber o valor `01` (fluxo crédito). Obrigatório para cancelamentos via host e origem externa para roteamento via Cielo.	< 2 N	COND.
`authorization_number`	Número de autorização da transação a ser cancelada. Obrigatório para cancelamentos via host e origem externa.	< 60 N	COND.
`product_code`	Códido de produto.<br/> É obrigatório e utilizado apenas em roteamento via Marisa.	< 6 N	COND.
`refund_type`	Tipo de estorno que se deseja realizar sobre o pagamento.<br/> É obrigatório e utilizado apenas para roteamento via Paypal.<br/><br/>Valores permitidos: <br/><br/>Full - É desejado o estorno completo do pagamento. <br/><br/>Partial - É desejado o estorno parcial do pagamento	< 7 AN	COND.
`currency_code`	Código da moeda a ser utilizada no estorno de acordo com a ISO 4217. Para o Real, o código utilizado é o BRL.<br/> É obrigatório e utilizado apenas para roteamento via Paypal.	< 3 AN	COND.
`invoice_id`	Código de pedido do estorno próprio do lojista para futura consulta ou rastreamento.<br/> Utilizado apenas para roteamento via Paypal.	< 127 AN	NÃO
`note`	Mensagem personalizada para lembretes sobre o estorno.<br/> Utilizado apenas para roteamento via Paypal.	< 256 AN	NÃO
`retry_until`	Data e hora limite até a qual será realizada a tentativa do estorno. Formato: AAAA-MM-DDTHH:MM:SS.<br/> Utilizado apenas para roteamento via Paypal.	< 20 AN	NÃO
`refund_source`	Fonte de fundos do lojista que será utilizado para realizar o estorno. <br/> Utilizado apenas para roteamento via Paypal.<br/><br/>Valores permitidos:<br/><br/>any - O lojista não tem preferência. Será utilizado qualquer fonte de fundos disponível.<br/><br/>default - Será utilizado a fonte de fundos configurada na conta do lojista.<br/><br/>instant - Será utilizado o balanço do vendedor como fonte de fundos.<br/><br/>eCheck - Será utilizado a opção “eCheck” como fonte de fundos. Se o balanço do lojista puder cobrir o estorno, será utilizado o balanço.	< 7 AN	NÃO
`merchant_store_details`	Informações sobre o estabelecimento do lojista.<br/> Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
`refund_advice`	Indicador para cliente que já foi recebeu algum estorno da determinada transação.<br/> Utilizado apenas para roteamento via Paypal.	< 5 AN	NÃO
`refund_item_details`	Detalhes do item individual tratado no estorno.<br/> Utilizado apenas para roteamento via Paypal.		NÃO
`msg_sub_id`	Esse ID identificará de maneira única a mensagem e poderá ser utilizado para requisitar os últimos resultados de um requisição anterior sem a necessidade de criar uma nova requisição. Isso pode ser realizado, por exemplo, em chamadas que foram canceladas por timeout ou erros durante o processo.<br/> Utilizado apenas para roteamento via Paypal.	< 38 AN	NÃO
`terminal_id`	Utilizado caso seja um Ponto de Venda.<br/> Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
`store_id`	Utilizado caso seja um Ponto de Venda.<br/> Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
`terminal`	Terminal SiTef que se deseja usar. Se não for enviado, o Carat gerará um terminal aleatório.	= 14 N	NÃO
`company_code`	Código de empresa SiTef que se deseja usar. Se não for enviado, o Carat enviará o código de empresa cadastrado na loja.	= 8 N	NÃO
acquirer.submerchant_split[]	Consiste em um array para transações split, exclusivos para roteamentos BIN e Sipag, ambos via SiTef. Permite a divisão de partes do valor total do pagamento entre outras empresas.<br/>O máximo de itens permitido neste array é de 5 itens. Cada item é composto pelos campos `submechant_code` e `submerchant_amount`.
`submerchant_code`	código de estabelecimento BIN/Sipag	< 51 AN	NÃO
`submerchant_amout`	Valor de transação referente ao estabelecimento	< 12 N	NÃO
`ecomm_pos_ref`	Este campo enviará uma identificação que constará no campo PDV do relatório do SiTef Web para transações e-commerce.	< 8 AF	NÃO

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 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
`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 cancelamento no Carat. Saiba mais.	= 3 AN
`nit`	Número 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
`merchant_usn`	Número sequencial único enviado pela loja na criação da transação.	< 12 N
`amount`	Valor do cancelamento especificado pela loja (em centavos).	< 12 N
`sitef_usn`	Número sequencial único da transação de cancelamento no SiTef.	= 6 N
`esitef_usn`	Número sequencial único da transação de cancelamento no Carat.	= 15 N
`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 do adquirente utilizado na transação.	< 4 N
`acquirer_name`	Nome do adquirente utilizado na transação.	< 100 AN
`authorizer_date`	Data de efetivação do cancelamento 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
`host_usn`	NSU da autorizadora.	< 20 AN
`tid`	ID da transação no adquirente. Este campo só é retornado em transações com adquirentes externos ao SiTef.	< 40 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
`issuer`	Código da bandeira retornado pelo autorizador.	< 5 AN
`authorizer_merchant_id`	Código de afiliação do lojista na autorizadora.	< 100 AN
`is_host_cancel`	Este campo retornará o valor `true` em caso de cancelamento via host.	< 5 T/F