Get List of Payment Cards

The GET /api/paymentCards endpoint retrieves all payment cards linked to the authenticated customer's account. The response includes masked card numbers, card type, expiration details, network, status, and the financial accounts each card is associated with. This endpoint supports both personal and business customers and returns paginated results via a cursor-based connection structure.

Endpoint

GET /api/paymentCards

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 display a customer's card portfolio in a dashboard or card management screen. It is the primary way to enumerate all physical, virtual, and burner cards for a given account holder, including cards assigned to authorized users (subProfiles) on business accounts. Call this endpoint before performing card-specific operations (e.g., freeze, update spending limits) to obtain the card id required by those endpoints.

Response

200 OK

The response is wrapped in a GraphQL-style edge/node connection. The top-level node is an accountholder object containing account holder identity and a nested paymentCards connection.

Top-level response — edge_accountholder

node — accountholder

name — person.name

businessProfile.name — business.businessname

paymentCards — connection_paymentcardresponse

pageInfo — pageinfo

edges[].node — paymentcardresponse

financialAccounts[] — financialaccountshort

{
  "cursor": "Y3Vyc29yOnYyOpK5MjAyNC0wMS0xNVQxMjowMDowMCswMDowMM4A",
  "node": {
    "typename": "BusinessAccountHolder",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith",
      "title": null,
      "suffix": null,
      "middleName": null
    },
    "businessProfile": {
      "name": {
        "legalBusinessName": "Acme Corporation LLC",
        "doingBusinessAsName": "Acme Corp"
      }
    },
    "primaryAuthorizedPerson": {
      "name": {
        "givenName": "Jane",
        "familyName": "Smith",
        "title": null,
        "suffix": null,
        "middleName": null
      }
    },
    "paymentCards": {
      "pageInfo": {
        "startCursor": "Y3Vyc29yOnYyOpHOAA==",
        "endCursor": "Y3Vyc29yOnYyOpHOBB==",
        "hasNextPage": false,
        "hasPreviousPage": false
      },
      "edges": [
        {
          "cursor": "Y3Vyc29yOnYyOpHOAA==",
          "node": {
            "id": "pcd_01HQ8K3MNPZ2VWXY4567890ABC",
            "bin": "411111",
            "last4": "4242",
            "status": "ACTIVE",
            "formFactor": "PHYSICAL",
            "expirationDate": "09/27",
            "expirationMonth": "09",
            "expirationYear": "2027",
            "network": "VISA",
            "cardType": 1,
            "cardholder": "JANE SMITH",
            "financialAccounts": [
              {
                "id": "fac_01HQ8K3MNPZ2VWXY1234567DEF",
                "name": "Business Checking"
              }
            ],
            "subProfile": null,
            "department": "Operations"
          }
        },
        {
          "cursor": "Y3Vyc29yOnYyOpHOBB==",
          "node": {
            "id": "pcd_01HQ8K3MNPZ2VWXY9876543XYZ",
            "bin": "411111",
            "last4": "8888",
            "status": "ACTIVE",
            "formFactor": "VIRTUAL",
            "expirationDate": "02/26",
            "expirationMonth": "02",
            "expirationYear": "2026",
            "network": "VISA",
            "cardType": 2,
            "cardholder": "JOHN DOE",
            "financialAccounts": [
              {
                "id": "fac_01HQ8K3MNPZ2VWXY1234567DEF",
                "name": "Business Checking"
              }
            ],
            "subProfile": "sub_01HQ8K3MNPZ2VWXY1111111SUB",
            "department": "Marketing"
          }
        }
      ]
    }
  }
}

Error Codes

Common Mistakes

• Forgetting that card numbers are never returned in full — use bin + last4 to identify a card in UI display; do not attempt to reconstruct the full PAN.
• Ignoring pagination: if pageInfo.hasNextPage is true, you must make additional requests using the endCursor value to retrieve all cards.
• Treating cardType as a string — the schema defines it as an integer enum (0–4); map to labels (Physical, Virtual, Burner) in your client code.
• Assuming subProfile is always present — it is null for cards owned directly by the main account holder and only populated for authorized user (subProfile) cards on business accounts.
• Confusing formFactor (the physical/digital form) with cardType (the product type) — both may be needed to fully categorize a card.

Related Endpoints

• POST /api/paymentCards — Issue a new payment card (physical, virtual, or burner)
• GET /api/paymentCards/{cardId} — Retrieve details for a specific payment card by ID
• PUT /api/paymentCards/{cardId}/status — Update the status of a payment card (freeze, unfreeze, close)
• GET /api/financialAccounts — List financial accounts that can be linked to payment cards
• GET /api/subProfiles — List authorized users (subProfiles) for a business account

Example

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