Serviço de cancelamento

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 e-SiTef. Os códigos de produção e certificação serão diferentes.	< 15 AN	SIM
`merchant_key`	Chave de autenticação da loja no e-SiTef. 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:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/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":"1005",
      "acquirer_name":"Redecard",
      "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 Cielo e-Commerce

Requisição:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{}
--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":"201",
      "acquirer_name":"Cielo e-Commerce",
      "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:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/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":"1125",
      "acquirer_name":"Cielo",
      "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:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/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":"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":"1005",
      "acquirer_name":"Redecard",
      "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). Caso este campo não seja enviado, o e-SiTef 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 e-SiTef. 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). 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
`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 `DDMMAA`. Obrigatório para cancelamentos via host e origem externa.	= 6 D	COND.
`authorizer_id`	Código da autorizadora no e-SiTef. 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: `0001` - Visa `0080` - Mastercard 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. É obrigatório e utilizado apenas em roteamento via Marisa.	< 6 N	COND.
`refund_type`	Tipo de estorno que se deseja realizar sobre o pagamento. É obrigatório e utilizado apenas para roteamento via Paypal. Valores permitidos: Full - É desejado o estorno completo do pagamento. 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. É 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. Utilizado apenas para roteamento via Paypal.	< 127 AN	NÃO
`note`	Mensagem personalizada para lembretes sobre o estorno. 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. Utilizado apenas para roteamento via Paypal.	< 20 AN	NÃO
`refund_source`	Fonte de fundos do lojista que será utilizado para realizar o estorno. Utilizado apenas para roteamento via Paypal. Valores permitidos: any - O lojista não tem preferência. Será utilizado qualquer fonte de fundos disponível. default - Será utilizado a fonte de fundos configurada na conta do lojista. instant - Será utilizado o balanço do vendedor como fonte de fundos. 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. 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. Utilizado apenas para roteamento via Paypal.	< 5 AN	NÃO
`refund_item_details`	Detalhes do item individual tratado no estorno. 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. Utilizado apenas para roteamento via Paypal.	< 38 AN	NÃO
`terminal_id`	Utilizado caso seja um Ponto de Venda. Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
`store_id`	Utilizado caso seja um Ponto de Venda. Utilizado apenas para roteamento via Paypal.	< 50 AN	NÃO
`terminal`	Terminal SiTef que se deseja usar. Se não for enviado, o e-SiTef 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 e-SiTef 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. 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

ATENÇÃO: Os parâmetros terminal e company_code são para uso somente no Cancelamento origem externa. Neste caso, os mesmos devem ser enviados simultaneamente.
É necessário também solicitar à equipe de atendimento do e-SiTef a permissão Permite envio de Empresa e Terminal Sitef via REST.

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 e-SiTef. Qualquer código diferente de `0`(zero) significa falha. Saiba mais.	< 4 N
`message`	Mensagem de resposta do e-SiTef.	< 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 e-SiTef. Saiba mais.	= 3 AN
`nit`	Número identificador da transação de cancelamento no e-SiTef.	= 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 e-SiTef.	= 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 e-SiTef 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