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
}'
{
"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"
}
}
Cards
Create card
Issue one USD virtual card for online checkout and load the opening amount.
POST
/
card
/
create
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
}'
{
"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"
}
}
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.
Cardholder id returned by create card user.
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 |
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
}'
{
"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"
}
}
