Serviço de efetivação de pré-autorização
Detalhes da Chamada#
O nit obtido no retorno do serviço de criação de pré-autorização deverá ser enviado na operação de efetivação de pré-autorização 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:
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
Content-Type | Valor fixo application/json | = 15 AN | SIM |
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 |
Exemplos:#
Pré-Autorização#
Requisição:
Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br
Resposta:
Pré-Autorização com Token Bandeira#
Algumas bandeiras de cartão possuem uma solução de tokenização que oferece o armazenamento de cartões em cofres na própria bandeira, de forma criptografada. Essa tokenização de bandeira tem o intuito de melhorar a segurança e qualidade das informações de cartão trafegadas, o que acarreta em possíveis aumentos na conversão de aprovação pelos bancos emissores.
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#
| Parâmetro | Descrição | Formato | Obrigatório |
|---|---|---|---|
authorizer_id | Código da autorizadora no Carat. Ver documento Autorizadoras. | < 3 N | SIM |
customer_id | Documento de identidade do comprador. Use apenas caracteres alfanuméricos (sem pontos, traços ou outros caracteres especiais). | < 20 AN | 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. | < 12 N | NÃO |
installments | Juntamente com o campo installment_type, indica parcelamento*, utilizados APENAS com autorizadoras roteadas por e-Rede, GetNetLac via SiTef, Rede via SiTef, Cetelem via SiTef e iCards via SiTef. Envie 1 para transações à vista. | < 2 N | COND. |
installment_type | Juntamente com o campo installments, indica parcelamento*, utilizados APENAS com autorizadoras roteadas por e-Rede, GetNetLac via SiTef, Rede via SiTef, Cetelem 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ão4.: Parcelamento realizado pela loja e sem juros (adotar este valor como padrão/default para transações à vista) | = 1 N | COND. |
mcc | Merchant Category Code - Indica o código de categoria da loja. Necessário ao utilizar subadquirência Stone WS e é possível enviá-lo na subadquirência via SiTef. | < 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 AN | NÃO |
nit | Identificador da transação no Carat (criptografado). Obtido no retorno da chamada ao beginTransaction. | = 64 AN | 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. | AN | 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 | < 22 AN | 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. | < 12 N | NÃO |
subacquirer_merchant_id | Identificação da loja na subadquirente. | < 22 N | NÃO |
card | Deve ser utilizado apenas um entre os campos: number, token ou wallet_transaction_id | ||
number | Número do cartão do comprador (PAN). Token gerado pela bandeira (DPAN) para pré-autorização com Token Bandeira. Saiba mais | < 19 N | SIM |
cryptogram | Criptograma gerado pela bandeira. | = 28 A | Sim para pagamentos com token bandeira |
wallet_type | Campo que especifica se a transação é processada com PAN ou DPAN. Se “tipo” estiver vazio, o valor padrão é PAN (número de cartão não tokenizado). Se houver uma transação tokenizada, deverá enviar o valor “network_token”. | AN | NÃO |
token | Utilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do Carat. | = 88 AN | COND. |
wallet_transaction_id | Código de identificação de transação com wallet VisaCheckout. Necessário apenas para Visa Checkout | < 25 AN | COND. |
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. Necessário apenas para Visa Checkout.Valor padrão: true | < 5 AN | COND. |
holder | Nome do portador do cartão. Obrigatório apenas para roteamentos e-Rede, GetNet WS e VR (SmartNet). | < 30 AN | COND. |
expiry_date | Data de vencimento do cartão no formato MMAA. | = 4 N | COND. |
security_code | Código de segurança. | < 5 N | COND. |
wallet_type | Campo que especifica se a transação é processada com PAN ou DPAN. Se “tipo” estiver vazio, o valor padrão é PAN (número de cartão não tokenizado). Se houver uma transação tokenizada, deverá enviar o valor “network_token”. | AN | NÃO |
external_authentication | Este elemento recebe campos de autenticação MPI. | ||
version | Versão do 3DS utilizado no processo de autenticação (atualmente só está sendo aceito versão 2). | < 1 AN | NÃO |
eci | Eletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão | < 3 N | NÃO |
reference_id | Identificador da transação de autenticação do dono do cartão, feita em serviço externo ao Carat | < 40 N | NÃO |
cavv | Cardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão. | < 40 N | NÃO |
acquirer | Dados específicos necessários dependendo da adquirente/roteamento. | ||
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 |
(\*) **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 com juros não são aceitos para este roteamento.
ATENÇÃO: Os parâmetros
terminalecompany_codedeverão ser usados somente para roteamentos via SiTef e devem 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.
Parâmetros de resposta#
A tabela abaixo contém os parâmetros de resposta do serviço de efetivação de pré-autorização. 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).
| Parâmetro | Descrição | Formato |
|---|---|---|
code | Código de resposta do Carat. Qualquer código diferente de 0 significa falha. Para maiores informações, consulte o documento de Códigos de Resposta. | < 4 N |
message | Mensagem de resposta do Carat. | < 500 AN |
pre_authorization | ||
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. | < 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 pagamento | = 1 AN |
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 |
terminal_id | Código do terminal utilizada na transação | < 8 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 |
retryable_code | Indicador de reversibilidade de uma transação cuja autorização foi negada pela autorizadora. Esse campo será retornado na resposta da requisição de pagamento com cartão e deve ser levado em consideração no mecanismo de retentativa de transação da loja virtual. Códigos válidos:01 – Transação negada reversível, retente mais tarde.02 – Transação negada irreversível, não retente. | = 2 N |