Serviço de criação de cancelamento

O consumo desse serviço é obrigatório no fluxo de cancelamento. Como resultado dessa operação, o lojista obterá um NIT que será necessário para o próximo passo do fluxo.

O NIT possui um tempo limite para sua utilização. Este prazo está configurado no Carat, e caso seja excedido, a transação de cancelamento passará do status NOV (nova) para EXP (expirada), o que impede futuras operações com essa transação, tornando necessário consumir novamente o serviço de criação de cancelamento.

POST de autenticidade x assinatura#

O Carat possui duas formas de autenticação da loja na interface de cancelamento REST: POST de autenticidade ou assinatura.

No método de POST de autenticidade, o Carat enviará os dados da transação de cancelamento recém-criada para a URL de autenticidade cadastrada da loja.

No método de assinatura, 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.

Detalhes da chamada#

Recurso: /v1/cancellations
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`.	< 2000 AN	NÃO

Exemplos#

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

Criação de cancelamento com POST de autenticidade#

Requisição:

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "esitef_usn":"123451234512345"
}
--verbose

Em seguida, o Carat irá enviar uma requisição POST HTTPS (x-www-form-urlencoded) para a URL cadastrada, este POST contém as informações necessárias para o prosseguimento do cancelamento:

POST de autenticidade:

curl -X POST \
  https://dominiodaloja.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d 'nsu=9055020677&nit=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr&pedido=09055020677&codigoLoja=xxxxxxxxxxxxxxx'

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful."
}

Criação de cancelamento com assinatura#

Requisição:

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

curl
--request POST "https://{{url}}/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc"
--data-binary
{
   "esitef_usn":"123451234512345"
}
--verbose

Resposta:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "merchant_usn":"9062259711"
   }
}

Requisição Pix:

curl
--request POST "https://{{url}}/e-sitef/api/v1/cancellations"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "amount":"1000"
}
--verbose

Resposta Pix:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "cancellation":{
      "nit":" 1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"09062259711",
      "merchant_usn":"9062259711"
   }
}

Códigos de resposta

Veja a referencia no Códigos da API - códigos de resposta

Parâmetros de requisição#

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

Parâmetro	Descrição	Formato	Obrigatório
`esitef_usn`	NSU do pagamento a ser cancelado. Essa informação é retornada pelo Carat após o pagamento ser aprovado.	= 15 N	SIM
`order_id`	Código de pedido do pagamento a ser cancelado. Este campo só deve ser enviado em caso de cancelamento via host.	< 40 AN	NÃO
`merchant_usn`	NSU gerado pela loja do pagamento a ser cancelado. Este campo só deve ser enviado em caso de cancelamento via host.	< 12 N	NÃO

Parâmetros do POST de autenticidade#

Na tabela abaixo está a descrição dos parâmetros enviados pelo Carat no POST de autenticidade:

Parâmetro	Descrição	Formato
`nit`	Identificador da transação de cancelamento a ser utilizado na próxima etapa do fluxo.	= 64 AN
`pedido`	Código de pedido do pagamento a ser cancelado.	< 20 AN
`nsu`	NSU gerado pela loja do pagamento a ser cancelado.	< 12 N
`codigoLoja`	Código da loja no Carat.	< 15 AN

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.

Parâmetros de resposta#

Em caso de sucesso, o código de resposta HTTP será 201. 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.
`nit`	Identificador da transação de cancelamento a ser utilizado na próxima etapa do fluxo.	= 64 AN
`order_id`	Código de pedido do pagamento a ser cancelado.	< 20 AN
`merchant_usn`	NSU gerado pela loja do pagamento a ser cancelado.	< 12 N

Home