Customer to 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

A customer must reach the product’s required_level (usually verified) to receive a card. Browse the card product catalog to see available products, their limits and fees.

Step 1: Browse card products

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

curl -X GET "https://kemycard.com/api/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

curl -X POST https://kemycard.com/api/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": "[email protected]",
    "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

curl -X POST https://kemycard.com/api/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:

curl -X GET https://kemycard.com/api/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:

curl -X POST https://kemycard.com/api/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
  }'

{
  "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.

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.

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:

curl -X GET https://kemycard.com/api/v1/cards/c1d2e3f4-a5b6-7890-abcd-ef1234567890/sensitive \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

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.

Step 7: Top up the card

curl -X POST https://kemycard.com/api/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.

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

Getting Started

Integration Guides

Overview

Step 1: Browse card products

Step 2: Create a customer

Step 3: Get the KYC verification link

Step 4: Wait for KYC approval

Step 5: Create a card

Step 6: Card activated

Step 7: Top up the card

Step 8: Follow the card

Verification levels required

​Overview

​Step 1: Browse card products

​Step 2: Create a customer

​Step 3: Get the KYC verification link

​Step 4: Wait for KYC approval

​Step 5: Create a card

​Step 6: Card activated

​Step 7: Top up the card

​Step 8: Follow the card

​Verification levels required

Overview

Step 1: Browse card products

Step 2: Create a customer

Step 3: Get the KYC verification link

Step 4: Wait for KYC approval

Step 5: Create a card

Step 6: Card activated

Step 7: Top up the card

Step 8: Follow the card

Verification levels required