Get Spending Report for Card

The spending report endpoint generates a detailed breakdown of transactions for a specific payment card within a defined date range. Results are organized by merchant category, each showing the total amount spent and its percentage of overall card spending. This makes it straightforward to analyze cardholder behavior, enforce budgets, or surface insights within a partner application.

Endpoint

POST /api/paymentCards/spendingReport

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 present a cardholder or account manager with a summary of how a payment card has been used over a period of time. It is well-suited for expense dashboards, monthly statements, and spend-control features where category-level aggregation (e.g., dining, travel, groceries) is more actionable than a raw transaction list. Both physical and virtual card IDs are accepted.

Request Body

{
  "paymentCardId": "card_abc123xyz",
  "dateFrom": "2025-01-01T00:00:00Z",
  "dateTo": "2025-01-31T23:59:59Z"
}

Response

200 OK

{
  "categories": [
    {
      "category": "Dining",
      "amount": 15400,
      "percentage": 30.8
    },
    {
      "category": "Travel",
      "amount": 22000,
      "percentage": 44.0
    },
    {
      "category": "Groceries",
      "amount": 12600,
      "percentage": 25.2
    }
  ],
  "total": 50000
}

Error Codes

Common Mistakes

• Providing dateFrom after dateTo — the date range must be chronologically ordered with dateFrom earlier than dateTo.
• Sending date strings without timezone information (e.g., 2025-01-01T00:00:00 with no Z or offset) — always include a timezone designator to avoid ambiguous period boundaries.
• Using a card display number instead of the internal paymentCardId — the field requires the platform-assigned card ID, not the 16-digit PAN.
• Expecting transaction-level detail in this response — this endpoint returns category aggregates only; use the transaction history endpoint for individual transaction records.

Related Endpoints

• POST /api/paymentCards — Create a new payment card (physical, virtual, or burner)
• GET /api/paymentCards/{paymentCardId} — Retrieve details for a specific payment card
• POST /api/paymentCards/transactions — Retrieve individual transaction records for a card

Example

curl -X POST https://api.banking.netevia.dev/api/paymentCards/spendingReport \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentCardId": "card_abc123xyz",
    "dateFrom": "2025-01-01T00:00:00Z",
    "dateTo": "2025-01-31T23:59:59Z"
  }'