Get List of Payment Cards with Pagination

The GET /api/paymentCards/v3 endpoint retrieves detailed information about all payment cards linked to the authenticated user's account. It returns key card attributes including masked card numbers, expiration dates, form factor, network, card type, and the financial accounts each card is associated with. This endpoint supports an optional query parameter to filter results to authorized user (subprofile) cards only.

Endpoint

GET /api/paymentCards/v3

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 when you need to display a customer's full list of active payment cards — for example, in a card management dashboard or during checkout flows. It is also useful for auditing which cards are linked to specific financial accounts or for identifying cards that require reissuance. Partners building subprofile (authorized user) management features can filter results to show only subprofile cards using the onlySubCards parameter.

Query Parameters

Response

200 OK

Returns an array of payment card objects.

[
  {
    "id": "card_abc123xyz456",
    "bin": "411111",
    "last4": "4242",
    "status": "ACTIVE",
    "formFactor": "PHYSICAL",
    "expirationDate": "09/2027",
    "network": "VISA",
    "cardType": 1,
    "cardholder": "Jane Smith",
    "subProfile": null,
    "department": "Operations",
    "cardName": "My Business Card",
    "financialAccounts": [
      {
        "id": "acct_def456uvw789",
        "name": "Primary Checking"
      }
    ],
    "isMainCard": true,
    "partnerName": "Netevia",
    "partnerId": 1001,
    "partnerCardIcons": [],
    "cardDesign": {
      "frontSideImageUrlXs": "https://cdn.netevia.com/cards/design_xs.png",
      "frontSideImageUrlXl": "https://cdn.netevia.com/cards/design_xl.png",
      "backSideImageUrlXl": "https://cdn.netevia.com/cards/design_back_xl.png"
    },
    "cardProfileSetId": "cps_ghi789rst012",
    "features": [
      "LockUnlock",
      "ReissueCard",
      "SetUpPin",
      "SpendingReport",
      "TransactionLimits"
    ],
    "subProfileId": null,
    "isCardForReissue": false
  },
  {
    "id": "card_jkl321mno654",
    "bin": "411111",
    "last4": "9999",
    "status": "ACTIVE",
    "formFactor": "VIRTUAL",
    "expirationDate": "12/2025",
    "network": "VISA",
    "cardType": 1,
    "cardholder": "Jane Smith",
    "subProfile": null,
    "department": null,
    "cardName": "Online Purchases",
    "financialAccounts": [
      {
        "id": "acct_def456uvw789",
        "name": "Primary Checking"
      }
    ],
    "isMainCard": false,
    "partnerName": "Netevia",
    "partnerId": 1001,
    "partnerCardIcons": [],
    "cardDesign": {
      "frontSideImageUrlXs": "https://cdn.netevia.com/cards/virtual_xs.png",
      "frontSideImageUrlXl": "https://cdn.netevia.com/cards/virtual_xl.png",
      "backSideImageUrlXl": "https://cdn.netevia.com/cards/virtual_back_xl.png"
    },
    "cardProfileSetId": "cps_ghi789rst012",
    "features": [
      "Close",
      "LockUnlock",
      "SpendingReport",
      "TransactionLimitsViewOnly"
    ],
    "subProfileId": null,
    "isCardForReissue": true
  }
]

Error Codes

Common Mistakes

• Passing onlySubCards=true when the account has no authorized users (subprofiles) will return an empty array — this is expected behavior, not an error.
• The cardType field is an integer enum, not a string. Do not compare it to string values such as "DEBIT" — use the numeric values (e.g., 1 for Debit).
• The partnerCardIcons field is deprecated. Do not rely on it for card branding or display logic; use cardDesign image URLs instead.
• Card numbers are never returned in full. Use bin and last4 together to identify a card for display purposes. Full PAN is never exposed through this endpoint.
• Burner cards have a distinct card design schema that includes additional fields (burnerFrontSideImageUrlXs, burnerFrontSideImageUrlXl, burnerBackSideImageUrlXl). Handle both carddesign and carddesignsettings shapes in your client code.
• The features array controls which actions are permitted for a given card. Always check this array before rendering card management options (e.g., hide "Set PIN" if SetUpPin is absent).

Related Endpoints

• POST /api/paymentCards — Create a new payment card (physical, virtual, or burner)
• GET /api/paymentCards/{id} — Retrieve details for a single payment card by ID
• PUT /api/paymentCards/{id}/lock — Lock or unlock a specific payment card
• DELETE /api/paymentCards/{id} — Close a payment card
• GET /api/paymentCards/v3 with onlySubCards=true — List cards belonging to authorized users only

Example

curl -X GET "https://api.banking.netevia.dev/api/paymentCards/v3" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

To retrieve only authorized user (subprofile) cards:

curl -X GET "https://api.banking.netevia.dev/api/paymentCards/v3?onlySubCards=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"