Get Payment card details by ID and additional parameters

get

https://api.banking.netevia.dev/api/paymentCards/findPaymentCard

Get Payment Card Details by ID and Additional Parameters

This endpoint retrieves detailed information about a specific payment card, including credit limits, available balance, burner card constraints, cardholder address, and paginated transaction activity. By providing the card's identifier along with optional date range and pagination parameters, partners can access essential card data to support card management, usage review, and limit compliance workflows.

Endpoint

GET /api/paymentCards/findPaymentCard

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 inspect the current state of a payment card — for example, to display card details in a customer dashboard, verify spending limits before authorizing a transaction, or retrieve transaction history scoped to a specific card. It supports all three card types: Physical, Virtual, and Burner. For Burner cards, the response includes additional spending cap and transaction count fields from the burnerCardInfo object.

Query Parameters

Parameter	Type	Required	Description
`paymentCardId`	string	Yes	Unique identifier of the payment card to retrieve
`from`	string (date-time)	No	Start of the date range for transaction activity (ISO 8601 format)
`to`	string (date-time)	No	End of the date range for transaction activity (ISO 8601 format)
`count`	integer (int32)	No	Number of transaction records to return per page. Default: `20`
`afterCursor`	string	No	Pagination cursor; pass the cursor from the previous response to retrieve the next page of results

Response

200 OK

Field	Type	Description
`card`	object	Payment card details object (card number metadata, status, etc.)
`cardType`	integer	Card type identifier: `1` = Physical, `2` = Virtual, `3` = Burner
`burnerCardInfo`	object	Present for Burner cards; contains spending cap and transaction count limits (see sub-fields below)
`burnerCardInfo.maxTotalSpending`	integer (int64)	Maximum cumulative spending allowed on this Burner card (in cents)
`burnerCardInfo.maxTransactionsCount`	integer (int32)	Maximum number of transactions allowed on this Burner card
`burnerCardInfo.totalSpending`	integer (int64)	Total amount spent to date on this Burner card (in cents)
`burnerCardInfo.totalTransactionsCount`	integer (int32)	Total number of transactions processed on this Burner card
`burnerCardInfo.availableSpending`	integer (int64)	Remaining spending balance on this Burner card (in cents)
`burnerCardInfo.availableTransactionsCount`	integer (int32)	Remaining number of transactions allowed on this Burner card
`burnerCardInfo.burnerExpirationDate`	string (date-time)	Expiration date/time of this Burner card (active until end of the following month from issuance)
`address`	string	Street address on file for the cardholder
`city`	string	City on file for the cardholder
`postalCode`	string	Postal/ZIP code on file for the cardholder
`state`	string	State on file for the cardholder
`dba`	string	Doing Business As name associated with the card (business customers)
`cardHolder`	string	Full name of the cardholder
`reissueAvailable`	boolean	Whether a card reissue is currently available for this card
`activity`	object	Paginated transaction activity associated with this card (see sub-fields below)
`activity.data`	array	List of financial activity records for this card
`activity.data[].id`	string	Unique identifier of the activity record
`activity.data[].financialAccountId`	string	ID of the financial account linked to this card
`activity.data[].date`	string (date-time)	Date and time of the transaction
`activity.data[].sortDate`	string (date-time)	Date used for sorting activity records
`activity.data[].balance`	object	Account balance after this transaction (`value` in cents, `currencyCode`)
`activity.data[].status`	string	Transaction status: `OTHER`, `PENDING`, `COMPLETED`, or `FAILED`
`activity.data[].riskHold`	boolean	Whether a risk hold is applied to this transaction
`activity.data[].settlementDate`	string (date-time)	Settlement date for the transaction, if available
`activity.data[].purpose`	string	Purpose description of the transaction
`activity.data[].statusReasonCode`	string	Reason code for the current transaction status
`activity.data[].amount`	object	Transaction amount (`value` in cents, `currencyCode`, `symbol`)
`activity.data[].clearAmount`	object	Cleared/settled amount (`value` in cents, `currencyCode`, `symbol`)
`activity.data[].pendingAmount`	object	Pending amount (`value` in cents, `currencyCode`)
`activity.data[].name`	string	Descriptive name or label for the transaction
`activity.data[].last4`	object	Last 4 digits context: `type` (`CARD` or `ACCOUNT`), `value`
`activity.data[].type`	string	Transaction type label (e.g., card purchase, transfer)
`activity.data[].authorizedUser`	string	Name of the authorized user (subProfile) who initiated the transaction, if applicable
`activity.data[].merchantCategory`	string	Merchant category label for card transactions
`activity.data[].rewardPoints`	integer (int64)	Reward points earned or redeemed in this transaction
`activity.filter`	object	Active filter criteria applied to the activity results
`activity.paginationResponse`	object	Pagination metadata
`activity.paginationResponse.totalItems`	integer (int32)	Total number of activity records matching the query

{
  "card": {
    "id": "card_abc123xyz",
    "last4": "4321",
    "bin": "411111",
    "status": "ACTIVE"
  },
  "cardType": 1,
  "burnerCardInfo": null,
  "address": "123 Main St",
  "city": "Miami",
  "postalCode": "33101",
  "state": "FL",
  "dba": "Acme Corp",
  "cardHolder": "Jane Doe",
  "reissueAvailable": true,
  "activity": {
    "data": [
      {
        "id": "act_001abc",
        "financialAccountId": "fa_xyz789",
        "date": "2025-06-01T14:23:00Z",
        "sortDate": "2025-06-01T14:23:00Z",
        "balance": {
          "value": 150000,
          "currencyCode": "USD"
        },
        "status": "COMPLETED",
        "riskHold": false,
        "settlementDate": "2025-06-02T00:00:00Z",
        "purpose": "Card Purchase",
        "statusReasonCode": null,
        "amount": {
          "value": 5000,
          "currencyCode": "USD",
          "symbol": "$"
        },
        "clearAmount": {
          "value": 5000,
          "currencyCode": "USD",
          "symbol": "$"
        },
        "pendingAmount": {
          "value": 0,
          "currencyCode": "USD"
        },
        "name": "Coffee Shop Purchase",
        "last4": {
          "type": "CARD",
          "value": "4321"
        },
        "type": "PURCHASE",
        "authorizedUser": null,
        "merchantCategory": "Food & Beverage",
        "rewardPoints": 50,
        "activityInfo": null,
        "financialEvent": null
      }
    ],
    "filter": {
      "all": { "displayName": "All", "value": true, "items": [] },
      "deposit": { "displayName": "Deposits", "value": false, "items": [] },
      "withdraw": { "displayName": "Withdrawals", "value": false, "items": [] },
      "transfers": { "displayName": "Transfers", "value": false, "items": [] },
      "pos": { "displayName": "POS", "value": true, "items": [] },
      "transactionStatus": { "displayName": "Status", "value": false, "items": [] },
      "others": { "displayName": "Others", "value": false, "items": [] }
    },
    "paginationResponse": {
      "totalItems": 1
    }
  }
}

Error Codes

Code	When it happens
400	`paymentCardId` is missing, malformed, or the date range values are not valid ISO 8601 date-time strings
401	Token missing, expired, or invalid
403	Insufficient permissions — the authenticated partner does not have access to the specified card
404	No payment card found matching the provided `paymentCardId`
500	Internal server error

Common Mistakes

Omitting paymentCardId — this is the only required parameter; the request will return a 400 error without it.
Passing the card number instead of the card ID for paymentCardId — the field expects an internal Netevia card identifier (e.g., card_abc123xyz), not the PAN.
Not using pagination: if a card has many transactions, the default count is 20. Use afterCursor from the previous response to page through all results rather than assuming the first response is complete.
Providing from or to in a non-ISO 8601 date-time format; always use UTC timestamps in the format YYYY-MM-DDTHH:MM:SSZ.
For Burner cards, burnerCardInfo will be populated; for Physical and Virtual cards this field will be null — do not assume it is always present.

Related Endpoints

GET /api/paymentCards — List all payment cards for a customer profile
POST /api/paymentCards — Issue a new payment card (Physical, Virtual, or Burner)
PUT /api/paymentCards/{paymentCardId} — Update card settings or limits
POST /api/paymentCards/reissue — Reissue an existing payment card

Example

curl -X GET "https://api.banking.netevia.dev/api/paymentCards/findPaymentCard?paymentCardId=card_abc123xyz&from=2025-06-01T00%3A00%3A00Z&to=2025-06-30T23%3A59%3A59Z&count=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Response

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

text/plain

application/json

text/json