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 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
esitef-homologacao.softwareexpress.com.br
Resposta:
Cancelamento de pagamento via BIN#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Cancelamento via host#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Códigos de resposta
Veja a referencia no Códigos da API - códigos de resposta
Cancelamento origem externa#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
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 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). 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:0001 - Visa0080 - MastercardEstes 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 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. 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 |