Pré-Autorização
Visão Geral#
O Carat é um gateway de pagamentos multisserviços com capacidade de processamento de transações de cartões de crédito, transferência bancária, geração de boletos, integração com opções de mobile payment, entre outros serviços que podem ser facilmente agregados à plataforma.
O Carat possui duas interfaces para integração com a Loja Virtual, Interface HTML e Web Services, possibilitando a maneira adequada de interação da loja com o Carat, conforme a linguagem e plataforma de execução da loja virtual.
A interface REST disponibiliza pagamentos com cartão de crédito, pré-autorização, captura de pré-autorização e recarga de celular pré-pago.
Para pagamentos via banco como transferência bancária, boleto, utilize a Interface HTML; a recarga de celular pré-pago também está disponível na Interface HTML.
Processo de Certificação#
O processo de certificação da aplicação integrada ao Carat será realizado pela equipe do Suporte Autorizadores/Carat. É de responsabilidade do cliente informar ao Suporte técnico que o desenvolvimento do aplicativo foi finalizado, para que sejam tomadas as devidas providências para a realização da certificação.
Para tanto, o cliente deverá entrar em contato com autorizadores5317@softwareexpress.com.br
Somente estará apto para a entrada em Produção o aplicativo que finalizar o processo de Certificação com sucesso; a Certificação, portanto, é um processo obrigatório
Roteamentos Suportados#
A funcionalidade de pré-autorização do Carat suporta os seguintes roteamentos:
- Rede (via SiTef)
- Cielo (via SiTef)
- Amex (via SiTef)
- GetNetLac (via SiTef)
- Safra (via SiTef)
- Adiq (via SiTef)
- BIN (via SiTef)
- Sipag (via SiTef)
- iCards (via SiTef)
- e-Rede
- GetNet WS
- GlobalPayments WS
- Cielo e-Commerce
- Stone WS
- EPX
Configurações necessárias no Carat#
O uso da funcionalidade de Pré Autorização sempre deve ter sua permissão habilitada pelas equipes de Suporte (ambiente de Certificação) e Produção (ambiente de Produção).
Integração de Pré-Autorização, Captura de Pré-Autorização e Cancelamento via Web Service REST#
O propósito deste documento é descrever a interface de pré-autorização via REST onde a coleta dos parâmetros será realizada pela Loja Virtual e o Carat apenas se encarrega de realizar a transação junto à rede adquirente/roteamento.
A pré-autorização é uma transação cujo valor será reservado do limite do cartão, porém não será debitado imediatamente, podendo ser capturado posteriormente por um valor igual ou menor que o autorizado. O prazo para realizar a captura, assim como a possibilidade de capturar valores menores vai depender da negociação com a rede adquirente/roteamento, caberá a Loja Virtual consultar a rede adquirente/roteamento.
O cancelamento da pré-autorização pode ser realizado para disponibilizar novamente o valor reservado do limite do cartão, caso ainda a captura da pré-autorização não seja realizada.
Após a conclusão da transação de captura da pré-autorização, a mesma também poderá ser estornada. Para mais detalhes sobre o cancelamento e estorno, o documento Interface Web Service REST de Pagamento, Agendamento e Cancelamento deve ser consultado. Caso o lojista não tenha este em mãos, deve solicitar às equipes de atendimento do Carat.
Fluxo de Pré-Autorização, Captura e Consulta de Status#
O fluxo de pré-autorização será iniciado pela Loja Virtual quando o aplicativo enviar a operação beginTransaction (Figura 1), na resposta da requisição o aplicativo receberá o nit (identificador da transação) e outros parâmetros (Tabela 2). O nit recebido no beginTransaction juntamente com outros parâmetros (Tabela 3), serão enviados pela Loja Virtual na operação doPreAuthorization e deverá tratar os parâmetros recebidos na resposta da requisição de beginTransaction. Posteriormente (conforme a regra de negócio) o mesmo nit enviado na pré-autorização, deverá ser enviado na operação capture juntamente com outros parâmetros (Tabela 9) e deverá tratar os parâmetros recebidos no webservice response.
Se ocorrer uma falha no recebimento do webservice response (i.e, timeout) do doPreAuthorization ou do capture, a aplicação da loja obrigatoriamente deverá realizar a consulta de status com a operação getStatus, para verificar o resultado da transação.
No caso do aplicativo não receber a resposta da operação beginTransaction, não será necessário realizar a operação getStatus, basta que o aplicativo realize novamente o beginTransaction. Porque nesse momento, ainda não houve o envio da transação que comprometerá o limite ou a cobrança na fatura do cartão do cliente.
A consulta de status (getStatus) é de extrema importância para evitar que ocorra a cobrança indevida (possível cobrança em duplicidade ou cobrança sem o recebimento do produto/serviço) na fatura do cliente. As figuras abaixo ilustram os fluxos:
Pré-Autorização#
Toda a comunicação será realizada via HTTPS/TLS, e é importante que o servidor do lojista suporte criptografia com no mínimo 128 bits e protocolo mínimo TLS 1.2. O servidor de aplicação da Loja Virtual realizará a chamada no endereço para pré-autorização via Web Service, conforme descrito abaixo, de acordo com o ambiente em questão.
URL do ambiente de Certificação/testes:
https://{{url}}/e-sitef/api/
URL do ambiente de Produção:
https://esitef-ec.softwareexpress.com.br/e-sitef/api/
Atenção: Nunca utilizar o IP ao invés do domínio esitef-ec.softwareexpress.com.br, porque o IP poderá mudar a qualquer momento e sem aviso prévio, portanto, é importante a utilização do domínio para acesso ao Carat.
Web Service possui as seguintes operações: beginTransaction, doPreAuthorization, capture, doCardQuery e getStatus.
Outras operações poderão ser incluídas sem aviso prévio.
Importante: Além dos parâmetros de resposta do webservice descrito nesta especificação, o Carat poderá retornar outros parâmetros sem aviso prévio. É importante que o aplicativo esteja preparado para receber parâmetros extras além dos parâmetros já especificados e simplesmente desprezá-los.
Operação beginTransaction – criação de transação#
Parâmetros de requisição da operação beginTransaction#
O fluxo da transação de Pré-Autorização é iniciado consumindo 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.
O nit tem um prazo de utilização configurado no Carat, se esse tempo limite exceder a transação passará do status “NOV” para o status “EXP”. Neste caso não será mais permitido a utilização do mesmo nit, sendo necessário consumir novamente a operação beginTransaction para gerar outro nit válido.
A operação beginTransaction deverá ser enviado com os parâmetros da tabela abaixo.
- 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 |
| 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 A | Não | | transaction_type | Valor fixo “preauthorization” | = 15 A | Sim |
Legenda do tipo do campo “Tamanho”:
A = alfanumérico
N = numérico
N A = não utilizado
Parâmetros de resposta da operação beginTransaction#
A tabela abaixo mostra os parâmetros de resposta da operação beginTransaction:
| 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 o documento "Anexo A-2 - Codigos 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 A |
| status | Status da transação de pré-autorização no Carat. | = 3 A |
Exemplo de requisição
Exemplo de resposta
Operação doPreAuthorization - efetivação da pré-autorização#
O nit obtido no retorno da operação beginTransaction, deverá ser enviado na operação doPreAuthorization juntamente com os parâmetros descritos na tabela abaixo (conforme a necessidade de cada aplicação):
- Recurso: /v1/preauthorizations/{nit}
- Método 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 |
Parâmetros de requisição da operação doPreAuthorization
| Nome do parâmetro | Descrição | Tamanho | Obrigatório |
|---|---|---|---|
| authorizer_id | Código da autorizadora no Carat. Ver documento Anexo A – Autorizadoras Carat. | ≤ 3 N | Sim |
| customer_id | Documento de identidade do comprador. Use apenas caracteres alfanuméricos (sem pontos, traços ou outros caracteres especiais). | ≤ 20 A | Não |
| discount | Valor do desconto, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente. | N | Não |
| installments | Juntamente com o campo installmenttype, indica parcelamento (**), utilizados _APENAS com autorizadoras roteadas, e-Rede, GetNetLac via SiTef, Rede via SiTef e iCards via SiTef. Envie ‘1’ para transações à vista. | < 2 N | Condicional |
| installment_type | Juntamente com o campo installments, indica parcelamento (), utilizados APENAS com autorizadoras roteadas por e-Rede, GetNetLac via SiTef, Rede via SiTef e iCards via SiTef. Para as demais roteamentos, o parcelamento é possível somente na captura. Os valores possíveis para installment_type são: 3: Parcelamento com juros da administradora do cartão 4**: Parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista) | = 1 N | Condicional |
| mcc | Merchant Category Code - Indica o código de categoria da loja. Necessário ao utilizar subadquirência Stone WS. | < 4 N | Obrigatório apenas para subadquirência Stone WS |
| merchant_email | e-mail da Loja. Este parâmetro quando enviado sobrescreve o e-mail do cadastro da Loja. | ≤ 40 A | Opcional |
| nit | Identificador da transação no Carat (criptografado). Obtido no retorno da chamada ao beginTransaction. | = 64 A | Sim |
| promo_code | Código de promoção Visa Checkout utilizado na pré-autorização. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente. | A | Não |
| soft_descriptor | Texto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. funcionalidade disponível apenas para as redes adquirentes/roteamentos e-Rede e Bin via SiTef. | ≤ 30 A | Não |
| subtotal | Valor do subtotal, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente. | N | Não |
| expiry_date | Data de vencimento do cartão no formato MMAA. | = 4 N | Sim |
| holder | Nome do portador do cartão. Obrigatório apenas para roteamentos e-Rede, GetNet WS e VR (SmartNet). | ≤ 30 A | Condicional |
| security_code | Código de segurança. | ≤ 5 N | Sim |
| number (*) | Número do cartão do comprador (PAN). Obrigatório utilizar um entre os campos (number, token ou initial_wallet_transaction_id) | ≤ 19 N | Sim |
| token (*) | Utilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do Carat. | = 88 A | Condicional |
| wallet_transaction_id(*) | Código de identificação de transação com wallet Visa Checkout. Sobre o uso de Visa Checkout, por favor ver o documento Anexo M-1 - VisaCheckout via WS | < 25 A | Condicional |
| initial_wallet_transaction_id | Informa se o Wallet ID (WALLET_TRANSACTION_ID) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário, enviar false. Possíveis valores: true/false Valor default: true | < 5 A | Necessário apenas para Visa Checkout |
(*) Obrigatório utilizar apenas um entre os campos: number, token ou initial_wallet_transaction_id
() Parcelamento roteada por GetNetLac via SiTef: Neste caso, a loja será responsável pelo controle do parcelamento, logo não entrarão em vigor as regras de parcelamento configuradas para a interface de pagamento HTML do Carat, somente as regras de parcelamento da autorizadora serão verificadas e aplicadas. Para estas redes mencionadas, caso a pré-autorização seja feita à vista, a captura não pode ser parcelada. Ainda, pré- autorizações roteadas por GetNetLac via SiTef, quando parceladas, apenas são aceitos sem juros, isto é, com o parâmetro installment_type = 4**. Parcelamentos sem juros não são aceitos para este roteamento.
Parâmetros de resposta da operação doPreAuthorization#
A tabela abaixo contém os parâmetros de resposta da operação doPreAuthorization. O aplicativo deverá armazenar os parâmetros que achar necessário. Sugerimos que sejam armazenados os parâmetros: order_id, authorization_number, merchant_usn, esitef_usn, sitef_usn, host_usn, status, code, amount, message (o parâmetro message poderá ser exibido ao cliente).
| 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 o documento Anexo A-2 - Codigos de Resposta. | < 4 N |
| message | Mensagem de resposta do Carat. | < 500 AN |
| acquirer_id | Código do adquirente/roteamento utilizado na transação. | < 4 N |
| acquirer_name | Nome do adquirente/roteamento utilizado na transação. | < 100 AN |
| amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 AN |
| authorization_number | Número de autorização. | < 6 AN |
| authorizer_code | Código de resposta do autorizador. | < 10 AN |
| authorizer_date | Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
| authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
| authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
| authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
| customer_receipt | Cupom (via cliente). | < 4000 AN |
| eci | Eletronic Commerce Indicator (indicador do nível de segurança da transação da pré-autorização via Cielo e-Commerce). | < 3 AN |
| esitef_usn | Número sequencial único da transação de pré-autorização no Carat. | = 15 N |
| host_usn | NSU da autorizadora. | < 15 AN |
| issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
| merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
| merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 AN |
| nit | Identificador da transação de pré-autorização no Carat. | = 64 AN |
| order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
| payment_type | Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios e pagamentos, W = Boleto NR via Web Service | = 1 A |
| sitef_usn | Número sequencial único da transação de pré-autorização no SiTef. | = 6 N |
| status | Status da transação de pré-autorização no Carat. | = 3 AN |
| tid | ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 AN |
| xid | Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos. | < 40 AN |
Exemplo de requisição#
Exemplo de resposta#
Operação editPreAuthorization - alteração de valor de pré-autorização#
Para o roteamento GetNetLac via SiTef é possível alterar o valor de uma pré-autorização não capturada. 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.
| Nome do Parâmetro | Descrição | Tamanho | Obrigatório |
|---|---|---|---|
| nit | Identificador da transação no Carat. Obtido no retorno da chamada ao beginTransaction. | = 64 A | Sim |
| authorizer_id | Código da autorizadora no Carat. Ver documento Anexo A – Autorizadoras Carat. | ≤ 3 N | Sim |
| amount | Valor total da compra (em centavos). | ≤ 12 N | Sim |
| number | Número do cartão do comprador (PAN). | ≤ 19 N | Sim |
| token | Utilizado para casos de pagamento recorrente, onde o cartão já deverá estar armazenado na base de dados do Carat. Obrigatório utilizar um entre os campos (number, token ou initial_wallet_transaction_id) | = 88 A | Condicional |
| expiry_date | Data de vencimento no formato MMAA. | = 4 N | Sim |
| security_code | Código de segurança. | ≤ 5 N | Sim |
Os campos de resposta são os mesmos da operação doPreAuthorization, descritos na Tabela 6.
Em caso de sucesso, será retornado o responseCode ‘0’. O status da transação não será alterado em hipótese alguma (sucesso ou falha). Porém, os campos sitef_usn, host_usn, authorization_number, sitef_date, customer_receipt e merchant_receipt sofrerão mudanças caso a alteração seja confirmada.
Operação capture – captura de pré-autorização#
A captura da Pré-Autorização tem como objetivo a efetivação da Pré-Autorização, que poderá ser no valor total ou inferior ao valor total da Pré-Autorização. Isso vai depender da regra de negócio da aplicação da Loja Virtual.
O fluxo seria, realizar a operação doPreAuthorization e se o resultado for aprovado, a operação capture deverá ser consumido para completar o fluxo. A captura será realizada no momento definido pelas regras de negócios da aplicação.
Na operação capture o parâmetro amount pode ter o valor igual ou menor ao valor do parâmetro amount da pré-autorização.
Para o roteamento GetNetLac via SiTef, o parcelamento pode ser feito também na etapa de pré-autorização e nesse caso, a captura deve receber um número de parcelas igual ou superior ao enviado anteriormente. Caso a pré- autorização seja feita à vista, a captura não pode ser parcelada.
Em caso de captura de transações de pré-autorização HTML, as parcelas e o tipo de financiamento seguem obrigatoriamente os valores definidos na pré-autorização. Logo neste caso não há a possibilidade de alteração destes valores no momento da captura.
Detalhes da chamada#
Recurso: /v1/preauthorizations/capture/{nit}
Método 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 |
Parâmetros da requisição da operação capture#
| Nome do Parâmetro | Descrição | Tamanho | Obrigatório |
|---|---|---|---|
| amount | Valor total da compra (em centavos). | ≤ 12 N | Sim |
| discount | Valor do desconto, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente. | N | Não |
| installments (*) | Número de parcelas, 1 = à vista | ≤ 2 N | Sim |
| installment_type | Juntamente com o campo installments, indica parcelamento. Os valores possíveis para installment_type são: 3: Parcelamento com juros da administradora do cartão 4: Parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista) | = 1 N | Sim |
| promo_code | Código de promoção Visa Checkout utilizado no pré-autorização. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente. | A | Não |
| subtotal | Valor do subtotal, em centavos. Em caso de pré-autorizações com valores promocionais pelo uso do Visa Checkout, a VISA sugere que este campo seja enviado adicionalmente. | N | Não |
| number (**) | Número do cartão do comprador (PAN). | ≤ 19 N | Sim |
| token (**) | Utilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do Carat. | = 88 A | Condicional |
| wallet_transaction_id (**) | Código de identificação de transação com wallet VisaCheckout. | < 25 A | Necessário apenas para Visa Checkout |
| initial_wallet_transaction_id | Informa se o Wallet ID (WALLET_TRANSACTION_ID) está sendo utilizado pela primeira vez. Se for a primeira vez, enviar true, caso contrário, enviar false. Possíveis valores: true/false Valor default: true | < 5 A | Necessário apenas para Visa Checkout |
| acquirer.submerchant_split[] | Consiste em um array para pagamentos 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. | Não | |
| submerchant_code | código de estabelecimento BIN/Sipag | ≤ 15 AN | Não |
| submerchant_amount | valor de transação referente ao estabelecimento | ≤ 12 N | Não |
(*) installments: O número máximo de parcelas configurado no portal Carat do lojista não será verificado neste campo, servindo somente para pagamentos HTML.
() Obrigatório utilizar apenas um** entre os campos: number, token ou initial_wallet_transaction_id
Parâmetros de resposta da operação capture#
| 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 o documento anexo A-2 - Codigos de Resposta. | < 4 N |
| message | Mensagem de resposta do Carat. | < 500 AN |
| acquirer_id | Código do adquirente/roteamento utilizado na transação. | < 4 N |
| acquirer_name | Nome do adquirente/roteamento utilizado na transação. | < 100 AN |
| amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 AN |
| authorization_number | Número de autorização. | < 6 AN |
| authorizer_code | Código de resposta do autorizador. | < 10 AN |
| authorizer_date | Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
| authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
| authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
| authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
| customer_receipt | Cupom (via cliente). | < 4000 AN |
| eci | Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce). | < 3 AN |
| esitef_usn | Número sequencial único da transação de pré-autorização no Carat. | = 15 N |
| host_usn | NSU da autorizadora. | < 15 AN |
| issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
| merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
| merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 AN |
| nit | Identificador da transação de pré-autorização no Carat. | = 64 AN |
| payment_type | Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service | = 1 A |
| sitef_usn | Número sequencial único da transação de pré-autorização no SiTef. | = 6 N |
| status | Status da transação de pré-autorização no Carat. | = 3 AN |
| tid | ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 AN |
| xid | Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos. | < 40 AN |
Exemplo de requisição#
Exemplo de resposta#
Operação doCardQuery - consulta de cartão#
A partir de um NIT de pré autorização com status NOV (novo), é possível realizar uma consulta do BIN do cartão (seis primeiros dígitos) no SiTef para obter dados sobre suas capacidades (possibilidade de pagamento parcelado, máximo de parcelas, exigência de código de segurança, etc.), ou ainda, saber qual autorizadora da loja é a mais adequada para a realização do pagamento.
No caso de transações com Visa Checkout, este serviço também retornará dados do cartão e do usuário retornados pelo Visa.
Fluxo#
Descrição do fluxo:
- O lojista cria uma transação no Carat passando informações como código da loja, número de parcelas e código de pedido e obtém como resposta um NIT (Número Identificador de Transação).
- O lojista envia o NIT obtido na etapa anterior e os dados do cartão a ser consultado. Com isso, o Carat retorna dados sobre as capacidades do cartão enviado.
- A loja virtual prossegue então consumindo o serviço de efetivação do pagamento, passando o NIT e os dados do cartão do comprador. Em caso de sucesso, a transação de pagamento mudará seu status para CON (confirmada).
Detalhes da chamada#
Recursos: /v1/preauthorizations/{nit}/cards
Método HTTP: POST
Obs.: apesar de se tratar de uma consulta, o método POST foi escolhido por questões de segurança.
Formato da requisição: JSON
Formato da resposta: JSON
Parâmetros de cabeçalho:
| Nome do Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| merchant_id | Código da loja no Carat. Os códigos de produção e certificação serão diferentes. | AN | ≤ 15 | SIM |
| merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | AN | ≤ 80 | SIM |
| Content-Type | Deve ser enviado com o valor “application/json”. | AN | = 15 | SIM |
Exemplo de Consulta de cartão com envio de autorizadora#
Requisição:
Resposta:
Exemplo de Consulta de cartão sem envio de autorizadora#
Requisição:
Resposta:
Exemplo de Consulta de cartão Visa Checkout#
Requisição:
Resposta:
Exemplo de Consulta de cartão com dados adicionais para roteamento iCards via SiTef
Requisição:
Resposta:
Parâmetros de requisição
Na tabela abaixo está a descrição dos parâmetros de requisição do serviço de consulta de cartão:
| Nome do Parâmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
| authorizer_id | Código da autorizadora no Carat, conforme listado no documento “Anexo A – Autorizadoras Carat”. Este campo só é obrigatório caso o campo “wallet_transaction_id” seja enviado. | N | ≤ 3 | NÃO |
| number | Número do cartão do comprador (PAN). | N | ≤ 19 | NÃO |
| 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. | AN | = 88 | NÃO |
| wallet_transaction_id | ID de uma transação de carteiras digitais. Por enquanto, essa funcionalidade está disponível apenas para a autorizadora Visa Checkout (authorizer_id:406). 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. | AN | ≤ 25 | NÃO |
Obs: Apesar de não obrigatório, recomenda-se o envio do authorizer_id para a consulta de cartão, principalmente para roteamentos via SiTef, a fim de comportamentos mais efetivos em relação ao roteamento cadastrado para a autorizadora.
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 consulta de cartão:
| Nome do Parâmetro | Descrição | Tipo | Tamanho |
|---|---|---|---|
| code | Código de resposta do Carat. Qualquer código diferente de ‘0’ significa falha. Para maiores informações, consulte o documento “Anexo A-2 – Codigos de Resposta”. | N | ≤ 4 |
| message | Mensagem de resposta do Carat. | AN | ≤ 500 |
| status | Status da transação de pré-autorização no Carat. Para mais informações, consulte o item 11.1. | AN | = 3 |
| authorizer_code | Código de resposta do autorizador. | AN | ≤ 10 |
| authorizer_message | Mensagem de resposta do autorizador. | AN | ≤ 500 |
| acquirer_name | Nome do roteamento. Ex.: Cielo | AN | ≤ 256 |
| authorizer_id | Código da autorizadora (utilizar este ID ao realizar o pagamento). | N | ≤ 3 |
| is_customer_id_required | Indica a obrigatoriedade da coleta do documento do cliente. | T/F | ≤ 5 |
| is_expiry_date_required | Indica a obrigatoriedade da coleta da data de validade do cartão do comprador. | T/F | ≤ 5 |
| is_installment_funding_enabled | Indica se o parcelamento está habilitado. | T/F | ≤ 5 |
| is_security_code_required | Indica a obrigatoriedade da coleta do código de segurança. | T/F | ≤ 5 |
| is_spot_sale_enabled | Indica se o pagamento à vista está habilitado. | T/F | ≤ 5 |
| is_with_interest_sale_enabled | Indica se o pagamento com juros está habilitado. | T/F | ≤ 5 |
| is_without_interest_sale_enabled | Indica se o pagamento sem juros está habilitado. | T/F | ≤ 5 |
| max_installments_with_interest | Parcelamento máximo com juros. | N | ≤ 2 |
| min_installments_with_interest | Parcelamento mínimo com juros. | N | ≤ 2 |
| visa_checkout_data | Objeto com os dados retornados pela Visa Checkout. | ||
| financing_plan_list | Objeto que consiste em um array de planos de financiamento apresentados em roteamento Via Certa Financiadora. Um plano de financiamento consiste dos seguintes campos: - cod_plano: código de identificação do plano de financiamento, que deve ser enviado no momento da efetivação do pagamento; - tipo_plano: código do tipo do plano de financiamento;- desc_plano: descrição do plano, que pode ser apresentado ao comprador; - parc_plano: número máximo de parcelas possíveis para o plano. | ||
| is_customer_postal_code_required | Indica a obrigatoriedade da coleta do código postal do usuário (CEP no Brasil). | T/F | < 5 |
| Key | Nome do prefixo. | AN | ≤ 1024 |
| value | Valor do prefixo | AN | ≤ 1024 |
Cancelamento de pré-autorização e captura#
Se a transação de pré-autorização foi realizada com sucesso e a Loja Virtual não queira realizar a captura, poderá cancelar a pré-autorização, liberando o valor reservado do limite do cartão ao cliente. Caso a captura não ocorra, após um determinado período de tempo a pré-autorização é desfeita automaticamente, porém o cliente pode desejar que a pré-autorização seja cancelada antes, de forma a liberar o valor do seu limite do cartão.
É importante saber que apenas uma transação de pré-autorização não capturada pode ser cancelada em dias posteriores. Uma transação de captura só pode ser cancelada no mesmo dia em que foi feita.
Para realizar o cancelamento da pré-autorização ou da captura de pré-autorização o fluxo é ligeiramente diferente, no sentido que a criação da transação de cancelamento devolve o nit na URL de Autenticidade, ou seja, a chamada aa operação beginCancelTransaction retornará simplesmente um “OK” e o nit será devolvido na URL de Autenticidade previamente cadastrada.
Note que o Carat somente irá enviar a mensagem “OK” caso o envio do NIT tenha sido bem-sucedido, com o servidor da loja respondendo “HTTP 200 OK” e só depois do retorno do “HTTP 200 OK” que o nit da transação de cancelamento poderá ser utilizado.
Informações para o desenvolvimento da transação de cancelamento inclusive com hash, consulte o manual Interface Web Service REST de Pagamento, Agendamento e Cancelamento. Caso ainda não tenha recebido o documento, solicitar ao e-mail autorizadores5317@softwareexpress.com.br ou pelo tel. (11)3170-5317.
Operação getStatus – consulta de transações#
Em caso de falha na comunicação ou demora excessiva na resposta (timeout) em qualquer uma das operações subsequentes ao beginTransaction, a loja obrigatoriamente deverá consumir a operação getStatus. Esta operação permite que se verifique o status de uma requisição a qual o lojista não obteve a resposta, recuperando os parâmetros que não pôde receber no fluxo normal.
A loja deverá recuperar o status da transação (com o prazo máximo para a consulta de 15 dias) desde que possua o nit, através do webservice getStatus, passando como parâmetro a chave de autenticação da loja (merchantKey) e o nit.
Desenvolvimento/Certificação: caso não tenha recebido o merchantKey para desenvolvimento/certificação, favor solicitar através do e-mail autorizadores5317@softwareexpress.com.br ou pelo telefone (11) 3170-5317.
Produção: o merchantKey para Produção será enviado pela equipe do Carat de Produção, caso não tenha recebido depois dos devidos procedimentos para a entrada em Produção, favor solicitar ao e-mail esitef.prod6773@softwareexpress.com.br.
Note que em casos excepcionais a chave de autenticação (merchantKey) pode ser alterada por questões de segurança, porém a equipe de produção irá entrar em contato com a loja antes da alteração.
Lembrando que diversos fatores podem ocasionar a demora na resposta, incluindo instabilidade de internet e o host da rede autorizadora do cartão. Recomendamos que o servidor da loja tenha configurado o timeout igual ou superior a 90 segundos.
Nota: Este serviço só irá devolver os dados se a transação tiver sido efetuada via Web Services, não irá funcionar em caso de transações via Interface HTML.
Atenção: A consulta de transação no Carat NÃO efetua uma consulta do status da transação no adquirente / autorizador. Este serviço retorna o status da transação na base de dados do Carat.
Exemplo: Caso uma transação de pré-autorização seja confirmada no Carat, mas seja estornada via telefone diretamente no adquirente / autorizador, este estorno não será necessariamente refletido no serviço de consulta de transação do Carat.
Detalhes da chamada#
Recurso: /v1/transactions/{nit}
Método HTTP: GET
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 | ||
| merchant_key | Chave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes. | ≤ 80 A | Sim |
| nit | Identificador da transação no Carat. Obtido no retorno da chamada ao beginTransaction. | = 64 A | Sim |
Parâmetros da requisição da operação getStatus
Na URL do recurso deve ser enviado o nit
| Nome do Parâmetro | Descrição | Tamanho | Obrigatório |
|---|---|---|---|
| nit | Identificador da transação no Carat. Obtido no retorno da chamada ao beginTransaction. | = 64 A | Sim |
A chamada da operação de consulta de transações – getStatus – não necessita de corpo de requisição.
Parâmetros da resposta da operação getStatus
| Nome do Parâmetro | Descrição | Tamanho |
|---|---|---|
| code | Código de resposta do Carat. Qualquer código diferente de "0" significa falha na consulta. Para maiores informações, consulte o documento Anexo A-2 - Codigos de Resposta. | < 4 N |
| message | Mensagem de resposta do Carat da consulta. | < 500 AN |
| acquirer_id | Código do adquirente/roteamento utilizado na transação. | < 4 N |
| acquirer_name | Nome do adquirente/roteamento utilizado na transação. | < 100 AN |
| amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 AN |
| authorization_number | Número de autorização. | < 6 AN |
| authorizer_code | Código de resposta do autorizador. | < 10 AN |
| authorizer_date | Data de efetivação da pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. | |
| Exemplo: 13/07/2017T16:03 | = 16 D | |
| authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
| authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
| authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
| customer_receipt | Cupom (via cliente). | < 4000 AN |
| eci | Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce). | < 3 AN |
| esitef_usn | Número sequencial único da transação de pré-autorização no Carat. | = 15 N |
| host_usn | NSU da autorizadora. | < 15 AN |
| issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
| merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
| merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 AN |
| nit | Identificador da transação de pré-autorização no Carat. | = 64 AN |
| order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
| payment_type | Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service | = 1 A |
| sitef_usn | Número sequencial único da transação de pré-autorização no SiTef. | = 6 N |
| status | Status da transação de pré-autorização no Carat. | = 3 AN |
| tid | ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 AN |
| xid | Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos. | < 40 AN |
| acquirer_id | Código do adquirente/roteamento utilizado na transação. | < 4 N |
| acquirer_name | Nome do adquirente/roteamento utilizado na transação. | < 100 AN |
| amount | Valor da compra especificado pela loja (em centavos) na criação da transação. | < 12 AN |
| authorization_number | Número de autorização. | < 6 AN |
| authorizer_code | Código de resposta do autorizador. | < 10 AN |
| authorizer_date | Data de efetivação do pré-autorização retornada pelo autorizador no formato DD/MM/AAAA’T’HH:mm. Exemplo: 13/07/2017T16:03 | = 16 D |
| authorizer_id | Código da autorizadora utilizada na transação. | < 4 N |
| authorizer_merchant_id | Código de afiliação do lojista na autorizadora. | < 100 AN |
| authorizer_message | Mensagem de resposta do autorizador. | < 500 AN |
| customer_receipt | Cupom (via cliente). | < 4000 AN |
| eci | Eletronic Commerce Indicator (indicador do nível de segurança da transação do pré-autorização via Cielo e-Commerce). | < 3 AN |
| esitef_usn | Número sequencial único da transação de pré-autorização no Carat. | = 15 N |
| host_usn | NSU da autorizadora. | < 15 AN |
| issuer | Código da bandeira retornado pelo autorizador. | < 5 AN |
| merchant_receipt | Cupom (via estabelecimento). | < 4000 AN |
| merchant_usn | Número sequencial único enviado pela loja na criação da transação. | < 12 AN |
| nit | Identificador da transação de pré-autorização no Carat. | = 64 AN |
| order_id | Código de pedido enviado pela loja na criação da transação. | < 40 AN |
| payment_type | Tipo do pagamento da autorizadora escolhida: B = boleto, C = crédito, D = débito, P = cartão crédito Private Label puro, T = tranferência bancária, G = cartão gift, O = outros meios de pagamentos, W = Boleto NR via Web Service | = 1 A |
| sitef_usn | Número sequencial único da transação de pré-autorização no SiTef. | = 6 N |
| status | Status da transação de pré-autorização no Carat. | = 3 AN |
| tid | ID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef. | < 40 AN |
| xid | Campo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos. | < 40 AN |
Atenção: Os campos code e message se referem ao código e mensagem referentes à requisição de consulta. Estes não se referem às transações consultadas.
Exemplo de requisição
Exemplo de requisição
Tabelas compartilhadas#
Status de transações do Carat#
| Código | Nome | Descrição |
|---|---|---|
| NOV | Nova | Transação recém-criada. |
| INV | Inválida | Transação não foi criada com sucesso, provavelmente a loja enviou algum parâmetro incorreto, e não foi possível inicializar a transação corretamente. |
| PPC | Pendente de confirmação | Pagamento pendente de confirmação. |
| PPN | Desfeita | Pagamento pendente não confirmado (cancelado). |
| PEN | Aguardando pagamento | Transação aguardando resposta da instituição financeira. |
| CON | Efetuada | Transação confirmada pela instituição financeira. |
| NEG | Negada | Transação negada pela instituição financeira. |
| ERR | Erro ao efetuar pagamento | Erro na comunicação com a autorizadora. Tente novamente. |
| BLQ | Bloqueada | Transação bloqueada após múltiplas tentativas de consulta de cartão. |
| EXP | Expirada | A transação expirou devido ao prazo de validade do NIT. |
| EST | Estornada | Pagamento estornado. |