Card query Service (pre-authorization)

This section explains in pre-authorization context. Look for Flow for further details

From a pre-authorization NIT with status NOV (new), you can perform a card BIN query (first six digits) in SiTef to obtain data on your capacities (possibility of payment in installments, maximum installments, security code requirement, etc.), or knowing which store authorizer is best suited for that payment.

In case of Visa Checkout transactions, this service will also return card and user data returned by VISA.

Flow#

Flow description:

  1. Merchant creates a transaction on Carat Portal passing some information, as merchant ID, installments quantity and order code e gets as response a nit (Transaction Identifier Number).
  2. Merchant sends the nit obtained previously and card data to be queried. Thus, Carat Portal returns data related to the card sent.
  3. Virtual Store then proceeds consuming the payment effectuation service, passing nit and the buyers card data. On success, the payment transaction will change its status to CON (confirmed).

Call details#

  • Resources: /v1/preauthorizations/{nit}/cards
  • HTTP Method: POST

Obs.: despite being a query, the POST method was chosen due to security matters.

  • Request format: JSON
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
Content-TypeFixed value "application/json"= 15 AYes
merchant_idCarat Portal store's ID. Production and certification IDs are different.
merchant_keyStore authentication key in Carat Portal. Production and certification keys are different.≤ 80 AYes
nitPre-authorization transaction ID in Carat Portal. Obtained at beginTransaction response.= 64 AYes

Card query example with authorizer's parameter#

Request:

To use this example, don't forget to define the variable {{url}} to the value
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

Response:

{
"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"
}
}
}

Card query example without authorizer's parameter#

Request:

To use this example, don't forget to define the variable {{url}} to the value
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

Response:

{
"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"
}
}
}

Visa Checkout card query example#

Request:

To use this example, don't forget to define the variable {{url}} to the value
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

Response:

{
"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"
}
}
}

Card query example with additional data for iCards routing via SiTef#

Request:

To use this example, don't forget to define the variable {{url}} to the value
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

Response:

{
"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"
}
}

Response codes

See reference on API codes - response codes

Request parameters#

In the table below there is a description of the card query service request parameters:

ParameterDescriptionFormatSizeMandatory
authorizer_idAuthorizer ID used in transaction, as listed in the Authorizer's list. Mandatory only when "wallet_transaction_id" is sent.N≤ 3NO
numberBuyer's card number PAN).N≤ 19NO
tokenHash of stored card at Carat Portal. It's not allowed to send the fields number and tokenon the same request.AN= 88NO
wallet_transaction_idDigital wallet transaction ID. For now, this feature is only available for Visa Checkout (authorizer_id:406). It's not allowed to send the fields number, tokenor wallet_transaction_id on the same request.AN≤ 25NO

Note: Although not mandatory, it is recommended to send authorizer_id for card consultation, especially for routing by SiTef, in order to more effective behaviors in relation to the routing registered to the authorizer.

Response parameters#

If successful, the HTTP response code will be 200. Any other code should be interpreted as an error. In the table below there is the description of the card query service response parameters:

ParameterDescriptionFormatSize
codeCarat Portal response code. Anything besides "0" means failure. See more information at the Response Code documentN≤ 4
messageCarat Portal response message.AN≤ 500
statusCarat Portal pre-authorization transaction status.AN= 3
authorizer_codeAuthorizer responde code.AN≤ 10
authorizer_messageAuthorizer's response messageAN≤ 500
acquirer_nameAcquirer's name. Ex.: CieloAN≤ 256
authorizer_idAuthorizer ID use in transaction.N≤ 3
is_customer_id_requiredIndicates wether the gathering of customer's ID is mandatory.T/F≤ 5
is_expiry_date_requiredIndicates wether the gathering of the buyer's card expiration date is mandatory.T/F≤ 5
is_installment_funding_enabledIndicates wether the installment is enabled.T/F≤ 5
is_security_code_requiredIndicates wether the gathering of card's security code is mandatory.T/F≤ 5
is_spot_sale_enabledIndicates if spot sale is enabled.T/F≤ 5
is_with_interest_sale_enabledIndicates if payment with interest is enabled.T/F≤ 5
is_without_interest_sale_enabledIndicates if payment without interest is enabled.T/F≤ 5
max_installments_with_interestMax installments with interest.N≤ 2
min_installments_with_interestMin installments with interest.N≤ 2
visa_checkout_dataReturned data from Visa Checkout.
financing_plan_listObject consisting of an array of financing plans presented in Via Certa Financing routing. A financing plan consists of the following fields:
- cod_plano: financing plan identification code, which must be sent at the time of payment;
- tipo_plano: financing plan type code;
- desc_plano: plan's description which can be presented to the buyer;
- parc_plano: maximum number of possible installments for the plan.
is_customer_postal_code_requiredIndicates the obligation to collect the user's zip code (CEP in Brazil).T/F< 5
keyPrefix name.AN≤ 1024
valuePrefix valueAN≤ 1024