Get list of Payment Cards

API Method: GET /api/paymentCards/v3/paginated

Description: This endpoint retrieves a paginated list of payment cards associated with the authenticated account. It supports filtering and pagination options, including the ability to return only sub-user cards. Each card record includes detailed metadata such as card status, cardholder info, issuing network, linked financial accounts, and visual design elements.

This API is useful for displaying a card management dashboard, auditing issued cards, or filtering cards by type (e.g., sub-user cards only).

Request:

• Method: GET

• Endpoint: https://api.banking.netevia.dev/api/paymentCards/v3/paginated

• Headers:

  • Authorization: Bearer <access_token> (required)
  • Content-Type: application/json

Query Parameters:

Payment card statuses

• ACTIVATION_REQUIRED

  The Payment Card needs activation before it can be used successfully.

• ACTIVE

  The Payment Card is active and ready for use.

• SUSPENDED

  The Payment Card has been suspended and authorizations will fail until the Payment Card is ACTIVE again.

• CLOSED

  The Payment Card has been closed and all future authorizations will fail.

Response:

• Status Code: 200 OK
• Content Type: application/json
• Response Body:

{
  "totalCount": 0,
  "errorMessage": "string",
  "records": [
    {
      "id": "string",
      "bin": "string",
      "last4": "string",
      "status": "string",
      "formFactor": "string",
      "expirationDate": "string",
      "network": "string",
      "cardType": 0,
      "cardholder": "string",
      "subProfile": "string",
      "department": "string",
      "cardName": "string",
      "financialAccounts": [
        {
          "id": "string",
          "name": "string",
          "last4": "string"
        }
      ],
      "isMainCard": true,
      "partnerName": "string",
      "partnerId": 0,
      "cardDesign": {
        "frontSideImageUrlXs": "string",
        "frontSideImageUrlXl": "string",
        "backSideImageUrlXl": "string"
      },
      "cardProfileSetId": "string",
      "features": [
        "Activate"
      ],
      "subProfileId": 0
    }
  ]
}

Response Fields:

• totalCount – Total number of cards available in the system matching the query.

• errorMessage – Any error message (typically empty on success).

• records – Array of card objects with the following fields:

  • id – Unique card identifier
  • bin – Bank Identification Number (first 6 digits, masked)
  • last4 – Last 4 digits of the card
  • status – Card status (e.g., "Active", "Blocked")
  • formFactor – Physical or virtual card type
  • expirationDate – Card expiration date
  • network – Card network (e.g., Visa, Mastercard)
  • cardType – Integer enum indicating type (main, sub, etc.)
  • cardholder – Full name of the cardholder
  • subProfile – Associated sub-user profile name
  • department – Department to which the cardholder belongs
  • cardName – Display name of the card
  • financialAccounts – Linked financial account(s), each with id, name, and last4
  • isMainCard – Boolean indicating if this is the account’s main card
  • partnerName, partnerId – Partner information if applicable
  • cardDesign – URLs for front/back design assets
  • cardProfileSetId – Identifier for the card profile configuration
  • features – List of enabled features (e.g., ["Activate"])
  • subProfileId – Sub-user ID if card belongs to a sub-user

Error Responses:

• 400 Bad Request – Invalid query parameters
• 401 Unauthorized – Access token missing or invalid
• 403 Forbidden – Insufficient permissions
• 500 Internal Server Error – Server-side failure

**Use Case Example:**An administrator wants to view 50 cards, skipping the first 100, and show only those issued to sub-users:

GET /api/paymentCards/v3/paginated?skip=100&count=50&onlySubCards=true