Skip to content
HitchPay API Docs

CARDS

List Cards

List your cards, optionally filtered by customer or status.

GET /v1/cards

Use this endpoint to

  • Page through all cards issued under your business account
  • Filter cards by customer or by status (e.g., only active cards)

Query parameters

Parameter Type Required Description
customer_id string No Filter to a single customer's uuid
status string No pending, active, frozen, terminated, or failed
page number No Page number
limit number No Results per page, max 100

Code Samples

const params = new URLSearchParams({ status: "active", page: "1", limit: "20" });

const response = await fetch(
  `https://sandbox.hitchpay.ng/v1/cards?${params}`,
  { headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" } }
);

const data = await response.json();
console.log(data);
<?php

$query = http_build_query([
  "status" => "active",
  "page" => 1,
  "limit" => 20
]);

$ch = curl_init();
curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/cards?" . $query,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
import requests

url = "https://sandbox.hitchpay.ng/v1/cards"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
params = {"status": "active", "page": 1, "limit": 20}

response = requests.get(url, params=params, headers=headers)
print(response.json())

Response

{
  "status": "success",
  "message": "Cards retrieved successfully.",
  "data": {
    "total_count": 12,
    "page": 1,
    "limit": 20,
    "cards": [
      {
        "tracking_id": "EXTCARD…",
        "customer_uuid": "…",
        "card_id": "…",
        "label": "John Doe USD Card",
        "brand": "visa",
        "card_type": "virtual",
        "currency": "USD",
        "masked_pan": "539983******1234",
        "last4": "1234",
        "exp_month": "08",
        "exp_year": "2029",
        "cardholder_name": "JOHN DOE",
        "balance": 25.00,
        "status": "active",
        "date_created": "1782947655"
      }
    ]
  }
}

Fields

Field Type Description
total_count number Total cards matching the filter
page / limit number Pagination echoed back
cards array Card objects see the card object shape in the Overview page

Errors

Code Meaning
UNAUTHORIZED Business not found or inactive
INVALID_REQUEST Invalid filter values, e.g. unsupported status

Questions? Email [email protected]. Also on GitBook.