Get Card Balance Information
The GET /api/transaction/availableToSpend endpoint retrieves the current available balance on a customer's payment card, showing how much money can be spent at any given moment. It returns a breakdown of spend, available funds, limits, refunds, and ATM availability, giving partners and customers accurate real-time data for financial decisions.
Endpoint
GET /api/transaction/availableToSpend
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.
When to use
Use this endpoint whenever you need to display a cardholder's current spendable balance in your application. It is particularly useful before initiating a transaction to confirm sufficient funds are available, and for customer-facing dashboards that show real-time spending limits and available balances.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| paymentCardId | string | Yes | The unique identifier of the payment card whose balance is being queried. |
Response
200 OK
| Field | Type | Description |
|---|---|---|
| spend | integer (int64) | Total amount already spent on the card, in the smallest currency unit (e.g., cents). |
| available | integer (int64) | Current available balance on the card, in the smallest currency unit. |
| availableWithLimit | integer (int64) | null | Available balance after accounting for any spending limit, if applicable. Null if no limit is set. |
| limit | integer (int64) | null | The spending limit configured on the card. Null if no limit is set. |
| hasLimit | boolean | Indicates whether a spending limit is active on the card. |
| refunds | integer (int64) | null | Total pending or applied refund amounts on the card. Null if none. |
| atm | integer (int64) | null | Amount available for ATM cash withdrawals. Null if ATM access is not configured. |
{
"spend": 4500,
"available": 95500,
"availableWithLimit": 45500,
"limit": 50000,
"hasLimit": true,
"refunds": 1000,
"atm": 20000
}Error Codes
| Code | When it happens |
|---|---|
| 400 | paymentCardId is missing or malformed. |
| 401 | Token missing, expired, or invalid. |
| 403 | Insufficient permissions to access balance information for the specified card. |
| 404 | No card found matching the provided paymentCardId. |
| 500 | Internal server error. |
Common Mistakes
- Omitting the
paymentCardIdquery parameter — it is required; the request will fail with a 400 error without it. - Using an outdated Bearer token — tokens expire after 10 minutes; refresh via
POST /api/auth/refreshbefore making the call. - Misinterpreting integer amounts — all monetary values are returned in the smallest currency unit (cents for USD), not as decimal dollar amounts.
- Assuming
availableWithLimitequalsavailable—availableWithLimitonly reflects the portion of available funds within the card's spending limit; checkhasLimitto determine whether this field is meaningful.
Related Endpoints
GET /api/transaction— Retrieve transaction history for a payment card or financial account.GET /api/paymentcard/{paymentCardId}— Retrieve full details for a specific payment card.POST /api/auth/v2— Obtain a Bearer token for authentication.POST /api/auth/refresh— Refresh an existing Bearer token.
Example
curl -X GET "https://api.banking.netevia.dev/api/transaction/availableToSpend?paymentCardId=YOUR_PAYMENT_CARD_ID" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json"