Serviço de criação de cancelamento
import ApiDoc from '../../src/components/api-doc/ApiDoc'; import ResponseCodes from './codigos-de-resposta.md';
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
<ApiDoc method="post" path="/e-sitef/api/v1/cancellations" />
- 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 {TOKEN_JWT_EXAMPLE}. | < 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<br/> <URLPOSTMAN/>
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<br/> <URLPOSTMAN/>
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 {TOKEN_JWT_EXAMPLE}"
--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"
}
}
<ResponseCodes />
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 |