List Customer Cards

Customer cards

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

import requests

url = "https://api.cartevo.co/api/v1/customers/{id}/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/customers/{id}/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/customers/{id}/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/customers/{id}/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/customers/{id}/cards")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/customers/{id}/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": [
    {
      "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

customers

{id}

cards

Customer cards

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

import requests

url = "https://api.cartevo.co/api/v1/customers/{id}/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/customers/{id}/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/customers/{id}/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/customers/{id}/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/customers/{id}/cards")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/customers/{id}/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": [
    {
      "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 /customers/{id}/cards returns all cards owned by the specified customer. Use it instead of GET /cards (which lists every card in your company) when you only want one customer’s cards — there is no customer_id filter on the company-wide list.

When to use it

Show a customer’s cards on their profile.
Check how many cards a customer holds before issuing another.

Prerequisites

The customer must belong to your company.

Request

Headers

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

Path parameters

Name	Type	Description
`id`	string	Customer ID (UUID).

Query parameters

Name	Type	Default	Description
`sync`	boolean	`false`	When `true`, refreshes each card’s balance and status from the provider before returning (slower). Omit for the cached database values.

Response

200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
      "status": "ACTIVE",
      "balance": 100.0,
      "masked_number": "4111********1111",
      "brand": "VISA",
      "currency": "USD",
      "created_at": "2026-05-09T10:15:00.000Z"
    }
  ]
}

data is an array of the customer’s cards. An empty list is returned as 404 (no cards found for the customer).

Error responses

Status	Trigger
`404`	The customer has no cards, or does not belong to your company.

Code examples

cURL

curl "https://api.cartevo.co/api/v1/customers/8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b/cards" \
  -H "Authorization: Bearer $TOKEN"

cURL (with provider sync)

curl "https://api.cartevo.co/api/v1/customers/8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b/cards?sync=true" \
  -H "Authorization: Bearer $TOKEN"

GET /cards — list all cards in your company.
GET /cards/{id} — full details for one card.
GET /customers/{id}/transactions — all card transactions for the customer.

Authorizations

Authorization

string

header

required

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

Path Parameters

string<uuid>

required

Customer ID.

Query Parameters

sync

boolean

When true, refreshes each card's balance and status from the provider before returning. Slower; omit for the cached database values.

Response

The customer's cards.

success

boolean

Example:

true

statusCode

integer

Example:

200

message

string

Example:

"Data retrieved successfully"

data

object[]

Show child attributes

Get Customer by ID List Customer Transactions

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Prerequisites

Request

Headers

Path parameters

Query parameters

Response

200 — Success

Error responses

Code examples

Authorizations

Path Parameters

Query Parameters

Response

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Path parameters

​Query parameters

​Response

​200 — Success

​Error responses

​Code examples

​Related

Authorizations

Path Parameters

Query Parameters

Response

Overview

When to use it

Prerequisites

Request

Headers

Path parameters

Query parameters

Response

200 — Success

Error responses

Code examples

Related