Card query service
This section explains in payment context. Look for Flow for further details.
It’s possible to use the NIT of a payment with status NOV (new) to query the card’s BIN (first six digits) on SiTef to obtain data about its capabilities (possibility of payment with installments, maximum number of installments, requirement of the security code, etc.), or knowing which authorizer of the merchant is the most suited for the payment.
In the case of transactions with Visa Checkout, this service also returns card and customer data returned by Visa.
Flow#
Flow description:
- The merchant creates a transaction on Carat Portal passing information such as the merchant ID, number of installments and the order ID and obtains as response a NIT (Transaction Identifier Number).
- The merchant sends the NIT obtained in the previous step and the data of the card to be queried. Then, Carat Portal returns data about the capabilities of the card.
- The merchants then proceeds consuming the payment effectuation service, passing the NIT and the customer’s card data. In case of success, the payment transaction will change its status to
CON(confirmed).
Call details#
- Resource:
/v1/payments/{nit}/cards - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Obs.: although it’s a query, the POST method was chosen for security reasons.
Examples#
Below are some examples of the card query service call using the cURL tool.
Card query with authorizer#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Card query without authorizer#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Visa Checkout card query#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Card Query with financing plans#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Card query with additional data for iCards via SITef routing#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Card query with additional data for IPG routing#
Requisição:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Response codes
See reference on API codes - response codes
Request parameters#
The table below describes the request parameters of the card query service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
authorizer_id | Code of the authorizer on Carat Portal. Learn more. This field is only mandatory when the wallet_transaction_id field is sent. If this parameter is absent, Carat Portal assumes it's a credit card. | < 3 N | COND. |
| card | |||
number | Customer card number (PAN). | < 19 N | YES |
token | HASH of a card stored on Carat Portal. It’s not allowed to send an ‘open’ card number (number field) and a stored card (token field) on the same request. | = 88 AN | NO |
wallet_transaction_id | Digital wallet transaction ID. Currently, this functionality is only available to the Visa Checkout authorizer. It isn’t allowed to send an "open" card number ( number field), a stored card (token field) and a wallet_transaction_id on the same request. | < 25 AN | NO |
do_par_inquiry | Informs if the VISA PAR Inquiry request will be performed. The response value will be returned on the response par field. Allowed values: true - PAR request will be sent. false - PAR request will not be sent.Default value: false | < 5 A | NO |
Response parameters#
If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes de response parameters of the card query service:
| Parameter | Description | Format |
|---|---|---|
code | Carat Portal response code. Any code different from 0 means failure. Learn more. | < 4 N |
message | Carat Portal response message. | < 500 AN |
| payment | ||
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
| card | ||
authorizer_code | Authorizer response code. | < 10 AN |
authorizer_message | Authorizer response message. | < 500 AN |
acquirer_name | Routing name, e.g.: Cielo | < 256 AN |
authorizer_id | Code of the authorizer (use this ID when making the payment). | < 3 N |
is_customer_id_required | Indicates the requirement of collecting the customer ID. | < 5 T/F |
is_expiry_date_required | Indicates the requirement of collecting the card expiry date. | < 5 T/F |
is_installment_funding_enabled | Indicates if installment funding is enabled. | < 5 T/F |
is_security_code_required | Indicates the requirement of collecting the security code. | < 5 T/F |
is_spot_sale_enabled | Indicates if spot sale is enabled. | < 5 T/F |
is_with_interest_sale_enabled | Indicates if installments with interest are enabled. | < 5 T/F |
is_without_interest_sale_enabled | Indicates if installments without interest are enabled. | < 5 T/F |
max_installments_with_interest | Maximum number of installments with interest. | < 2 N |
min_installments_with_interest | Minimum number of installments with interest. | < 2 N |
visa_checkout_data | Object with the data returned by Visa Checkout. | O |
financing_plan_list | Financing plans list object, returned when the card is configured to be routed by Via Certa Financiadora. A financing plan is made by fields below:cod_plano: financing plan identifier code. It must be sent in payment effectuation service;tipo_plano: financing plan type code;desc_plano: financing plan description text. It can be shown to the customer;parc_plano: maximum amount of installments in financing plan. | O |
is_customer_postal_code_required | Indicates the requirement of hte user’s postal code (CEP in Brazil) | < 5 T/F |
par | PAR value returned by VISA of the field do_par_inquiry was sent with the value true on the request. | < 32 AN |
| card.prefixes[] This field contains the prefixes (additional data) returned by SiTef. | ||
| key | Prefix name. | < 1024 AN |
| value | Prefix value. | < 1024 AN |
| details[] This field contains details returned by IPG routing | ||
| brand | The card brand. | < 1024 AN |
| brand_product_id | The product ID of the brand. | < 1024 AN |
| card_function | Card function. | CREDIT, DEBIT, PREPAID, VOUCHER, UNDEFINED |
| commercialCard | Indicates whether it is a corporate or non-corporate card. | CORPORATE, NON_CORPORATE |
| issuer_country | The country of the issuer. | < 1024 AN |
| issuer_name | The name of the issuer. | < 1024 AN |