Card Query Service

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:

Merchant creates a transaction on e-SiTef passing some information, as merchant ID, installments quantity and order code e gets as response a nit (Transaction Identifier Number).
Merchant sends the nit obtained previously and card data to be queried. Thus, e-SiTef returns data related to the card sent.
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:

Parameter	Description	Format	Mandatory
`Content-Type`	Fixed value "application/json"	= 15 A	Yes
`merchant_id`	e-SiTef store's ID. Production and certification IDs are different.
`merchant_key`	Store authentication key in e-SiTef. Production and certification keys are different.	≤ 80 A	Yes
`nit`	Pre-authorization transaction ID in e-SiTef. Obtained at beginTransaction response.	= 64 A	Yes

Card query example with authorizer's parameter

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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":"Redecard",
        "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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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":"Redecard",
        "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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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":"Redecard",
        "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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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"
    }
}

Request parameters

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

Parameter	Description	Format	Size	Mandatory
`authorizer_id`	Authorizer ID used in transaction, as listed in the Authorizer's list. Mandatory only when `"wallet_transaction_id"` is sent.	N	≤ 3	NO
`number`	Buyer's card number PAN).	N	≤ 19	NO
`token`	Hash of stored card at e-SiTef. It's not allowed to send the fields `number` and `token`on the same request.	AN	= 88	NO
`wallet_transaction_id`	Digital 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`, `token`or `wallet_transaction_id` on the same request.	AN	≤ 25	NO

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:

Parameter	Description	Format	Size
`code`	e-SiTef response code. Anything besides "0" means failure. See more information at the Response Code document	N	≤ 4
`message`	e-SiTef response message.	AN	≤ 500
`status`	e-SiTef pre-authorization transaction status.	AN	= 3
`authorizer_code`	Authorizer responde code.	AN	≤ 10
`authorizer_message`	Authorizer's response message	AN	≤ 500
`acquirer_name`	Acquirer's name. Ex.: Cielo	AN	≤ 256
`authorizer_id`	Authorizer ID use in transaction.	N	≤ 3
`is_customer_id_required`	Indicates wether the gathering of customer's ID is mandatory.	T/F	≤ 5
`is_expiry_date_required`	Indicates wether the gathering of the buyer's card expiration date is mandatory.	T/F	≤ 5
`is_installment_funding_enabled`	Indicates wether the installment is enabled.	T/F	≤ 5
`is_security_code_required`	Indicates wether the gathering of card's security code is mandatory.	T/F	≤ 5
`is_spot_sale_enabled`	Indicates if spot sale is enabled.	T/F	≤ 5
`is_with_interest_sale_enabled`	Indicates if payment with interest is enabled.	T/F	≤ 5
`is_without_interest_sale_enabled`	Indicates if payment without interest is enabled.	T/F	≤ 5
`max_installments_with_interest`	Max installments with interest.	N	≤ 2
`min_installments_with_interest`	Min installments with interest.	N	≤ 2
`visa_checkout_data`	Returned data from Visa Checkout.
`financing_plan_list`	Object 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_required`	Indicates the obligation to collect the user's zip code (CEP in Brazil).	T/F	< 5
`key`	Prefix name.	AN	≤ 1024
`value`	Prefix value	AN	≤ 1024