> ## Documentation Index > Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Card > Issue a new virtual USD card to an enrolled customer, optionally with an initial funding amount. ## 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](/api-reference/endpoint/Virtual-Card-Overview) and [Glossary → Card](/getting-started/glossary#card). ## Prerequisites * Customer must already exist via [`POST /customers`](/api-reference/endpoint/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 ` | | `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. | ```json theme={null} { "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`) ```json theme={null} { "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`](/api-reference/endpoint/webhook#card-created) — once the upstream issuer confirms the card. * [`transaction.funding.completed`](/api-reference/endpoint/webhook#transaction-funding-completed) — only if `amount > 0`. ## Code examples ```bash cURL theme={null} 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 }' ``` ```js Node.js (axios) theme={null} 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 Python (requests) theme={null} 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"] ``` ## Related * [Cards Overview](/api-reference/endpoint/Virtual-Card-Overview) — limits, statuses, and PCI DSS notes. * [`POST /cards/{id}/fund`](/api-reference/endpoint/post-card-fund) — add funds later. * [`GET /cards/{id}`](/api-reference/endpoint/get-card-by-id) — retrieve full (or revealed) card details. * [Webhooks](/api-reference/endpoint/webhook) — payloads emitted after creation. ## OpenAPI ````yaml POST /cards openapi: 3.1.0 info: title: Cartevo API description: Essential endpoints for wallets, transactions, customers and conversion. version: 1.0.0 servers: - url: https://api.cartevo.co/api/v1 security: - bearerAuth: [] paths: /cards: post: summary: Create a card requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string format: uuid brand: type: string enum: - VISA - MASTERCARD name_on_card: type: string amount: type: number required: - customer_id - brand responses: '201': description: Card created successfully. content: application/json: schema: $ref: '#/components/schemas/PostCardResponse' '400': description: Bad Request. e.g., Insufficient balance. components: schemas: PostCardResponse: type: object properties: status: type: string example: success message: type: string example: Card created successfully! card: $ref: '#/components/schemas/CreateCardResponseCard' autoFilledFields: type: array items: {} CreateCardResponseCard: type: object properties: id: type: string format: uuid example: 91b3c6d6-111b-44da-9f81-16f019bebe8c customer_id: type: string format: uuid example: 4d4dad81-7899-4612-a9f6-133ce56a4507 status: type: string example: ACTIVE balance: type: number example: 2 masked_pan: type: string example: 533758******1530 brand: type: string example: VISA currency: type: string example: USD expiry_month: type: integer example: 8 expiry_year: type: integer example: 30 is_virtual: type: boolean example: true is_physical: type: boolean example: false created_at: type: string format: date-time securitySchemes: bearerAuth: type: http scheme: bearer ````