# Card Query

<BraEng />

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

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/4c2ca9e10b8176b221f62d8f148da6b44ac8dd7b8bc1b79890279ea2d2eb7585-consultacartao-rest-fluxo-EN.png",
        null,
        "Consulta Cartão"
      ],
      "align": "center"
    }
  ]
}
[/block]


**Flow description:**

1. 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).
2. 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.
3. 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

<ApiDoc method="post" path="/e-sitef/api/v1/payments/{nit}/cards" />

- **Resource:** `/v1/payments/{nit}/cards`
- **HTTP Method:** `POST`
- **Request format:** `JSON`
- **Response format:** `JSON`
- **Header parameters:**

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Format",
    "h-3": "Mandatory",
    "0-0": "`merchant_id`",
    "0-1": "Merchant code on Carat Portal. The production and certification codes will be different.",
    "0-2": "<u>\\<</u> 15 AN",
    "0-3": "YES",
    "1-0": "`merchant_key`",
    "1-1": "Merchant authentication key on Carat Portal. The production and certification keys will be different.",
    "1-2": "<u>\\<</u> 80 AN",
    "1-3": "YES",
    "2-0": "`Content-Type`",
    "2-1": "It must be sent with the value `application/json`.",
    "2-2": "= 15 AN",
    "2-3": "YES"
  },
  "cols": 4,
  "rows": 3,
  "align": [
    null,
    null,
    null,
    null
  ]
}
[/block]


> **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<br/> **<URLPOSTMAN/>**

```bash
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:**

```json
{
  "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<br/> **<URLPOSTMAN/>**

```bash
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:**

```json
{
  "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<br/> **<URLPOSTMAN/>**

```bash
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:**

```json
{
  "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": "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",
        "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<br/> **<URLPOSTMAN/>**

```bash
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:**

```json
{
  "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<br/> **<URLPOSTMAN/>**

```bash
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:**

```json
{
  "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<br/> **<URLPOSTMAN/>**

```bash
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:**

```json
{
  "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"
    }
  ]
}
```

<ResponseCodes />

## Request parameters

The table below describes the request parameters of the card query service:

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Format",
    "h-3": "Mandatory",
    "0-0": "`authorizer_id`",
    "0-1": "Code of the authorizer on Carat Portal. [Learn more.](autorizadoras.md) This field is only mandatory when the `wallet_transaction_id` field is sent. <br/> If this parameter is absent, Carat Portal assumes it's a credit card.",
    "0-2": "<u>\\<</u> 3 N",
    "0-3": "COND.",
    "1-0": "**card**",
    "1-1": "",
    "1-2": "",
    "1-3": "",
    "2-0": "`number`",
    "2-1": "Customer card number (PAN).",
    "2-2": "<u>\\<</u> 19 N",
    "2-3": "YES",
    "3-0": "`token`",
    "3-1": "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.",
    "3-2": "= 88 AN",
    "3-3": "NO",
    "4-0": "`wallet_transaction_id`",
    "4-1": "Digital wallet transaction ID. Currently, this functionality is only available to the Visa Checkout authorizer.<br/>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.",
    "4-2": "<u>\\<</u> 25 AN",
    "4-3": "NO",
    "5-0": "`do_par_inquiry`",
    "5-1": "Informs if the VISA PAR Inquiry request will be performed. The response value will be returned on the [response](#parâmetros-de-resposta) `par` field. <br/><br/>Allowed values: <br/>`true` - PAR request will be sent. <br/> `false` - PAR request will not be sent.<br/><br/>Default value: `false`",
    "5-2": "<u>\\<</u> 5 A",
    "5-3": "NO"
  },
  "cols": 4,
  "rows": 6,
  "align": [
    null,
    null,
    null,
    null
  ]
}
[/block]


## 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:

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Description",
    "h-2": "Format",
    "0-0": "`code`",
    "0-1": "Carat Portal response code. Any code different from `0` means failure. [Learn more.](codigos-da-api.md#response-codes)",
    "0-2": "<u>\\<</u> 4 N",
    "1-0": "`message`",
    "1-1": "Carat Portal response message.",
    "1-2": "<u>\\<</u> 500 AN",
    "2-0": "**payment**",
    "2-1": "",
    "2-2": "",
    "3-0": "`status`",
    "3-1": "Status of the payment transaction on Carat Portal. [Learn more.](codigos-da-api.md#transaction-status)",
    "3-2": "= 3 AN",
    "4-0": "**card**",
    "4-1": "",
    "4-2": "",
    "5-0": "`authorizer_code`",
    "5-1": "Authorizer response code.",
    "5-2": "<u>\\<</u> 10 AN",
    "6-0": "`authorizer_message`",
    "6-1": "Authorizer response message.",
    "6-2": "<u>\\<</u> 500 AN",
    "7-0": "`acquirer_name`",
    "7-1": "Routing name, e.g.: Cielo",
    "7-2": "<u>\\<</u> 256 AN",
    "8-0": "`authorizer_id`",
    "8-1": "Code of the authorizer (use this ID when making the payment).",
    "8-2": "<u>\\<</u> 3 N",
    "9-0": "`is_customer_id_required`",
    "9-1": "Indicates the requirement of collecting the customer ID.",
    "9-2": "<u>\\<</u> 5 T/F",
    "10-0": "`is_expiry_date_required`",
    "10-1": "Indicates the requirement of collecting the card expiry date.",
    "10-2": "<u>\\<</u> 5 T/F",
    "11-0": "`is_installment_funding_enabled`",
    "11-1": "Indicates if installment funding is enabled.",
    "11-2": "<u>\\<</u> 5 T/F",
    "12-0": "`is_security_code_required`",
    "12-1": "Indicates the requirement of collecting the security code.",
    "12-2": "<u>\\<</u> 5 T/F",
    "13-0": "`is_spot_sale_enabled`",
    "13-1": "Indicates if spot sale is enabled.",
    "13-2": "<u>\\<</u> 5 T/F",
    "14-0": "`is_with_interest_sale_enabled`",
    "14-1": "Indicates if installments with interest are enabled.",
    "14-2": "<u>\\<</u> 5 T/F",
    "15-0": "`is_without_interest_sale_enabled`",
    "15-1": "Indicates if installments without interest are enabled.",
    "15-2": "<u>\\<</u> 5 T/F",
    "16-0": "`max_installments_with_interest`",
    "16-1": "Maximum number of installments with interest.",
    "16-2": "<u>\\<</u> 2 N",
    "17-0": "`min_installments_with_interest`",
    "17-1": "Minimum number of installments with interest.",
    "17-2": "<u>\\<</u> 2 N",
    "18-0": "`visa_checkout_data`",
    "18-1": "Object with the data returned by Visa Checkout.",
    "18-2": "O",
    "19-0": "`financing_plan_list`",
    "19-1": "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:<br/>`cod_plano`: financing plan identifier code. It must be sent in payment effectuation service;<br/>`tipo_plano`: financing plan type code;<br/>`desc_plano`: financing plan description text. It can be shown to the customer;<br/>`parc_plano`: maximum amount of installments in financing plan.",
    "19-2": "O",
    "20-0": "`is_customer_postal_code_required`",
    "20-1": "Indicates the requirement of hte user’s postal code (CEP in Brazil)",
    "20-2": "<u>\\<</u> 5 T/F",
    "21-0": "`par`",
    "21-1": "PAR value returned by VISA of the field `do_par_inquiry` was sent with the value `true` on the [request](#request-parameters).",
    "21-2": "<u>\\<</u> 32 AN",
    "22-0": "**card.prefixes\\[]** This field contains the prefixes (additional data) returned by SiTef.",
    "22-1": "",
    "22-2": "",
    "23-0": "key",
    "23-1": "Prefix name.",
    "23-2": "<u>\\<</u> 1024 AN",
    "24-0": "value",
    "24-1": "Prefix value.",
    "24-2": "<u>\\<</u> 1024 AN",
    "25-0": "**details\\[]** This field contains details returned by IPG routing",
    "25-1": "",
    "25-2": "",
    "26-0": "brand",
    "26-1": "The card brand.",
    "26-2": "<u>\\<</u> 1024 AN",
    "27-0": "brand_product_id",
    "27-1": "The product ID of the brand.",
    "27-2": "<u>\\<</u> 1024 AN",
    "28-0": "card_function",
    "28-1": "Card function.",
    "28-2": "CREDIT, <br/> DEBIT, <br/> PREPAID, <br/> VOUCHER, <br/> UNDEFINED",
    "29-0": "commercialCard",
    "29-1": "Indicates whether it is a corporate or non-corporate card.",
    "29-2": "CORPORATE, <br/> NON_CORPORATE",
    "30-0": "issuer_country",
    "30-1": "The country of the issuer.",
    "30-2": "<u>\\<</u> 1024 AN",
    "31-0": "issuer_name",
    "31-1": "The name of the issuer.",
    "31-2": "<u>\\<</u> 1024 AN"
  },
  "cols": 3,
  "rows": 32,
  "align": [
    null,
    null,
    null
  ]
}
[/block]