> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xwift.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards

> Issue USD virtual cards for online checkout, one-off payments, and auto-renewal subscriptions.

The card API issues a USD virtual Visa or Mastercard for online checkout. A cardholder pays with the card number, expiration, security code, and billing address. Authenticate with your partner **consumer key** (`x-api-key`). Every endpoint is `POST` with a JSON body under `/card`.

## Online payments and subscriptions

Use the card anywhere a merchant accepts Visa or Mastercard online: stores, invoices, app stores, and ads. Cards created here are virtual. `is_contactless_payment` is `false`, and `is_physical` stays unset unless the issuer reports otherwise.

Auto-renewal is chosen once, on [create card](https://docs.xwift.africa/api-reference/cards/create.md), with `is_non_subscription`:

| `is_non_subscription` | Subscriptions | Typical use |
| - | - | - |
| `true` (default) | Blocked | One-off online payments. A merchant cannot charge the card again on a renewal. |
| `false` | Allowed | Streaming, SaaS, and other plans that store the card and bill it automatically. |

Renewals draw from the card balance. [Fund the card](https://docs.xwift.africa/api-reference/cards/fund.md) before a billing date so the charge can clear, and [freeze](https://docs.xwift.africa/api-reference/cards/freeze.md) it to stop further spend.

## Flow

```mermaid theme={null}
sequenceDiagram
  participant App as Your backend
  participant API as Pretium API

  App->>API: POST /card/create-user
  API-->>App: user_id
  App->>API: POST /card/create
  API-->>App: Card, including card number and security code
  App->>API: POST /card/fund or /card/withdraw
  API-->>App: Updated balance
  App->>API: POST /card/transactions
  API-->>App: Card activity
```

1. [Create a card user](https://docs.xwift.africa/api-reference/cards/create-user.md). Keep the returned `user_id`.
2. [Create a card](https://docs.xwift.africa/api-reference/cards/create.md) for that user. The opening `amount` is loaded onto the card in USD and must be greater than `0.9`.
3. [Read the card](https://docs.xwift.africa/api-reference/cards/get.md), [fund](https://docs.xwift.africa/api-reference/cards/fund.md) it, or [withdraw](https://docs.xwift.africa/api-reference/cards/withdraw.md).
4. [List transactions](https://docs.xwift.africa/api-reference/cards/transactions.md). [Freeze](https://docs.xwift.africa/api-reference/cards/freeze.md) and [unfreeze](https://docs.xwift.africa/api-reference/cards/unfreeze.md) when you need to block spending.

A card user can hold one card. A second create returns `Card user already has a card.`

## Identifying a card

Later calls use the `user_id` from create-user (your cardholder id). They do not take a separate card id, except [terminate](https://docs.xwift.africa/api-reference/cards/terminate.md), which takes `card_id`.

`user_id` is scoped to your partner account. Another partner's id returns `Card user not found.`

## Card object

Create, list, and get return this object. Fund, withdraw, freeze, and unfreeze return the same fields except `card_number` and `security_code`.

| Field | Description |
| - | - |
| `user_id` | Cardholder id from create-user |
| `title` | Display title |
| `color` | `blue`, `black`, `purple`, `orange`, or `yellow` |
| `name` | Name printed for the cardholder |
| `brand` | `visa` or `mastercard` |
| `currency` | `USD` |
| `balance` | Available balance as a two-decimal string |
| `status` | `active`, `frozen`, `terminating`, or `terminated` |
| `mask` | Masked card number |
| `last4` | Last four digits |
| `expiration` | Expiry from the issuer |
| `is_non_subscription` | `true` when auto-renewal is blocked, `false` when merchants may bill the card again |
| `is_contactless_payment` | `false` on cards created through this API |
| `is_physical` | `true`, `false`, or `null`. Cards created here are virtual |
| `billing_address` | `address`, `city`, `state`, `zip_code`, `country`, or `null` |
| `last_used_on` | Last use time, or `null` |
| `created_at`, `updated_at` | Timestamps |
| `card_number` | Full card number. Present on create, list, and get |
| `security_code` | Security code. Present on create, list, and get |
| `total_card_spend` | Present on [get card](https://docs.xwift.africa/api-reference/cards/get.md) only |

> [!NOTE]
>
> `POST /card/create`, `POST /card/all`, and `POST /card/get-card` return the full card number and security code. Store them as cardholder secrets. List-users nests cards without those fields.

## Card user object

[Create](https://docs.xwift.africa/api-reference/cards/create-user.md) and [edit](https://docs.xwift.africa/api-reference/cards/edit-user.md) return:

| Field | Description |
| - | - |
| `user_id` | Id to send on card calls |
| `email` | Cardholder email |
| `name` | `first_name` and `last_name` joined |

[List users](https://docs.xwift.africa/api-reference/cards/users.md) adds `phone`, `country`, `state`, `city`, `address`, `zip_code`, and a `cards` array. ID type and ID number are not returned.

## Statuses

| Status | Meaning |
| - | - |
| `active` | Card can be funded, withdrawn, and spent |
| `frozen` | Spending is blocked until you unfreeze |
| `terminating` | Termination is in progress |
| `terminated` | Card is closed |

Get, fund, withdraw, freeze, and unfreeze only resolve a card that is not `terminated` or `terminating`. Transaction history still resolves a closed card.

## Amounts

Cards are issued in **USD**.

| Call | Rule |
| - | - |
| Create | `amount` must be greater than `0.9` |
| Withdraw | `amount` must be greater than `0.9` |
| Fund | `amount` is a required number |

A withdrawal the card cannot cover returns `Card has insufficient balance.`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.