Home

    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
    sandbox.ecomm-bin.fiserv.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
    sandbox.ecomm-bin.fiserv.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
    sandbox.ecomm-bin.fiserv.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
    sandbox.ecomm-bin.fiserv.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