Cards Service
API reference for managing payment cards
Introduction
The Cards API lets you manage payment cards for your entity: request new cards, view card details, activate cards, set PINs, and manage card status and limits.
Virtual card guide
Issue, approve, reveal details, and manage a virtual card with three core calls. This covers the virtual-only flow, with cardholder access.
Request the card
Create a hosted session with the request_card flow, passing the account, user, card type, and the features and limits to apply. use_type must be 2 (multi-use); single-use cards aren't available. The cardholder reviews and submits the request in the SAVA-hosted page. The session's expected_result.id becomes the card's card_id once the request is approved.
See Request Card Session.
Track approval
Call svc.card.{partner}.list_requests with the account_id (optionally scoped to user_ids) and watch for status: "APPROVED" on the request with the matching id. Virtual cards are auto-approved, so this is typically immediate.
See List Card Requests.
Get the card details
Call svc.card.{partner}.get_details with the account_id and the id from step one. You'll receive the card number, expiry date, and CVV. Virtual cards are active by default, no separate activation step needed.
See Get Card Details.
Security
get_details returns sensitive card information (PAN, expiry, CVV). Handle it in compliance with PCI DSS, and avoid logging or persisting the raw response. To display card details to the end user without the plaintext ever touching your code, use the Card Reveal flow instead.
Manage the card
Once a virtual card exists, these calls handle it day to day:
- List cards (reference):
svc.card.{partner}.list_cardsfor a UI-friendly list.last_4is masked ("****") while a card isINACTIVEand visible onceACTIVE. - Set PIN (reference):
svc.card.{partner}.set_pinwith a 4-digitpin. - Update status (reference):
svc.card.{partner}.update_statuswithstatus: "ACTIVE"or"FROZEN". - View transactions (reference): card transactions are returned by the account's transaction list,
svc.account.{partner}.list. Each one carries ametadatablock with thecard_id, merchant and MCC. The endpoint has no card filter, so to show one card's activity, filter onmetadata.card_idin your own code. For how payments, reversals and refunds arrive over time, see the Card Transaction Lifecycle guide.
Physical card guide
Physical cards follow the same request and approval flow, plus one extra step once the card arrives: activation.
Request the card
Create a request_card hosted session the same way as a virtual card, but with type: 2 (Physical). The session's expected_result.id becomes the card's card_id once the request is approved.
See Request Card Session.
Track approval
Call svc.card.{partner}.list_requests and watch for status: "APPROVED". Physical cards typically require Owner or Accountant approval before manufacturing and shipping begin.
Activate the card
Once the cardholder has the physical card in hand, call svc.card.{partner}.activate_card with the account_id and the last 4 digits printed on the card for verification. The card can't be used for transactions until this step completes.
See Activate Card.
Manage the card
Once a physical card is activated, these calls handle it day to day, the same ones used for virtual cards:
- List cards (reference):
svc.card.{partner}.list_cardsfor a UI-friendly list.last_4is masked ("****") while a card isINACTIVEand visible onceACTIVE. - Set PIN (reference):
svc.card.{partner}.set_pinwith a 4-digitpin. - Update status (reference):
svc.card.{partner}.update_statuswithstatus: "ACTIVE"or"FROZEN". - View transactions (reference): card transactions are returned by the account's transaction list,
svc.account.{partner}.list. Each one carries ametadatablock with thecard_id, merchant and MCC. The endpoint has no card filter, so to show one card's activity, filter onmetadata.card_idin your own code. For how payments, reversals and refunds arrive over time, see the Card Transaction Lifecycle guide.
Card features and limits
Every card request includes a features object (which transaction types are allowed) and a limits object (spending caps). Both are validated on request; other endpoints mostly pass them through.
Card features
| Field | Type | Description |
|---|---|---|
domestic | boolean | Domestic transactions. Always forced to true, the request payload is ignored. |
international | boolean | International transactions. Always forced to false, the request payload is ignored. |
e_commerce | boolean | Online and e-commerce purchases. Honors the request payload (default true if omitted). |
atm | boolean | ATM withdrawals. Honors the request payload (default true if omitted). |
pos | boolean | Point-of-sale transactions. Honors the request payload (default true if omitted). |
contactless | boolean | Contactless payments. Honors the request payload (default true if omitted). |
International is staged
The international toggle exists in the API but full enablement may still be staged on the backend; treat it as reserved rather than functional for now.
Card limits
All amounts are in minor units (e.g. cents) of the account currency.
| Field | Type | Description |
|---|---|---|
transaction_enabled | boolean | Whether the per-transaction limit is enforced. |
transaction | number | Maximum amount per transaction, e.g. 100000 = $1,000.00. |
daily_enabled | boolean | Whether the daily limit is enforced. |
daily | number | Maximum spend per day. |
monthly_enabled | boolean | Whether the monthly limit is enforced. |
monthly | number | Maximum spend per month. |
yearly_enabled | boolean | Whether the yearly limit is enforced. |
yearly | number | Maximum spend per year. |
Validation rules
- At least one limit amount must be greater than 0
- Provide at most one periodic limit (daily, monthly, or yearly). Requests with more than one periodic limit are rejected
- A single transaction limit can be combined with the one periodic limit
- Send inactive limits as 0 or omit them. Any periodic limit with an amount greater than 0 is treated as enabled, even if its
*_enabledflag is false. For exampledaily_enabled: falsewithdaily: 75000still counts as a daily limit, and combined withmonthly_enabled: trueit triggers the only-one-periodic-limit rejection
Request Card
Requests a new card for a user.
Subject: svc.card.<partner_id>.request
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | UUID of the account the card spends from |
user_id | string | required | UUID of the cardholder |
name | string | required | Name to appear on the card |
type | number | required | Card type: 1 = Virtual, 2 = Physical |
use_type | number | required | Card use type. Must be 2 (multi-use); 1 (single-use) is rejected |
features | object | required | Feature toggles. See Card features |
limits | object | required | Spending limits: at least one non-zero amount, at most one periodic limit (daily, monthly or yearly), optionally with a transaction limit. Send unused limits as 0. See Card limits |
extras | object | optional | auto_lock is accepted and stored, but not enforced yet |
Response
| Field | Type | Description |
|---|---|---|
id | string | UUID of the card request. It becomes the card's card_id once the request is approved |
Approval
Virtual cards are auto-approved. Physical cards may need Owner or Accountant approval before the id can be used as a card_id, and the cardholder needs an address on file. Track the request with List Card Requests.
Iframe equivalent: Request Card Session
The same card request can be made through a hosted session, where the cardholder reviews, gives consent and submits inside a SAVA-owned page that you embed in an iframe (or WebView). The request body is the same as above, and the response is a hosted_url and iframe_url instead of the card request id. See Request Card Session.
List Card Requests
List card requests for an account. Members see their own; owners and accountants can see all.
Subject: svc.card.{partner_id}.list_requests
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Account ID |
user_ids | array | optional | Filter results to specific user IDs |
Response
Visibility is enforced by upstream auth and policy; the service returns results scoped to the account and optional user_ids.
Respond to Card Request
Approve or reject a card request. Typically restricted to Owner and Accountant roles, enforce this via your own access control. Virtual cards are auto-approved and don't need this call.
Subject: svc.card.{partner_id}.respond_to_request
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | required | Entity ID |
account_id | string | required | Account ID |
request_id | string | required | Card request ID |
approved | boolean | optional | Set to true to approve; omit or set to false to record a rejection |
Response
Authorization
Ensure appropriate role checks (Owner or Accountant) are enforced in your integration before calling this.
List Cards
List cards for an entity or account. Members see their own; owners and accountants can see all.
Subject: svc.card.{partner_id}.list_cards
Request
| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | required | Entity ID |
account_id | string | required | Account ID |
user_ids | array | optional | Filter results to specific user IDs |
Response
Visibility is enforced by upstream auth and policy; the service filters by the request parameters.
Masking behavior
When a card is INACTIVE, last_4 may be masked ("****"). Virtual cards are ACTIVE on creation.
Get Card Details
Retrieve sensitive card details, including the full card number, expiry date, and CVV. Use this sparingly and only when necessary.
Replaced by Card Reveal
This endpoint is replaced by the Basis Theory Card Reveal flow, which displays card details to the end user through secure elements without the plaintext ever reaching your servers or application code. Use card reveal for new integrations.
Subject: svc.card.{partner_id}.get_details
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Account ID |
id | string | required | Card ID |
Response
| Field | Type | Description |
|---|---|---|
card_number | string | Full card number |
expiry_date | string | Card expiry date (MMYY) |
cvv | string | Card verification value |
Security warning
This endpoint returns sensitive card information. Handle it securely and in compliance with PCI DSS requirements.
Update Card Status
Change a card's status to ACTIVE or FROZEN. Freezing a card prevents transactions.
Subject: svc.card.{partner_id}.update_status
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Account ID |
id | string | required | Card ID |
status | string | required | New status: ACTIVE or FROZEN |
Response
Activate Card
Activate a physical card after the user has received it. Required before the card can be used for transactions.
Subject: svc.card.{partner_id}.activate_card
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Account ID |
id | string | optional | Card ID (can activate by last_4 only) |
last_4 | string | required | Last 4 digits of the card, used for verification |
Response
Set PIN
Set or change the PIN for a card. The PIN must be exactly 4 digits. A cooldown applies between PIN set requests.
Subject: svc.card.{partner_id}.set_pin
Request
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Account ID |
id | string | required | Card ID |
pin | string | required | New 4-digit PIN |
Response
Security warning
PINs are encrypted in transit and storage. Handle this data with care in your application.