> ## 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.

# Create card

> Issue one USD virtual card for online checkout and load the opening amount.

Issues one virtual card in **USD** for online checkout and loads `amount` onto it. Each cardholder can have one card.

`is_non_subscription` controls auto-renewal. Leave it `true` (the default) to block recurring charges. Set it to `false` when a merchant should be able to store the card and bill it again, such as a streaming or SaaS plan. Contactless is off for cards created here.

The response includes `card_number` and `security_code`. See the [card object](https://docs.xwift.africa/guides/cards.md#card-object).

**user\_id** `string` *required*

Cardholder id returned by [create card user](https://docs.xwift.africa/api-reference/cards/create-user.md).

**amount** `number` *required*

Opening balance in USD. Must be greater than `0.9`.

**brand** `string` *required*

`visa` or `mastercard`.

**title** `string`

Display title. Defaults to the cardholder's full name.

**color** `string`

`blue`, `black`, `purple`, `orange`, or `yellow`. Defaults to `black`.

**is\_non\_subscription** `boolean`

`true` (default) blocks merchant auto-renewal. `false` allows a merchant to charge the card again when a subscription renews.

### Errors

| Message | When |
| - | - |
| First validator error | `user_id` is missing, `amount` is not greater than `0.9`, or `brand` / `color` is invalid |
| `Card user not found.` | `user_id` is unknown, or the cardholder was not provisioned |
| `Card user already has a card.` | This cardholder already has a card |
| `An unexpected error occurred. Please try again.` | The card could not be issued |

```bash theme={null}
curl -X POST "{{base_url}}/card/create" \
  -H "x-api-key: YOUR_CONSUMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "amount": 25,
    "brand": "visa",
    "title": "Ada Lovelace",
    "color": "black",
    "is_non_subscription": true
  }'
```

```json theme={null}
{
  "code": 200,
  "message": "Card created.",
  "data": {
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "title": "Ada Lovelace",
    "color": "black",
    "name": "ADA LOVELACE",
    "brand": "visa",
    "currency": "USD",
    "balance": "25.00",
    "status": "active",
    "mask": "424242******4242",
    "last4": "4242",
    "expiration": "12/28",
    "is_non_subscription": true,
    "is_contactless_payment": false,
    "is_physical": false,
    "billing_address": {
      "address": "1 Market Street",
      "city": "Nairobi",
      "state": "Nairobi",
      "zip_code": "00100",
      "country": "KE"
    },
    "last_used_on": null,
    "created_at": "2026-11-07T08:00:00+00:00",
    "updated_at": "2026-11-07T08:00:00+00:00",
    "card_number": "4242424242424242",
    "security_code": "123"
  }
}
```


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