List Cards

List cards

curl --request GET \
  --url https://api.cartevo.co/api/v1/cards \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cartevo.co/api/v1/cards"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cartevo.co/api/v1/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartevo.co/api/v1/cards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartevo.co/api/v1/cards"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cartevo.co/api/v1/cards")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/cards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "company_id": "eca5e982-00b5-4aa2-b709-7d5cd673e95c",
    "statistics": {
      "total": 5,
      "active": 5,
      "frozen": 0,
      "terminated": 0,
      "pending": 0,
      "failed": 0,
      "total_balance": 16,
      "available_slots": 5,
      "by_customer": {}
    },
    "cards": [
      {
        "id": "91b3c6d6-111b-44da-9f81-16f019bebe8c",
        "customer_id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
        "status": "ACTIVE",
        "balance": 5,
        "masked_pan": "**** **** **** 5407",
        "currency": "USD",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "is_active": true,
        "is_virtual": true
      }
    ]
  }
}

GET

cards

List cards

curl --request GET \
  --url https://api.cartevo.co/api/v1/cards \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cartevo.co/api/v1/cards"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cartevo.co/api/v1/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cartevo.co/api/v1/cards",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cartevo.co/api/v1/cards"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cartevo.co/api/v1/cards")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/cards")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "company_id": "eca5e982-00b5-4aa2-b709-7d5cd673e95c",
    "statistics": {
      "total": 5,
      "active": 5,
      "frozen": 0,
      "terminated": 0,
      "pending": 0,
      "failed": 0,
      "total_balance": 16,
      "available_slots": 5,
      "by_customer": {}
    },
    "cards": [
      {
        "id": "91b3c6d6-111b-44da-9f81-16f019bebe8c",
        "customer_id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
        "status": "ACTIVE",
        "balance": 5,
        "masked_pan": "**** **** **** 5407",
        "currency": "USD",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "is_active": true,
        "is_virtual": true
      }
    ]
  }
}

Overview

GET /cards returns every card issued under your company, plus a statistics block summarizing counts and balances by status and per customer. Use it to populate dashboards, reconcile your own card records, or look up a specific card by last-4.

When to use it

Render a “all cards” view in your back-office.
Reconcile your records against Cartevo’s source of truth.
Find a card by last-4 when a customer reports an issue without knowing the card ID.

Prerequisites

Authenticated as a company user.

Request

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`

Query parameters

Name	Type	Required	Description
`status`	string	No	Filter by card status. One of `PENDING`, `ACTIVE`, `FROZEN`, `SUSPENDED`, `TERMINATED`, `FAILED`.
`brand`	string	No	Filter by `VISA` or `MASTERCARD` (case-insensitive).
`last4`	string	No	Last 4 digits of the card PAN. Useful for support lookups.
`sync`	boolean	No	If `true`, force a re-fetch from the upstream issuer before returning. Slower; default `false`.

Response

200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "company_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "statistics": {
      "total": 142,
      "active": 120,
      "frozen": 5,
      "terminated": 15,
      "pending": 1,
      "failed": 1,
      "total_balance": 18450.75,
      "available_slots": 858,
      "by_customer": {
        "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b": {
          "cards": 2,
          "balance": 245.5
        }
      }
    },
    "cards": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "customer_id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
        "status": "ACTIVE",
        "balance": 100.0,
        "masked_pan": "4111********1111",
        "brand": "VISA",
        "currency": "USD",
        "is_active": true,
        "is_virtual": true,
        "created_at": "2026-05-09T10:15:00.000Z",
        "updated_at": "2026-05-09T10:15:02.500Z"
      }
    ]
  }
}

Field	Type	Description
`data.company_id`	string	Echoes your company ID for client-side validation.
`data.statistics.total`	integer	Number of cards (filtered by query, if any).
`data.statistics.total_balance`	number	Sum of `balance` across all returned cards (USD).
`data.statistics.available_slots`	integer	How many more cards your company can issue under its current plan.
`data.statistics.by_customer`	object	Map of `customer_id → { cards, balance }`.
`data.cards[]`	array	Card records — see `GET /cards/{id}` for the per-card field reference.

Note: This endpoint is not paginated — it returns the full set in a single response. If your company has more than a few thousand cards, prefer per-customer lookups via GET /customers/{id}/cards (currently undocumented; reach out if you need it).

Error responses

Status	Trigger
`401`	Missing or expired Bearer token.
`400`	Invalid `status` or `brand` value.

Code examples

cURL

curl -G https://api.cartevo.co/api/v1/cards \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "brand=VISA"

Node.js (axios)

const { data } = await axios.get("https://api.cartevo.co/api/v1/cards", {
  headers: { Authorization: `Bearer ${token}` },
  params: { status: "ACTIVE", brand: "VISA" },
});
console.log(`${data.data.statistics.total} active VISA cards`);

GET /cards/{id} — full card detail (with optional reveal).
POST /cards — issue a new card.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

200 - application/json

A list of cards with company statistics.

success

boolean

Example:

true

statusCode

integer

Example:

200

message

string

Example:

"Data retrieved successfully"

data

object

Show child attributes

Create Card Get Card Details

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Prerequisites

Request

Headers

Query parameters

Response

200 — Success

Error responses

Code examples

Authorizations

Response

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Query parameters

​Response

​200 — Success

​Error responses

​Code examples

​Related

Authorizations

Response

Overview

When to use it

Prerequisites

Request

Headers

Query parameters

Response

200 — Success

Error responses

Code examples

Related