Paynovus Card Management API
The Paynovus Card Management API exposes a curated set of endpoints for card and account operations through the Paynovus CIP platform.
What is this service?
This API gives integrations direct access to card and account operations through the Paynovus CIP platform. It is designed for authenticated integrations that need to verify service health, confirm their account setup, and manage individual accounts and cards.
Where to start
This site has two sections:
- Documentation (you are here) — explains the concepts, the auth model, the tenant scoping rules, the high-level flows, and how errors surface.
- API Reference — every endpoint on its own page with request method, parameters, example bodies, responses, and a Try it widget.
Use the Documentation to understand how things work, and the API Reference when you're ready to call a specific endpoint.
Core capabilities
| Area | What it covers |
|---|---|
| Account identity | Self-introspection of the authenticated partner account (GET /me). |
| Business Accounts (B2B) | Partner-owned tenants, IBAN settings approval, products, audit/history, transactions, cardholder CRUD, card issuance. |
| Individual Accounts | Onboarding and listing of partner-owned individuals, plus their cards and logs. |
| Cards | Partner-wide listing and per-card lifecycle, restrictions, replace/resign, sensitive operations, and limits. |
| Fees & Delivery | Country delivery methods, issuing-fee and delivery-fee checks before card issuance. |
| Webhooks | Outbound notifications when a workflow reaches its final outcome — signature scheme, event catalogue, retries, and your own delivery history. |
Current stage
| Stage | Status | Scope |
|---|---|---|
| 1 | Live | Health check, account identity, account-owned individuals, shared card endpoints. |
| 2 | Live | Business Accounts (B2B) — tenants, IBAN settings, products, logs, transactions, cardholder CRUD, and card issuance under a tenant. Partner-wide balances. |
| 3 | Planned | Additional features around partner-wide aggregation, advanced reporting, and broader account coverage. |
Environments
| Service | URL |
|---|---|
| Docs (staging) | https://docs.card-management-staging.paynovus.com |
| API (staging) | https://api.card-management-staging.paynovus.com |
| Docs (production) | https://docs.card-management.paynovus.com (planned) |
| API (production) | https://api.card-management.paynovus.com (planned) |
All endpoints are mounted under the /api prefix, e.g. /api/partner/me, /api/partner/individual/accounts.
All code examples in this documentation use the staging API base URL (https://api.card-management-staging.paynovus.com). Production credentials must be requested separately.
High-level architecture
Client context CIP-Backend Card platform
┌─────────────────────┐ ┌──────────────────────────────────┐ ┌──────────────┐
│ ES512-signed JWT │ ──── /api ──▶ JWT verification + │ │ │
│ iss = Partner.url │ │ │ partner record lookup │ │ │
│ sub = Partner._id │ │ │ │ ──── proxied ──▶│ card ops │
└─────────────────────┘ │ │ Every request is automatically │ │ client ops │
│ │ scoped to your partner │ │ account ops │
│ │ (404 on anything you don't own)│ └──────────────┘
│ └──────────────────────────────────┘
Tenant scoping summary
Every tenant-scoped route is automatically scoped to your partner. If you pass an id that does not belong to you, the endpoint returns 404 Not Found with no further detail — the response is identical whether the resource does not exist or belongs to another partner, so a caller cannot probe your partner's resources.
| URL path | What it scopes |
|---|---|
/business/accounts/:b2bAccountId/* | One B2B tenant. The :b2bAccountId must resolve to a tenant linked to your partner. |
/business/cardholders/:id/* | One cardholder under one of your tenants. |
/individual/accounts/:id/* | One individual onboarding owned by your partner. |
/cards/:id/* | One card. The card must be issued under an account owned by your partner. |
/cards (no :id), /cardholders, /transactions, /balances* | Partner-wide listings. The controller scopes results to resources owned by your partner. |
Next steps
- Getting Started — Make your first authenticated request
- Authentication — Understand JWT generation and key setup
- Business Accounts (B2B) → — Tenants, IBAN settings, cardholders, card issuance
- Individual Accounts → — Partner-owned end-customer accounts
- Cards → — Card lifecycle, restrictions, sensitive operations, limits
- Errors → — How errors are shaped and how to handle them
- API Reference → — Browse endpoints by area (Partner API, Business Accounts (B2B), Individual Accounts, Cards, Fees & Delivery)