Card Query (Pre-Authorization)

Brazil

import ResponseCodes from './codigos-de-resposta.md';
import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

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:

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).
Merchant sends the nit obtained previously and card data to be queried. Thus, Carat Portal 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`	Carat Portal store's ID. Production and certification IDs are different.
`merchant_key`	Store authentication key in Carat Portal. Production and certification keys are different.	≤ 80 A	Yes
`nit`	Pre-authorization transaction ID in Carat Portal. Obtained at beginTransaction response.	= 64 A	Yes

Card query example with authorizer's parameter

Request:

To use this example, don't forget to define the variable {{url}} to the value

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

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

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": "[email protected]",
        "user_email": "[email protected]",
        "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

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

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 Carat Portal. 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`	Carat Portal response code. Anything besides "0" means failure. See more information at the Response Code document	N	≤ 4
`message`	Carat Portal response message.	AN	≤ 500
`status`	Carat Portal 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

Updated 14 days ago