Serviço de 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 de efetivação de pré-autorização e se o resultado for aprovado, o serviço de captura 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 de captura, 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.

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â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

Exemplo#

Requisição:

Para usar este exemplo, não esquecer de definir a variável {{url}} com o valor
esitef-homologacao.softwareexpress.com.br

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

Resposta:

{
"code": "0",
"message": "OK. Transaction successful.",
"capture": {
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "orderID",
"customer_receipt": "=== CUSTOMER RECEIPT ===",
"merchant_receipt": "=== MERCHANT RECEIPT ===",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_code": "000",
"authorizer_message": "Transacao OK.",
"authorizer_date": "20/02/2023T19:40",
"authorizer_merchant_id": "000000000000000",
"authorization_number": "212195",
"esitef_usn": "180921015287704",
"merchant_usn": "20190101",
"sitef_usn": "212195",
"host_usn": "999212195",
"amount": "100",
"payment_type": "C",
"issuer": "2"
},
"card":{
"suffix":"5555",
"bin": "544444"
}
}

Códigos de resposta

Veja a referencia no Códigos da API - códigos de resposta

Parâmetros da requisição#

O envio de dados de cartão é obrigatório para transações com roteamento SiTef com exceção do adquirente Cetelem. Deve ser utilizado apenas um entre os campos: number, token ou wallet_transaction_id
ParâmetroDescriçãoFormatoObrigatório
amountValor total da compra (em centavos).< 12 NSIM
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
installmentsNúmero de parcelas. 1 = à vista.

O número máximo de parcelas configurado no portal Carat do lojista não será verificado neste campo, servindo somente para pagamentos HTML.
< 2 NSIM
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 NSIM
promo_codeCó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.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
card
numberNúmero do cartão do comprador (PAN).< 19 NCOND.
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.
expiry_dateData de vencimento do cartão no formato MMAA.= 4 NCOND.
security_codeCódigo de segurança.< 5 NCOND.
mccO MCC (Merchant Category Code) é um código que classifica um negócio pelo tipo de bens ou produtos fornecidos.< 4 NNÃO
subacquirer_merchant_idIdentificação da loja na subadquirente.< 22 ANNÃO
ecomm_pos_refEste campo enviará uma identificação que constará no campo PDV do relatório do SiTef Web para transações e-commerce.< 8 AFNÃO

Parâmetros de resposta#

ParâmetroDescriçãoFormato
codeCó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
messageMensagem de resposta do Carat.< 500 AN
capture
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 (indicador do nível de segurança da transação do pré-autorização).< 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
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 pagamentos, W = Boleto NR via Web Service= 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
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
card
suffixÚltimos 4 dígitos do cartão do comprador.= 4 AN
bin6 primeiros dígitos do cartão do comprador.= 6 AN