Create Card - Cartevo Documentation

Create a card

curl --request POST \
  --url https://api.cartevo.co/api/v1/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name_on_card": "<string>",
  "amount": 123
}
'

{
  "status": "success",
  "message": "Card created successfully!",
  "card": {
    "id": "91b3c6d6-111b-44da-9f81-16f019bebe8c",
    "customer_id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
    "status": "ACTIVE",
    "balance": 2,
    "masked_pan": "533758******1530",
    "brand": "VISA",
    "currency": "USD",
    "expiry_month": 8,
    "expiry_year": 30,
    "is_virtual": true,
    "is_physical": false,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "autoFilledFields": [
    "<unknown>"
  ]
}

POST

cards

Create a card

curl --request POST \
  --url https://api.cartevo.co/api/v1/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name_on_card": "<string>",
  "amount": 123
}
'

{
  "status": "success",
  "message": "Card created successfully!",
  "card": {
    "id": "91b3c6d6-111b-44da-9f81-16f019bebe8c",
    "customer_id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
    "status": "ACTIVE",
    "balance": 2,
    "masked_pan": "533758******1530",
    "brand": "VISA",
    "currency": "USD",
    "expiry_month": 8,
    "expiry_year": 30,
    "is_virtual": true,
    "is_physical": false,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "autoFilledFields": [
    "<unknown>"
  ]
}

Overview

POST /cards issues a new virtual USD card to one of your customers. The card is usable immediately for online payments wherever Visa or Mastercard is accepted. If you provide an amount, the card is funded from your USD wallet in the same call.

When to use it

A customer needs a card for the first time.
An existing customer needs an additional card (you can issue more than one card per customer).

For card limits and lifecycle states, see Cards Overview and Glossary → Card.

Prerequisites

Customer must already exist via POST /customers and have KYC status APPROVED.
Your company USD wallet must have a balance covering the issuance fee plus the optional initial amount.
The customer’s country must be supported for card issuance (most African and many other countries — contact support for the current list).

Request

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`
`Content-Type`	Yes	`application/json`

Body

Field	Type	Required	Constraints	Description
`customer_id`	string	Yes	UUID of a customer in your company	The customer who will own the card.
`brand`	string	Yes	One of `VISA`, `MASTERCARD` (case-insensitive)	The card network. Both work globally; choose based on customer/merchant preference.
`name_on_card`	string	No	Max 50 characters. Letters, spaces, `.`, `-` recommended.	Cardholder name as it should be encoded. Defaults to the customer’s full name if omitted.
`amount`	number	No	≥ `0`. USD.	Initial funding amount in USD, deducted from the company USD wallet. Omit or set `0` for an unfunded card.

{
  "customer_id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
  "brand": "VISA",
  "name_on_card": "JOHN DOE",
  "amount": 100
}

Idempotency: This endpoint does not currently accept an idempotency key. To avoid duplicate cards on network retries, store the resulting card.id in your own database before retrying.

Response

201 — Card created (and funded if `amount > 0`)

{
  "success": true,
  "statusCode": 201,
  "message": "Card created successfully",
  "data": {
    "card": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
      "status": "ACTIVE",
      "balance": 100.0,
      "masked_pan": "4111********1111",
      "brand": "VISA",
      "currency": "USD",
      "expiry_month": 12,
      "expiry_year": 2028,
      "is_virtual": true,
      "is_physical": false,
      "created_at": "2026-05-09T10:15:00.000Z"
    },
    "auto_filled_fields": []
  }
}

Field	Type	Description
`card.id`	string	Cartevo card identifier (UUID). Use this in all future card calls.
`card.status`	string	`PENDING` while the upstream issuer processes; flips to `ACTIVE` on success.
`card.balance`	number	Current card balance in USD.
`card.masked_pan`	string	First 4 + masked + last 4 digits.
`card.expiry_month` / `card.expiry_year`	integer	Card expiry. Cards are valid for 3 years.
`auto_filled_fields`	array	Fields Cartevo defaulted (e.g. `name_on_card` from customer profile). Empty if you supplied everything.

Error responses

Status	`message` example	Trigger	Recommended action
`400`	`"Insufficient balance"`	Company USD wallet has less than (issuance fee + `amount`).	Top up the USD wallet.
`400`	`"Customer KYC not approved"`	Customer exists but `kyc_status` is `PENDING` or `REJECTED`.	Wait for KYC, or re-submit documents.
`400`	`"Invalid brand"`	`brand` is not `VISA` or `MASTERCARD`.	Fix the request.
`404`	`"Customer not found"`	`customer_id` does not exist or belongs to another company.	Verify the customer ID.
`422`	`"Card issuer rejected: ..."`	The upstream card issuer refused (rare — usually KYC- or BIN-related).	Inspect the message. May need support intervention.
`5xx`	`"Issuance temporarily unavailable"`	Transient upstream issue.	Retry with exponential backoff. Card may still issue eventually — check via `GET /cards`.

Webhooks fired

After a successful create call, you will receive (in order):

card.created — once the upstream issuer confirms the card.
transaction.funding.completed — only if amount > 0.

Code examples

cURL

curl -X POST https://api.cartevo.co/api/v1/cards \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
    "brand": "VISA",
    "name_on_card": "JOHN DOE",
    "amount": 100
  }'

Node.js (axios)

const { data } = await axios.post(
  "https://api.cartevo.co/api/v1/cards",
  {
    customer_id: customerId,
    brand: "VISA",
    name_on_card: "JOHN DOE",
    amount: 100,
  },
  { headers: { Authorization: `Bearer ${token}` } }
);
const cardId = data.data.card.id;

Python (requests)

resp = requests.post(
    "https://api.cartevo.co/api/v1/cards",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "customer_id": customer_id,
        "brand": "VISA",
        "name_on_card": "JOHN DOE",
        "amount": 100,
    },
)
resp.raise_for_status()
card_id = resp.json()["data"]["card"]["id"]

Cards Overview — limits, statuses, and PCI DSS notes.
POST /cards/{id}/fund — add funds later.
GET /cards/{id} — retrieve full (or revealed) card details.
Webhooks — payloads emitted after creation.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

customer_id

string<uuid>

required

brand

enum<string>

required

Available options:

VISA,

MASTERCARD

name_on_card

string

amount

number

Response

Card created successfully.

status

string

Example:

"success"

message

string

Example:

"Card created successfully!"

card

object

Show child attributes

autoFilledFields

any[]

Cards Overview List Cards

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Body

​Response

​201 — Card created (and funded if amount > 0)

​Error responses

​Webhooks fired

​Code examples

​Related

Authorizations

Body

Response

Overview

When to use it

Prerequisites

Request

Headers

Body

Response

201 — Card created (and funded if `amount > 0`)

Error responses

Webhooks fired

Code examples

Related