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âmetroDescriçãoFormatoObrigatório
Content-TypeValor fixo application/json= 15 ANSIM
merchant_idCódigo da loja no Carat. Os códigos de produção e certificação serão diferentes< 15 ANSIM
merchant_keyChave de autenticação da loja no Carat. As chaves de produção e certificação serão diferentes.< 80 ANSIM

Exemplos:#

Pré-Autorização#

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
sandbox.ecomm-bin.fiserv.com.br

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"authorizer_id":"2",
"installments":"2",
"installment_type":"4",
"card": {
"number":"xxxxxxxxxxxxxxxx",
"expiry_date":"1222",
"security_code":"123"
}
}
--verbose

Resposta:

{
"code":"0",
"message":"OK. Transaction successful.",
"pre_authorization":{
"authorizer_code":"000",
"authorizer_message":"Transacao OK.",
"status":"CON",
"nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"customer_receipt":"=== CUSTOMER RECEIPT ===",
"merchant_receipt":"=== MERCHANT RECEIPT ===",
"authorizer_id":"2",
"authorizer_date":"09/11/2018T19:40",
"acquirer_id":"229",
"acquirer_name":"Bin",
"authorization_number":"013245",
"merchant_usn":"20190101",
"esitef_usn":"181109017689784",
"order_id":"orderID",
"sitef_usn":"212194",
"host_usn":"999212194",
"amount":"100",
"issuer":"2",
"payment_type":"C",
"authorizer_merchant_id":"000000000000000"
}
}

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
sandbox.ecomm-bin.fiserv.com.br

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/8621c93b58e507d3fe0bda407f5cb0b1fe3971df591fd2652cc9f737134502d3"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"card": {
"expiry_date": "1023",
"number": "xxxxxxxxxxxxxxxx",
"security_code": "123",
"cryptogram":"ALRzlt6NKQtPAAZAkOuIAAADFA=="
}
}'

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"pre_authorization": {
"authorizer_code": "000",
"authorizer_message": "Transacao Aprov.",
"status": "CON",
"nit": "8621c93b58e507d3fe0bda407f5cb0b1fe3971df591fd2652cc9f737134502d3",
"order_id": "1670945065929",
"customer_receipt":"=== CUSTOMER RECEIPT ===",
"merchant_receipt":"=== MERCHANT RECEIPT ===",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_date": "13/12/2022T12:24",
"authorization_number": "136231",
"merchant_usn": "16114726760",
"esitef_usn": "221213115168264",
"sitef_usn": "136231",
"host_usn": "999136231 ",
"amount": "25255",
"payment_type": "C",
"issuer": "1",
"authorizer_merchant_id": "000000000000005",
"terminal_id": "ES000038"
}
}

Parâmetros de requisição#

ParâmetroDescriçãoFormatoObrigatório
authorizer_idCódigo da autorizadora no Carat. Ver documento Autorizadoras.< 3 NSIM
customer_idDocumento de identidade do comprador. Use apenas caracteres alfanuméricos (sem pontos, traços ou outros caracteres especiais).< 20 ANNÃO
discountValor 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 NNÃO
installmentsJuntamente com o campo installment_type, indica parcelamento*, Envie 1 para transações à vista.< 2 NCOND.
installment_typeJuntamente 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 NCOND.
mccMerchant Category Code - Indica o código de categoria da loja. É possível enviá-lo na subadquirência via SiTef.< 4 N NÃO
merchant_emaile-mail da Loja. Este parâmetro quando enviado sobrescreve o e-mail do cadastro da Loja.< 40 ANNÃO
nitIdentificador da transação no Carat (criptografado). Obtido no retorno da chamada ao beginTransaction.= 64 ANSIM
promo_codeCó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.ANNÃO
soft_descriptorTexto adicional que será apresentado junto ao nome do estabelecimento na fatura do cartão de crédito do comprador. Saiba mais< 22 ANNÃO
subtotalValor 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 NNÃO
subacquirer_merchant_idIdentificação da loja na subadquirente.< 22 NNÃO
cardDeve ser utilizado apenas um entre os campos: number, token ou wallet_transaction_id
numberNúmero do cartão do comprador (PAN).

Token gerado pela bandeira (DPAN) para pré-autorização com Token Bandeira. Saiba mais
< 19 NSIM
cryptogramCriptograma gerado pela bandeira.= 28 ASim para pagamentos com token bandeira
wallet_typeCampo 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”.ANNÃO
tokenUtilizado para casos de pré-autorização recorrente, onde o cartão já deverá estar armazenado na base de dados do Carat.= 88 ANCOND.
wallet_transaction_idCódigo de identificação de transação com wallet VisaCheckout. Necessário apenas para Visa Checkout< 25 ANCOND.
initial_wallet_transaction_idInforma 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 ANCOND.
holderNome do portador do cartão. .< 30 ANCOND.
expiry_dateData de vencimento do cartão no formato MMAA.= 4 NCOND.
security_codeCódigo de segurança.< 5 NCOND.
wallet_typeCampo 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”.ANNÃO
external_authenticationEste elemento recebe campos de autenticação MPI.
versionVersão do 3DS utilizado no processo de autenticação (atualmente só está sendo aceito versão 2).< 1 ANNÃO
eciEletronic Commerce Indicator – indica o nível de segurança da transação com autenticação do dono do cartão< 3 NNÃO
reference_idIdentificador da transação de autenticação do dono do cartão, feita em serviço externo ao Carat< 40 NNÃO
cavvCardholder Authentication Verification Value - Código que indica o resultado da autenticação do dono do cartão.< 40 NNÃO
acquirerDados específicos necessários dependendo da adquirente/roteamento.
terminalTerminal SiTef que se deseja usar. Se não for enviado, o Carat gerará um terminal aleatório.= 14 NNÃO
company_codeCó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 NNÃO

ATENÇÃO: Os parâmetros terminal e company_code deverã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âmetroDescriçãoFormato
codeCó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
messageMensagem de resposta do Carat.< 500 AN
pre_authorization
acquirer_idCódigo do adquirente/roteamento utilizado na transação.< 4 N
acquirer_nameNome do adquirente/roteamento utilizado na transação.< 100 AN
amountValor da compra especificado pela loja (em centavos) na criação da transação.< 12 AN
authorization_numberNúmero de autorização.< 6 AN
authorizer_codeCódigo de resposta do autorizador.< 10 AN
authorizer_dateData 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_idCódigo da autorizadora utilizada na transação.< 4 N
authorizer_merchant_idCódigo de afiliação do lojista na autorizadora.< 100 AN
authorizer_messageMensagem de resposta do autorizador.< 500 AN
customer_receiptCupom (via cliente).< 4000 AN
eciEletronic Commerce Indicator.< 3 AN
esitef_usnNúmero sequencial único da transação de pré-autorização no Carat.= 15 N
host_usnNSU da autorizadora.< 15 AN
issuerCódigo da bandeira retornado pelo autorizador.< 5 AN
merchant_receiptCupom (via estabelecimento).< 4000 AN
merchant_usnNúmero sequencial único enviado pela loja na criação da transação.< 12 AN
nitIdentificador da transação de pré-autorização no Carat.= 64 AN
order_idCódigo de pedido enviado pela loja na criação da transação.< 40 AN
payment_typeTipo 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_usnNúmero sequencial único da transação de pré-autorização no SiTef.= 6 N
statusStatus da transação de pré-autorização no Carat.= 3 AN
terminal_idCódigo do terminal utilizada na transação< 8 AN
tidID da transação no adquirente/roteamento. Este campo só é retornado em transações com adquirentes externos ao SiTef.< 40 AN
xidCampo XID retornado em autenticações 3DS ou certos adquirentes/roteamentos.< 40 AN
retryable_codeIndicador 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