Get List of Payment Cards (Paginated)

This endpoint retrieves a paginated list of payment cards associated with the authenticated account. It supports filtering by BIN, last four digits, active status, and the ability to scope results to sub-user cards only. Each card record includes detailed metadata such as card status, cardholder information, issuing network, linked financial accounts, and visual design elements.

Endpoint

GET /api/paymentCards/v3/paginated

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint to power a card management dashboard, audit all issued cards for a customer or partner, or retrieve a filtered subset of cards — for example, displaying only cards belonging to authorized sub-users. It is also useful for reconciliation flows that need to page through large card inventories efficiently using cursor-based or offset-based pagination.

Query Parameters

Parameter	Type	Required	Description
`skip`	integer (int32)	No	Number of records to skip for offset-based pagination. Default: `0`.
`count`	integer (int32)	No	Number of records to return per page. Default: `20`.
`bin`	string	No	Filter cards by BIN (Bank Identification Number, first 6 digits).
`last4`	string	No	Filter cards by the last 4 digits of the card number.
`isActive`	boolean	No	When `true`, returns only active cards.
`cursor`	string	No	Cursor value for cursor-based pagination (from a previous response).
`lastUserId`	string	No	Last user ID from a previous page, used alongside cursor-based pagination.

Response

200 OK

Field	Type	Description
`totalCount`	integer	Total number of cards matching the query.
`errorMessage`	string	Error message if applicable; typically empty on success.
`cursor`	string	Cursor token to use for retrieving the next page of results.
`lastUserId`	string	ID of the last user in the current page, for cursor-based pagination continuity.
`records`	array	Array of payment card objects (see fields below).
`records[].id`	string	Unique identifier for the payment card.
`records[].bin`	string	Bank Identification Number (first 6 digits, masked).
`records[].last4`	string	Last 4 digits of the card number.
`records[].status`	string	Card status: `ACTIVATION_REQUIRED`, `ACTIVE`, `SUSPENDED`, or `CLOSED`.
`records[].formFactor`	string	Card form factor: Physical, Virtual, or Burner.
`records[].expirationDate`	string	Card expiration date.
`records[].network`	string	Card network (e.g., Visa, Mastercard).
`records[].cardType`	integer (int32)	Integer enum indicating the card type (0–4).
`records[].cardholder`	string	Full name of the cardholder.
`records[].subProfile`	string	Name of the associated sub-user profile, if applicable.
`records[].department`	string	Department the cardholder belongs to, if applicable.
`records[].cardName`	string	Display name assigned to the card.
`records[].financialAccounts`	array	Linked financial accounts; each entry has `id` and `name`.
`records[].financialAccounts[].id`	string	Unique identifier of the linked financial account.
`records[].financialAccounts[].name`	string	Display name of the linked financial account.
`records[].isMainCard`	boolean	`true` if this is the account holder's primary card.
`records[].partnerName`	string	Name of the partner associated with the card.
`records[].partnerId`	integer	Numeric ID of the partner associated with the card.
`records[].cardDesign`	object	URLs for card design images (front/back, small/large).
`records[].cardDesign.frontSideImageUrlXs`	string	URL for the small front-side card image.
`records[].cardDesign.frontSideImageUrlXl`	string	URL for the large front-side card image.
`records[].cardDesign.backSideImageUrlXl`	string	URL for the large back-side card image.
`records[].cardProfileSetId`	string	Identifier for the card profile configuration set.
`records[].features`	array of strings	List of enabled features for this card. Possible values: `Activate`, `Close`, `LockUnlock`, `ReissueCard`, `SetUpPin`, `OrderStatus`, `SpendingReport`, `TransactionLimits`, `TransactionLimitsViewOnly`.
`records[].subProfileId`	integer	Numeric ID of the sub-user if the card belongs to an authorized user.
`records[].isCardForReissue`	boolean	Read-only. Indicates whether the card is flagged for reissuance.

{
  "totalCount": 2,
  "errorMessage": null,
  "cursor": "eyJsYXN0SWQiOiJhYmMxMjMifQ==",
  "lastUserId": "usr_98765",
  "records": [
    {
      "id": "card_001abc",
      "bin": "411111",
      "last4": "4242",
      "status": "ACTIVE",
      "formFactor": "Physical",
      "expirationDate": "2027-08",
      "network": "Visa",
      "cardType": 0,
      "cardholder": "Jane Doe",
      "subProfile": null,
      "department": "Finance",
      "cardName": "Business Checking Card",
      "financialAccounts": [
        {
          "id": "fa_001xyz",
          "name": "Business Checking"
        }
      ],
      "isMainCard": true,
      "partnerName": "Netevia",
      "partnerId": 101,
      "cardDesign": {
        "frontSideImageUrlXs": "https://cdn.netevia.com/cards/front_xs.png",
        "frontSideImageUrlXl": "https://cdn.netevia.com/cards/front_xl.png",
        "backSideImageUrlXl": "https://cdn.netevia.com/cards/back_xl.png"
      },
      "cardProfileSetId": "cps_standard_001",
      "features": ["LockUnlock", "SetUpPin", "SpendingReport", "TransactionLimits"],
      "subProfileId": null,
      "isCardForReissue": false
    },
    {
      "id": "card_002def",
      "bin": "422222",
      "last4": "8888",
      "status": "ACTIVATION_REQUIRED",
      "formFactor": "Virtual",
      "expirationDate": "2026-12",
      "network": "Mastercard",
      "cardType": 1,
      "cardholder": "John Smith",
      "subProfile": "John Smith - Authorized User",
      "department": "Operations",
      "cardName": "Team Card",
      "financialAccounts": [
        {
          "id": "fa_002abc",
          "name": "Business Savings"
        }
      ],
      "isMainCard": false,
      "partnerName": "Netevia",
      "partnerId": 101,
      "cardDesign": {
        "frontSideImageUrlXs": "https://cdn.netevia.com/cards/virtual_front_xs.png",
        "frontSideImageUrlXl": "https://cdn.netevia.com/cards/virtual_front_xl.png",
        "backSideImageUrlXl": "https://cdn.netevia.com/cards/virtual_back_xl.png"
      },
      "cardProfileSetId": "cps_virtual_002",
      "features": ["Activate", "Close"],
      "subProfileId": 55,
      "isCardForReissue": false
    }
  ]
}

Card Statuses

Status	Description
`ACTIVATION_REQUIRED`	The card has been issued but must be activated before use.
`ACTIVE`	The card is active and ready for transactions.
`SUSPENDED`	The card is suspended; authorizations will fail until reinstated to `ACTIVE`.
`CLOSED`	The card has been permanently closed; all future authorizations will fail.

Error Codes

Code	When it happens
400	Invalid query parameter values (e.g., non-integer `skip` or `count`)
401	Token missing, expired, or invalid
403	Insufficient permissions to list cards for this account
500	Internal server error

Common Mistakes

Omitting the Authorization header or using an expired token will result in a 401 response; tokens expire after 10 minutes and must be refreshed via POST /api/auth/refresh.
Using offset-based pagination (skip/count) and cursor-based pagination (cursor/lastUserId) simultaneously can produce inconsistent results; choose one approach per request.
The cardType field is an integer enum (0–4) — do not compare it to string values in client code.
The partnerCardIcons field is deprecated and should not be used in new integrations.
When onlySubCards filtering is needed, use the isActive flag combined with subProfileId filtering on the client side, as the paginated endpoint returns all card types by default.

Related Endpoints

POST /api/paymentCards/v3 — Issue a new payment card (Physical, Virtual, or Burner)
GET /api/paymentCards/v3/{cardId} — Retrieve details for a specific payment card
PUT /api/paymentCards/v3/{cardId}/status — Update the status of a payment card (lock, unlock, close)
GET /api/paymentCards/v3/{cardId}/transactions — List transactions for a specific payment card

Example

curl -X GET "https://api.banking.netevia.dev/api/paymentCards/v3/paginated?skip=0&count=20&isActive=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Retrieve the next page using cursor-based pagination:

curl -X GET "https://api.banking.netevia.dev/api/paymentCards/v3/paginated?cursor=eyJsYXN0SWQiOiJhYmMxMjMifQ==&count=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Retrieve only cards belonging to sub-users (authorized users), paginating through results:

curl -X GET "https://api.banking.netevia.dev/api/paymentCards/v3/paginated?skip=100&count=50" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"