Serviço de edição de pré-autorização de origem externa
O roteamento GetnetLac permite alterar o valor de uma pré-autorização não capturada, mesmo que a mesma não conste nos registros do Carat. Consulte nosso Suporte para verificar se existem outros roteamentos com esta funcionalidade. Para utilizar essa funcionalidade, basta chamar novamente a operação doPreAuthorization com os dados de uma transação de pré-autorização com status CON (confirmada) com adição do campo amount. Abaixo estão os detalhes dessa chamada.
Atualmente esta funcionalidade permite somente a edição de transações de pré-autorização realizadas no SiTef.
Esta operação possui um passo a mais no fluxo, em relação a uma edição de pré-autorização normal. É preciso que seja criada uma edição de pré-autorização utilizando a operação beginTransaction, que irá gerar um registro no Carat de uma transação com status=NOV, e, retornará ao aplicativo o parâmetro nit, que identificará essa transação.
Criação da edição de pré-autorização com origem externa#
Detalhes da Chamada#
- Recurso:
/v1/transactions - Operação HTTP:
POST - Formato da requisição:
JSON - Formato da resposta:
JSON - Parâmetros de cabeçalho:
| Nome do Parâmetro | Descrição | Tamanho | Obrigatório |
|---|---|---|---|
Content-Type | Valor fixo "application/json" | = 15 A | Sim |
merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes | ≤ 15 A | Sim |
merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | < 80 A | Sim |
Exemplos#
Abaixo estão alguns exemplos de chamada do serviço de criação de transações utilizando a ferramenta cURL.
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#
| Nome do Parâmetro | Descrição | Tamanho | Obrigatório |
|---|---|---|---|
amount | Valor total da compra (em centavos). Exemplo: 1,00 = 100 ou 1.100,00 = 110000 – enviar o valor sem a vírgula e ponto | < 12N | Sim |
encrypted_card | Este campo deve ser enviado com valor "true" caso o número do cartão a ser enviado na próxima etapa do fluxo use a criptografia do SiTef. A opção de envio do cartão criptografado só será possível com roteamento via SiTef e é necessário a configuração prévia do SiTef em questão. Opções: 1. "true" 2. "false" (valor default) | < 5 AN | Não |
merchant_usn | Número sequencial único para cada pedido, criado pela loja. O NSU será utilizado em toda a comunicação com a loja, de forma a identificar o pedido. Como se trata de uma possível chave para acesso do lado da loja, apesar de ser opcional para o Carat, é fortemente recomendado que o campo seja formatado e enviado pela aplicação da loja. | < 12 N | Não |
order_id | Código do pedido para ser exibido ao comprador, definido pelo lojista. É aconselhável que seja diferente a cada pedido para que facilite a rastreabilidade. Se a integração da Loja com as redes adquirentes/roteamentos (Cielo, Redecard, etc) for via SiTef (TEF), o campo orderId que tem o tamanho máximo de 40 caracteres, será reduzido a 12 caracteres, devido a uma restrição do SiTef. Essa redução será realizada mantendo os caracteres da esquerda para direita (ex.: se um código de pedido inserido for 12345678901234567890 no Carat, no SiTef ele será apenas 123456789012). | < 40 AN | Não |
transaction_type | Valor fixo "preauthorization" | = 15 A | Sim |
soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais | < 22 AN | NÃO |
is_transaction_origin_external | Indica se a transação foi originada fora do Carat. Valor fixo "true" | = 5 AN | Sim |
Legenda do tipo do campo "Tamanho":
AN = alfanumérico
N = numérico
N A = não utilizado
Parâmetros de resposta#
| Nome do Parâmetro | Descrição | Tamanho |
|---|---|---|
code | Código de resposta do Carat. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte Códigos de Resposta. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 A |
amount | Valor da transação especificado pela loja (em centavos) na criação da transação. | < 12 N |
merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 N |
nit | Identificador da transação de pré-autorização no Carat. | = 64 A |
order_id | Código de pedido enviado pela loja na criação da transação | < 40 AN |
status | Status da transação de pré-autorização no Carat. | = 3 A |
Efetivação da edição de pré-auto com origem externa#
A efetivação segue o mesmo fluxo de uma edição de pré-autorização originada no Carat, mas é preciso enviar alguns parâmetros a mais na requisição.
Parâmetros de Requisição#
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
| acquirer | Os campos desse elemento só devem ser enviados em casos de transações de origem externa. | ||
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 |
authorizer_id | Código da autorizadora no Carat. Deve ser o mesmo valor enviado no pagamento. | < 3 N | SIM |
host_usn | NSU do host/autorizadora da transação a ser cancelada. | = 9 N | SIM |
authorization_number | Número de autorização da transação a ser cancelada. | < 6 N | SIM |
authorizer_date | Data de efetivação SiTef do pagamento no formato DD/MM/AAAA. | = 10 D | SIM |
order_id | Código do pedido usado na pré-autorização iniciada externamente ao Carat. | < 40 AN | NÃO |
identification_number | CPF ou CNPJ usado na pré-autorização iniciada externamente ao Carat. | < 20 AN | SIM |
terminal | Terminal SiTef que se deseja usar. Se não for enviado, o Carat gerará um terminal aleatório. | = 8 AN | 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 |
Legenda do tipo do campo "Tamanho":
AN = alfanumérico
N = numérico
N A = não utilizado
Nota:#
1 - Quando as informações de terminal e company_code são enviadas, o comportamento do cardquery muda ligeiramente. Neste momento, ao executar o cardquery, o Carat irá identificar a rede retornada pelo SiTef. Uma vez identificada, esta será usada ao invés da cadastrada na loja.
2 - Nas operações de origem externa, não temos como validar a rede que foi utilizada na parte externa da operação, que foi feita fora do Carat. Nestes casos, usamos a rede configurada no SiTef. Por causa disso, mudanças de configuração, se feitas durante o meio da operação, podem ocasionar solicitações inválidas ou negadas. Por exemplo, se uma pré autorização foi feita no meio físico na rede 181 e, antes da finalização da captura, a configuração do SiTef for alterada para a rede 125, as operações que forem feitas via Carat assumirão a rede 125.
ATENÇÃO: Os parâmetros
terminalecompany_codedevem ser enviados simultaneamente. É necessário também solicitar à equipe de atendimento do Carat a permissão Permite envio de Empresa e Terminal SiTef via REST.
Exemplo#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta: