Serviço de consulta de cartão (pré-autorização)

Esta seção explica sob o contexto de pré-autorização. Veja mais detalhes no fluxo.

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:

1. 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).
2. 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.
3. 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:

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/1234567890abcdefghijklmnopqrstuvwxyz123456

7890abcdefghijklmnopqr /cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"number":"5555555555555555"

},

"authorizer_id":"1"

}

--verbose

Resposta:

{

"code": "0",

"message": "OK. Transaction successful.",

"preauthorization": {

"status": "NOV"

},

"card": {

"acquirer_name": "Bin",

"authorizer_id": "1",

"authorizer_response_code": "000",

"is_customer_id_required": "false",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"TRAT": "2",

"PERIFERICO": "1",

"CSEG": "2"

}

}

}

Exemplo de Consulta de cartão sem envio de autorizadora

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/1234567890abcdefghijklmnopqrstuvwxyz123456

7890abcdefghijklmnopqr/cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"number":"6543210987654321"

}

}

--verbose

Resposta:

{

"code": "0",

"message": "OK. Transaction successful.",

"preauthorization": {

"status": "NOV"

},

"card": {

"acquirer_name": "Bin",

"authorizer_id": "1",

"authorizer_response_code": "000",

"is_customer_id_required": "false",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"TRAT": "2",

"PERIFERICO": "1",

"CSEG": "2"

}

}

}

Exemplo de Consulta de cartão Visa Checkout

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/1234567890abcdefghijklmnopqrstuvwxyz123

4567890abcdefghijklmnopqr/cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"wallet_transaction_id":"4444444444444444444"

},

"authorizer_id":"406"

}

--verbose

Resposta:

{

"code": "0",

"message": "OK. Transaction successful.",

"preauthorization": {

"status": "NOV"

},

"card": {

"acquirer_name": "Bin",

"authorizer_id": "406",

"authorizer_response_code": "000",

"is_customer_id_required": "false",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"TRAT": "2",

"PERIFERICO": "1"

},

"visa_checkout_data": {

"payment_request": {

"currency_code": "BRL",

"subtotal": "115.5",

"total": "115.5",

"order_id": "09387",

"source_id": "LOJAVISACHECK"

},

"user_data": {

"user_first_name": "Comprador",

"user_last_name": "Esitef",

"user_full_name": "Comprador Esitef",

"user_name": "esitef2@gmail.com",

"user_email": "esitef2@gmail.com",

"enc_user_id": "c5DmPXTXC3VwZywsFESEGAqiLM5PXSZG7hgyQgRv0j8=",

"user_personal_id": "12345678909"

},

"creation_time_stamp": 1502206049403,

"payment_instrument": {

"id": "AWUU0/rQrmKCMx+C740kBefZP2GNsdAMYUTXAzCPk+M=",

"last_four_digits": "1010",

"bin_six_digits": "406897",

"verification_status": "VERIFIED",

"issuer_bid": "10029901",

"nick_name": "Cartão PAN",

"name_on_card": "aaaaaaaaaa vvvvvvvvvv",

"card_first_name": "aaaaaaaaaa",

"card_last_name": "vvvvvvvvvv",

"payment_type": {

"card_brand": "VISA",

"card_type": "CREDIT"

},

"billing_address": {

"person_name": "aaaaaaaaaa vvvvvvvvvv",

"first_name": "aaaaaaaaaa",

"last_name": "vvvvvvvvvv",

"line1": "qqqqqqqqqq",

"line2": "eeeeee",

"line3": "wwwwwwwww",

"city": "cccccccc",

"state_province_code": "SP",

"postal_code": "01238010",

"country_code": "BR",

"phone": "987654321",

"default": "false"

},

"card_arts": {

"card_art": [

{

"base_image_file_name": "https://sandbox.secure.checkout.visa.com/VmeCardArts/lg_visa_card.png",

"height": 105,

"width": 164

}

]

},

"expiration_date": {

"month": "11",

"year": "2022"

}

},

"risk_data": {

"advice": "UNAVAILABLE",

"score": 0,

"avs_response_code": "0",

"cvv_response_code": "0",

"age_of_account": "704"

},

"visa_checkout_guest": "false"

}

}

}

Exemplo de Consulta de cartão com dados adicionais para roteamento iCards via SiTef

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/1234567890abcdefghijklmnopqrstuvwxyz123456

7890abcdefghijklmnopqr/cards"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-binary

{

"card":{

"number":"6543210987654321"

},

"authorizer_id":"38"

}

--verbose

Resposta:

{

"code": "0",

"message": "OK. Transaction successful.",

"card": {

"acquirer_name": "iCards",

"authorizer_id": "38",

"authorizer_response_code": "000",

"is_customer_id_required": "true",

"is_expiry_date_required": "true",

"is_installment_funding_enabled": "true",

"is_security_code_required": "true",

"is_spot_sale_enabled": "true",

"is_with_interest_sale_enabled": "true",

"is_without_interest_sale_enabled": "true",

"max_installments_with_interest": "12",

"min_installments_with_interest": "01",

"prefixes": {

"NPSAQ": "0299",

"CAPTPPRE": "1",

"XCAPPREAUT": "11"

},

"is_customer_postal_code_required": "true",

"is_card_holder_required": "true"

},

"preauthorization": {

"status": "NOV"

}

}

Códigos de resposta

Veja a referencia no Códigos da API - códigos de 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 na lista de autorizadoras. 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.	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.	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