Cards API Concepts

The Cards API provides card-level data access for partners who need to view cardholder cards, transactions, and payment accounts. Unlike the Distributors API (which is scoped to distributors and their card programs), the Cards API is scoped to individual cards and their associated data.

---

When to Use the Cards API

Use the Cards API when you need to:

• View cards associated with a specific cardholder
• Access transaction history for individual cards
• View payment accounts linked to cards
• Access linked bank account transactions

The Cards API is a read-oriented API — it provides visibility into card-level data rather than management operations.

---

Core Entities

Cardholder Cards

A cardholder card represents an individual card issued to a cardholder. Each card is associated with a distributor card (card program) and has its own transaction history and payment accounts.

The Cards API allows you to:

• List cards within your access scope
• View card details including status and associated distributor card

Transactions

Transactions represent card activity — purchases, refunds, and other financial events processed through the card network. The Cards API provides:

• Transaction history for specific cards
• Transaction details including amount, merchant, and status
• Filtering and pagination for large transaction sets

Payment Accounts

Payment accounts are funding sources linked to a card. These may include:

• Payment gateway accounts (created via the Payments API)
• Currency-based payment accounts (created via the Currency API)

The Cards API provides read access to payment account information associated with cards.

Payment Account Transactions

Payment account transactions track activity related to specific payment accounts — funding events, balance changes, and settlement activity.

Linked Bank Account Transactions

Linked bank account transactions provide visibility into bank account activity connected to cards.

---

Relationship to Other APIs

---

Distributor Cards (Card Programs)

A distributor card (also called a card program) is a template that defines how cards are issued. The Cards API lets you list the distributor cards within your scope. Each distributor card belongs to a distributor, and cardholders receive cards issued under these programs.

---

Transaction States

Transactions progress through a lifecycle of states:

When querying transaction history, you may see transactions in any of these states. The card_transaction_state_logs on each transaction provide the full history of state changes.

---

Filtering and Sorting

Cards API list endpoints support filtering and sorting:

• Pagination — All list endpoints support page and per_page parameters (see Pagination and Rate Limits)
• Sorting — Transaction lists support sort (e.g., created_at, total_amount) and sort_direction (asc or desc)
• Date filtering — Filter transactions by date range using from and to query parameters

---

Data Scoping

Cards API data is scoped to the distributor cards (card programs) associated with your partner account. You only see cards, transactions, and payment accounts for cards issued under those programs. See API Scoping and Permissions for details.

---

Related Guides

• API Authentication and Credentials — How to authenticate API requests
• API Scoping and Permissions — How data is scoped to your partner account
• Pagination and Rate Limits — Paginating list responses
• Cards API Reference — Full endpoint documentation