API References

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_cards for a UI-friendly list. last_4 is masked ("****") while a card is INACTIVE and visible once ACTIVE.
  • Set PIN (reference): svc.card.{partner}.set_pin with a 4-digit pin.
  • Update status (reference): svc.card.{partner}.update_status with status: "ACTIVE" or "FROZEN".
  • View transactions (reference): card transactions are returned by the account's transaction list, svc.account.{partner}.list. Each one carries a metadata block with the card_id, merchant and MCC. The endpoint has no card filter, so to show one card's activity, filter on metadata.card_id in 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.

See List Card Requests and Respond to Card Request.

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_cards for a UI-friendly list. last_4 is masked ("****") while a card is INACTIVE and visible once ACTIVE.
  • Set PIN (reference): svc.card.{partner}.set_pin with a 4-digit pin.
  • Update status (reference): svc.card.{partner}.update_status with status: "ACTIVE" or "FROZEN".
  • View transactions (reference): card transactions are returned by the account's transaction list, svc.account.{partner}.list. Each one carries a metadata block with the card_id, merchant and MCC. The endpoint has no card filter, so to show one card's activity, filter on metadata.card_id in 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

CardFeatures object
{
  "domestic": true,
  "international": false,
  "e_commerce": true,
  "atm": true,
  "pos": true,
  "contactless": true
}
FieldTypeDescription
domesticbooleanDomestic transactions. Always forced to true, the request payload is ignored.
internationalbooleanInternational transactions. Always forced to false, the request payload is ignored.
e_commercebooleanOnline and e-commerce purchases. Honors the request payload (default true if omitted).
atmbooleanATM withdrawals. Honors the request payload (default true if omitted).
posbooleanPoint-of-sale transactions. Honors the request payload (default true if omitted).
contactlessbooleanContactless 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.

CardLimits object
{
  "transaction_enabled": true,
  "transaction": 100000,
  "daily_enabled": true,
  "daily": 100000,
  "monthly_enabled": false,
  "monthly": 0,
  "yearly_enabled": false,
  "yearly": 0
}
FieldTypeDescription
transaction_enabledbooleanWhether the per-transaction limit is enforced.
transactionnumberMaximum amount per transaction, e.g. 100000 = $1,000.00.
daily_enabledbooleanWhether the daily limit is enforced.
dailynumberMaximum spend per day.
monthly_enabledbooleanWhether the monthly limit is enforced.
monthlynumberMaximum spend per month.
yearly_enabledbooleanWhether the yearly limit is enforced.
yearlynumberMaximum 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 *_enabled flag is false. For example daily_enabled: false with daily: 75000 still counts as a daily limit, and combined with monthly_enabled: true it triggers the only-one-periodic-limit rejection

Request Card

Requests a new card for a user.

Subject: svc.card.<partner_id>.request

Request

Request
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account the card spends from
  "user_id": "40ec785e-d915-49de-9053-4630042d8182",     // Required: the cardholder
  "name": "Jane Doe",                                     // Required: name on the card
  "type": 1,                                              // Required: 1 = Virtual, 2 = Physical
  "use_type": 2,                                          // Required: must be 2 (multi-use)
  "features": {                                           // Required: see Card features
    "domestic": true,
    "international": false,
    "e_commerce": true,
    "atm": true,
    "pos": true,
    "contactless": true
  },
  "limits": {                                             // Required: see Card limits
    "transaction_enabled": true,
    "transaction": 20000,
    "daily_enabled": true,
    "daily": 20000,
    "monthly_enabled": false,
    "monthly": 0,
    "yearly_enabled": false,
    "yearly": 0
  },
  "extras": {                                             // Optional: accepted but not enforced yet
    "auto_lock": "2026-12-31T23:59:59Z"
  }
}
FieldTypeRequiredDescription
account_idstringrequiredUUID of the account the card spends from
user_idstringrequiredUUID of the cardholder
namestringrequiredName to appear on the card
typenumberrequiredCard type: 1 = Virtual, 2 = Physical
use_typenumberrequiredCard use type. Must be 2 (multi-use); 1 (single-use) is rejected
featuresobjectrequiredFeature toggles. See Card features
limitsobjectrequiredSpending 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
extrasobjectoptionalauto_lock is accepted and stored, but not enforced yet

Response

Response
{
  "id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5"
}
FieldTypeDescription
idstringUUID 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

ListOrganisationCardRequestsRequest
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account ID
  "user_ids": ["40ec785e-d915-49de-9053-4630042d8182"]   // Optional: filter by users
}
FieldTypeRequiredDescription
account_idstringrequiredAccount ID
user_idsarrayoptionalFilter results to specific user IDs

Response

ListOrganisationCardRequestsResponse
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "requests": [
    {
      "id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5",
      "name": "John Doe",
      "type": 1,
      "use_type": 2,
      "created_at": "2023-11-15T10:30:45Z",
      "requested_by": "40ec785e-d915-49de-9053-4630042d8182",
      "assigned_to": "40ec785e-d915-49de-9053-4630042d8182",
      "features": { "domestic": true, "international": false, "e_commerce": true, "atm": true, "pos": true, "contactless": true },
      "limits": { "transaction_enabled": true, "transaction": 20000, "daily_enabled": true, "daily": 20000, "monthly_enabled": false, "monthly": 0, "yearly_enabled": false, "yearly": 0 },
      "extras": {},
      "status": "PENDING"
    }
  ]
}

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

RespondToCardRequestRequest
{
  "entity_id": "7632a09c-9408-4cf0-b8dd-cada3f089240",  // Required: entity ID
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account ID
  "request_id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5",  // Required: card request ID
  "approved": true                                        // Optional: omit or false to record a rejection
}
FieldTypeRequiredDescription
entity_idstringrequiredEntity ID
account_idstringrequiredAccount ID
request_idstringrequiredCard request ID
approvedbooleanoptionalSet to true to approve; omit or set to false to record a rejection

Response

RespondToCardRequestResponse
{}

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

ListOrganisationCardsRequest
{
  "entity_id": "7632a09c-9408-4cf0-b8dd-cada3f089240",   // Required: entity ID
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account ID
  "user_ids": ["40ec785e-d915-49de-9053-4630042d8182"]    // Optional: filter by users
}
FieldTypeRequiredDescription
entity_idstringrequiredEntity ID
account_idstringrequiredAccount ID
user_idsarrayoptionalFilter results to specific user IDs

Response

ListOrganisationCardsResponse
{
  "id": "7632a09c-9408-4cf0-b8dd-cada3f089240",
  "cards": [
    {
      "id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5",
      "name": "John Doe",
      "type": 1,
      "use_type": 2,
      "last_4": "1234",
      "date_created": "2023-11-15T10:30:45Z",
      "user_id": "40ec785e-d915-49de-9053-4630042d8182",
      "org_id": "7632a09c-9408-4cf0-b8dd-cada3f089240",
      "features": { "domestic": true, "international": false, "e_commerce": true, "atm": true, "pos": true, "contactless": true },
      "limits": { "transaction_enabled": true, "transaction": 20000, "daily_enabled": true, "daily": 20000, "monthly_enabled": false, "monthly": 0, "yearly_enabled": false, "yearly": 0 },
      "extras": {},
      "status": "ACTIVE"
    }
  ]
}

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

GetCardDetailsRequest
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account ID
  "id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5"            // Required: card ID
}
FieldTypeRequiredDescription
account_idstringrequiredAccount ID
idstringrequiredCard ID

Response

GetCardDetailsResponse
{
  "card_number": "4111111111111234",  // Full card number
  "expiry_date": "1225",              // Card expiry date (MMYY)
  "cvv": "123"                        // Card verification value
}
FieldTypeDescription
card_numberstringFull card number
expiry_datestringCard expiry date (MMYY)
cvvstringCard 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

UpdateCardStatusRequest
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account ID
  "id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5",           // Required: card ID
  "status": "FROZEN"                                       // New status: ACTIVE or FROZEN
}
FieldTypeRequiredDescription
account_idstringrequiredAccount ID
idstringrequiredCard ID
statusstringrequiredNew status: ACTIVE or FROZEN

Response

UpdateCardStatusResponse
{}

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

ActivateCardRequest
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account ID
  "id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5",           // Optional: card ID (can activate by last_4 only)
  "last_4": "1234"                                         // Required: last 4 digits for verification
}
FieldTypeRequiredDescription
account_idstringrequiredAccount ID
idstringoptionalCard ID (can activate by last_4 only)
last_4stringrequiredLast 4 digits of the card, used for verification

Response

ActivateCardResponse
{}

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

SetPINRequest
{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",  // Required: account ID
  "id": "7aa53a6d-5869-c814-5cee-2af0f5d92aa5",           // Required: card ID
  "pin": "1234"                                            // New 4-digit PIN
}
FieldTypeRequiredDescription
account_idstringrequiredAccount ID
idstringrequiredCard ID
pinstringrequiredNew 4-digit PIN

Response

SetPINResponse
{}

Security warning

PINs are encrypted in transit and storage. Handle this data with care in your application.