Pré-Autorização com Idempotência
Interface de pré-autorização que permite a loja realizar requisições de pré-autorização em uma única chamada utilizando idempotência. Clique aqui para mais informações sobre a captura de pré-autorização.
Detalhes da chamada#
- Recurso:
/v2/preauthorizations/ - 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 |
|---|---|---|---|
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 |
Content-Type | Deve ser enviado com o valor application/json. | = 15 AN | SIM |
idempotency_key | É como um código aleatório (identificador), com até 80 caracteres, criado pelo integrador que vai usar a API do Carat. | < 80 N | SIM |
Exemplos#
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 utilizando o mesmo idempotency_key com order_id diferente#
Quando uma dada requisição é enviada com o mesmo idempotency key, porém com o payload diferente.
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 |
|---|---|---|---|
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. Para as transações roteadas pela adquirente Bin, existe uma limitação de 20 caracteres. | < 40 AN | SIM |
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 já cadastrado na plataforma Carat Pagamento Online. | < 40 AN | NÃO |
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. | < 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. |
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 |
mid | Código do estabelecimento da adquirente - Para roteamentos BIN, o MID a ser utilizado pelo estabelecimento é único. Este campo deve ser utilizado caso seja necessário selecionar um MID diferente do padrão. | < 15 AN | COND |
additional_data | Elemento para envio de dados adicionais. | ||
ecomm_pos_ref | Este campo enviará uma identificação que constará no campo PDV do relatório do SiTef Web para transações e-commerce. | < 8 AF | NÃO |
* Parcelamento roteado 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 aceitas sem juros, isto é, com o parâmetro installment_type = 4. Parcelamentos com juros não são aceitos para este roteamento.
ATENÇÃO:
Além dos parâmetros de retorno dos serviços descritos nesta especificação o Carat poderá devolver outros parâmetros sem aviso prévio.
É importante que o aplicativo esteja preparado para receber os parâmetros desconhecidos além dos parâmetros já especificados e simplesmente desprezá-los.
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 (indicador do nível de segurança da transação da pré-autorização). | < 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 |