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

# Customer to Card

> Complete flow: create a customer, verify identity, and issue a card

This guide walks you through the full flow to issue a card for a customer.

## Overview

```
Step 1: Browse card products   → Choose a product
Step 2: Create customer        → BASIC
Step 3: Submit KYC             → PENDING
Step 4: KYC approved           → VERIFIED
Step 5: Create card            → PENDING
Step 6: Card activated         → ACTIVE
Step 7: Top up card            → Funded
```

<Info>
  A customer must reach the product's `required_level` (usually `verified`) to receive a card.
  Browse the [card product catalog](/api-reference/card-products/list) to see available products, their limits and fees.
</Info>

## Step 1: Browse card products

Start by consulting the catalog to find the right product for your use case:

```bash theme={null}
curl -X GET "https://api.kemycard.com/v1/cards/products?brand=MASTERCARD&type=virtual" \
  -H "Authorization: Bearer sk_test_YOUR_KEY"
```

Each product specifies its `required_level`, limits with and without KYC (`max_balance`, `max_reload`, `spend_limit_monthly`, `spend_limit_monthly_without_kyc`, `max_card_per_user`, `max_card_per_user_without_kyc`), features (`google_pay`, `apple_pay`, `atm_available`, `addons`), initial load requirements (`initial_load.required`, `initial_load.min`, `initial_load.max`) and fees (`creation_fee`, `reload_fee`, etc.).

## Step 2: Create a customer

```bash theme={null}
curl -X POST https://api.kemycard.com/v1/customers \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "user-001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_country_code": "+33",
    "phone": "612345678",
    "date_of_birth": "1990-05-15",
    "address": "123 Main Street",
    "city": "Paris",
    "state": "IDF",
    "postal_code": "75001",
    "country": "FRA"
  }'
```

The customer is created with `verification_level: basic`.

## Step 3: Get the KYC verification link

```bash theme={null}
curl -X POST https://api.kemycard.com/v1/kyc/a1b2c3d4-e5f6-7890-abcd-ef1234567890/link \
  -H "Authorization: Bearer sk_test_YOUR_KEY"
```

Response includes a `verification_url` — redirect your customer there. You can call this endpoint again at any time to get the link back, or a new one if it expired.

## Step 4: Wait for KYC approval

Listen for the `kyc.approved` webhook, or check the status endpoint:

```bash theme={null}
curl -X GET https://api.kemycard.com/v1/kyc/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  -H "Authorization: Bearer sk_test_YOUR_KEY"
```

Once approved, the customer automatically upgrades to `verification_level: verified`.

## Step 5: Create a card

Pick a card product from `GET /cards/products` and create the card with its `code`:

```bash theme={null}
curl -X POST https://api.kemycard.com/v1/cards \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "product_code": "019aaa11-2222-7333-8444-555566667777",
    "name_on_card": "John Doe",
    "amount": 100.00
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "code": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
    "customer_code": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "product_code": "019aaa11-2222-7333-8444-555566667777",
    "brand": "VISA",
    "category": "virtual_basic",
    "name_on_card": "John Doe",
    "status": "pending",
    "balance": 100.00,
    "currency": "USD",
    "last_four": null,
    "expiry": null,
    "fees": {
      "card_fee": 30.00,
      "service_fee": 5.00,
      "total_charged": 135.00
    },
    "created_at": "2026-10-06T10:00:00+00:00"
  }
}
```

`amount` is the initial load. It is required when the product has `initial_load.required: true`, within its `min` and `max`.

<Warning>
  Card creation debits your ops balance (`cards_mastercard` or `cards_visa`, depending on the product brand) of `total_charged`: the initial load, the card fee and the service fee of the product. The fees are listed on each product in `GET /cards/products`; the lower `_with_kyc` tariff applies when the customer's KYC is approved.
</Warning>

## Step 6: Card activated

The card is issued asynchronously. You receive a `card.activated` webhook when it is ready, or `card.creation_failed` if it could not be issued — in that case `total_charged` is refunded to the same `cards_visa` or `cards_mastercard` balance.

Once the card is `active`, get its number, CVV and expiry from your server:

```bash theme={null}
curl -X GET https://api.kemycard.com/v1/cards/c1d2e3f4-a5b6-7890-abcd-ef1234567890/sensitive \
  -H "Authorization: Bearer sk_test_YOUR_KEY"
```

<Warning>
  Call this endpoint only when your customer needs to see the card, and never store or log its response. Every other endpoint only returns `last_four`.
</Warning>

## Step 7: Top up the card

```bash theme={null}
curl -X POST https://api.kemycard.com/v1/cards/c1d2e3f4-a5b6-7890-abcd-ef1234567890/topup \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00}'
```

The top-up is applied asynchronously: you receive `card.topup.completed`, or `card.topup.failed` with a refund. See [Top Up a Card](/guides/topup-card).

## Step 8: Follow the card

| Need | How |
| - | - |
| Payments, declines, refunds and fees | `card.transaction` webhook, or `GET /cards/{code}/transactions` |
| 3-D Secure code asked by a merchant | `card.3ds_request` webhook — relay the code to your customer immediately |
| Block or unblock the card | `POST /cards/{code}/freeze` and `POST /cards/{code}/unfreeze` |
| Card terminated | `card.terminated` webhook — the remaining balance is returned to your `cards_visa` or `cards_mastercard` balance |

## Verification levels required

| Product | Minimum level | Why |
| - | - | - |
| Gift Cards (low amounts) | `basic` | Low risk |
| Virtual Cards | depends on the product | See `required_level` on each card product |
| Physical Cards | `verified` | KYC required |
| Crypto Wallets | `verified` | KYC required by regulation |
| Virtual Bank Accounts | `full` | KYC + POA required for banking |


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