Get List of Payment Cards V2

The GET /api/paymentCards/v2 endpoint returns a list of all payment cards linked to the authenticated customer's account. Each card entry includes masked card number details, expiration information, card type, current status, and associated financial accounts. This endpoint supports both business and personal customer profiles.

Endpoint

GET /api/paymentCards/v2

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 full card portfolio in a dashboard or card management screen. It is the primary way to retrieve card identifiers (id) needed for subsequent card operations such as freezing, updating, or retrieving sensitive card details. It is also useful for checking card status before authorizing a transaction.

Response

200 OK

The response is a cursor-based paginated structure. The top-level object contains an accountholder node with profile information and a nested paymentCards connection holding the list of cards.

Top-level response (bank.client.graph.edge_accountholder)

Account holder node (bankingapi.models.paymentcards.accountholder)

Payment cards connection (bank.client.graph.connection_paymentcardresponse)

Payment card node (bankingapi.models.paymentcards.paymentcardresponse)

{
  "cursor": "Y3Vyc29yMQ==",
  "node": {
    "typename": "PersonAccountHolder",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith",
      "title": null,
      "suffix": null,
      "middleName": null
    },
    "businessProfile": {
      "name": {
        "legalBusinessName": "Acme Corp LLC",
        "doingBusinessAsName": "Acme Corp"
      }
    },
    "primaryAuthorizedPerson": {
      "name": {
        "givenName": "Jane",
        "familyName": "Smith",
        "title": null,
        "suffix": null,
        "middleName": null
      }
    },
    "paymentCards": {
      "pageInfo": {
        "startCursor": "Y2FyZEN1cnNvcjE=",
        "endCursor": "Y2FyZEN1cnNvcjM=",
        "hasNextPage": false,
        "hasPreviousPage": false
      },
      "edges": [
        {
          "cursor": "Y2FyZEN1cnNvcjE=",
          "node": {
            "id": "card_01HXYZ1234ABCDEF567890",
            "bin": "411111",
            "last4": "4242",
            "status": "ACTIVE",
            "formFactor": "VIRTUAL",
            "expirationDate": "09/2027",
            "expirationMonth": "09",
            "expirationYear": "2027",
            "network": "VISA",
            "cardType": 2,
            "cardholder": "JANE SMITH",
            "financialAccounts": [
              {
                "id": "fa_01HXYZ9876UVWXYZ012345",
                "name": "Business Checking"
              }
            ],
            "subProfile": null,
            "department": "Operations"
          }
        },
        {
          "cursor": "Y2FyZEN1cnNvcjI=",
          "node": {
            "id": "card_01HXYZ5678GHIJKL901234",
            "bin": "411111",
            "last4": "8888",
            "status": "ACTIVE",
            "formFactor": "PHYSICAL",
            "expirationDate": "03/2026",
            "expirationMonth": "03",
            "expirationYear": "2026",
            "network": "VISA",
            "cardType": 1,
            "cardholder": "JANE SMITH",
            "financialAccounts": [
              {
                "id": "fa_01HXYZ9876UVWXYZ012345",
                "name": "Business Checking"
              }
            ],
            "subProfile": null,
            "department": null
          }
        }
      ]
    }
  }
}

Error Codes

Common Mistakes

• Forgetting to paginate: if pageInfo.hasNextPage is true, additional cards exist beyond the current page. Use pageInfo.endCursor as a cursor parameter in follow-up requests to retrieve them.
• Treating cardType as a string: the cardType field is an integer enum (0–4), not a string label. Map values in your client code: 1=Physical, 2=Virtual, 3=Burner.
• Assuming all fields are populated: most fields are nullable. Always perform null checks before displaying values such as subProfile, department, or businessProfile.
• Using bin + last4 as a card identifier: use the id field exclusively when referencing a card in other API calls.
• Confusing formFactor with cardType: formFactor is a descriptive string label while cardType is the authoritative numeric enum used in filtering and card management operations.

Related Endpoints

• POST /api/paymentCards/v2 — Create a new payment card (Physical, Virtual, or Burner)
• GET /api/paymentCards/v2/{cardId} — Retrieve details for a single payment card by ID
• PUT /api/paymentCards/v2/{cardId} — Update payment card settings or status
• POST /api/paymentCards/v2/{cardId}/freeze — Freeze an active payment card
• POST /api/paymentCards/v2/{cardId}/unfreeze — Unfreeze a suspended payment card

Example

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