Card Query

Brazil

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

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

curl 
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/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.",
  "payment": {
    "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 without authorizer

Request:

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

curl 
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/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.",
  "payment": {
    "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

Request:

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

curl 
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/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.",
  "payment": {
    "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",
        "expired": "false",
        "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 with financing plans

Request:

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

curl 
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"6543210987654321"
   },
   "authorizer_id":"313"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV"
  },
  "card": {
    "acquirer_name": "Via Certa Financiadora",
    "authorizer_id": "313",
    "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": "99",
    "min_installments_with_interest": "00",
    "prefixes": {
      "CADSENHA": "11",
      "NPSAQ": "0199",
      "ECHO": "MIG3DH00000"
    },
    "financing_plan_list": [
      {
        "cod_plano": "0201",
        "tipo_plano": "02",
        "desc_plano": "Plano de Teste para CDC 01                        ",
        "parc_plano": "99"
      },
      {
        "cod_plano": "0301",
        "tipo_plano": "03",
        "desc_plano": "Plano de Teste para Saque e CDC 01                ",
        "parc_plano": "99"
      },
      {
        "cod_plano": "0201",
        "tipo_plano": "02",
        "desc_plano": "Plano de Teste para CDC 01                        ",
        "parc_plano": "99"
      },
      {
        "cod_plano": "0202",
        "tipo_plano": "02",
        "desc_plano": "Plano de Teste para CDC 02                        ",
        "parc_plano": "99"
      },
      {
        "cod_plano": "0301",
        "tipo_plano": "03",
        "desc_plano": "Plano de Teste para Saque e CDC 01                ",
        "parc_plano": "99"
      },
      {
        "cod_plano": "0302",
        "tipo_plano": "03",
        "desc_plano": "Plano de Teste para Saque e CDC 02                ",
        "parc_plano": "99"
      },
      {
        "cod_plano": "0303",
        "tipo_plano": "03",
        "desc_plano": "Plano de Teste para Saque e CDC 03                ",
        "parc_plano": "99"
      }
    ]
  }
}

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

curl 
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/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"
  },
  "payment": {
    "status": "NOV"
  }
}

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

curl 
--request POST "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr/cards"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "card":{
    "number":"4036952187654321"
  },
  "routing_id":"414"
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "payment": {
    "status": "NOV"
  },
  "details": [
    {
      "brand": "VISA",
      "brand_product_id": "VI",
      "card_function": "CREDIT",
      "issuer_country": "USA",
      "issuer_name": "Simulation"
    },
    {
      "brand": "VISA",
      "brand_product_id": "VI",
      "card_function": "DEBIT",
      "issuer_country": "BRA",
      "issuer_name": "Simulation"
    }
  ]
}

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

Updated 14 days ago