List of tokenized cards

Call details#

Resource: /v1/cards/list
HTTP Method: GET
Request format: JSON
Response format: JSON
Header Parameters:

Parameter	Description	Format	Mandatory
`merchant_id`	Store code on Carat. Production and certification codes will be different.	< 15 AN	YES
`merchant_key`	Store authentication key in Carat. The production and certification keys will be different.	< 80 AN	YES
`token`	Token obtained from the token creation service Learn more.. If `Authorization` is not sent, this field becomes mandatory	= 66 AN	COND.
`Authorization`	The store authentication signature must be sent in the format `Bearer {signature}`. Example: `Bearer JHVGytfdgauygdauiw78264284527852897hagdg`. If `token` is not sent, this field will be mandatory	< 2000 AN	COND.
`Content-Type`	It must be sent with the value `application/json`.	= 15 AN	YES

Flow#

Examples#

Below are some examples of calling the tokenized card listing service using the cURL tool.

List of tokenized cards using token#

Request:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl --location --request GET 'https://{{url}}/e-sitef/api/v1/cards/list?authorizer_id=1&status=ATV&page=0&limit=1' \
--header 'merchant_id: xxxxxxxxxxx' \
--header 'merchant_key: xxxxxxxxxxx' \
--header 'token: ca6ff575d51b013dc01ab4059c63aebb055af2963b8a31043daa33e16b20750e01'
--verbose

Listing of tokenized cards using signature#

Request:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl --location --request GET 'https://{{url}}/e-sitef/api/v1/cards/list?authorizer_id=1&status=ATV&page=0&limit=1' \
--header 'merchant_id: LOJATESTE' \
--header 'merchant_key: F19DE00177C301DF24A865F11AA9B2567F604891F0F44DDAEFD69E3399E0B7E1' \
--header 'Authorization: Bearer XXXXX'

Response:

{
    "response_code": "0",
    "response_message": "OK. Transaction successful.",
    "cards": [
        {
            "status": "ATV",
            "authorizer_id": 1,
            "token": "S1uloKsLc+CLVhbOtf1SBg0WwTCbYLBsxh29jgKwhm-jNAfkQ1g-u6vcWfiV5gH1CfyAhu8Hl5fXR2ho+Cmrjw==",
            "bin": "455182",
            "suffix": "2345",
            "expiration_date": "1129",
            "customer_id": "1",
            "creation_date": "14/11/2023T00:21",
            "modification_date": "14/11/2023T02:56"
        },
        {
            "status": "ATV",
            "authorizer_id": 1,
            "token": "wAVdAIFCTkCTRZSL+BOH93hJYlBlD7Z4QhRDnyp6pbLQpfYE+rcUh740Tpf9Svvc5nLKZqKFuc4aZpTo41jc8Q==",
            "bin": "401200",
            "suffix": "1112",
            "expiration_date": "1212",
            "customer_id": "kakaroto",
            "creation_date": "07/04/2024T23:22",
            "modification_date": "09/05/2012T15:54"
        }       
    ],
    "current_page": "0",
    "total_pages": "1",
    "count": "2"
}

Request parameters#

The table below describes the request parameters for the tokenized card listing service:

Parameter	Description	Format	Mandatory
`authorizer_id`	Authorizer code in Carat. Learn more.	3 N	NO
`status`	Card status storing in Carat `ATV` (Active) or `INA` (Inactive).	= 3 AN	NO
`page`	Listing page. The first page has a value of `0`. If it is not sent, we will assume the value `0`.	3 N	NO
`limit`	Maximum number of records per page. If it is not sent, we will assume the maximum value `100`	3 N	NO

Response parameters#

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. In the table below is the description of the response parameters of the tokenized card listing service:

Parameter	Description	Format
`code`	Carat response code. Any code other than `0` (zero) means failure. Learn more.	< 4 N
`message`	Carat response message.	< 500 AN
`current_page`	Current records page.	< 4 AN
`total_pages`	Total number of pages.	< 4 AN
`count`	Total record count.	< 4 AN
card
`status`	Card status.	= 3 AN
`customer_id`	Buyer identification for card storage.	= 20 AN
`authorizer_id`	Authorizer code used in storage.	< 3 N
`token`	Identification of the stored card. This token must be used instead of the buyer's card to carry out transactions with Carat.	= 88 AN
`suffix`	Last 4 digits of the buyer's card.	= 4 AN
`bin`	First 6 digits of the buyer's card.	= 6 AN
`expiration_date`	Card expiration date in `MMYA` format.	= 4 N
`creation_date`	Creation date in card storage in the format: `DD/MM/YYYY'T'HH:mm`. Example: `07/13/2017T16:03`	= 16 D
`modification_date`	Date that was changed in the card storage in the format: `DD/MM/YYYY'T'HH:mm`. Example: `07/13/2017T16:03`	= 16 D