Skip to main content
This guide walks you through the core Partner API flow: creating a cardholder, completing KYC, and issuing a card.
Prefer to run a working example? Download the sample demo app — a self-contained Bun + React project that walks through every step in this guide against the sandbox. Extract it, add your CONTRO_API_KEY to .env, and run bun install && bun run dev.

​
Prerequisites

  • A Contro partner account with sandbox API keys (sk_test_*)
  • The Contro SDK installed, or a tool for making HTTP requests (cURL, Postman)
1

Authenticate

Set your API key. All examples below use the sandbox key.
export CONTRO_API_KEY="sk_test_your_key_here"
2

Create a KYC session

Register an end user by first creating a hosted KYC session. The user completes identity verification on the Contro-hosted page. See Cardholders for all KYC options.
curl -X POST https://api.contro.me/v1/partner/kyc-sessions \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123"
  }'
Once the session status is completed (poll or listen for the kyc_session.completed webhook), create the cardholder:
curl -X POST https://api.contro.me/v1/partner/cardholders \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "kycSource": "web",
    "kycSessionId": "ks_abc123",
    "email": "jane@example.com",
    "phoneNumber": "+14155552671"
  }'
3

Initiate KYC for a card program

Submit the cardholder for KYC verification against a specific card program. Cards cannot be issued until KYC is approved for that program.
curl -X POST https://api.contro.me/v1/partner/cardholders/ch_abc123/kyc \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardProgramId": "cp_xyz789"
  }'
Poll the KYC status or listen for the webhook event:
curl "https://api.contro.me/v1/partner/cardholders/ch_abc123/kyc?cardProgramId=cp_xyz789" \
  -H "x-contro-api-key: $CONTRO_API_KEY"
4

Issue a card

Once KYC is approved for the card program, issue a card.
curl -X POST https://api.contro.me/v1/partner/cards \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholderId": "ch_abc123",
    "programId": "cp_xyz789"
  }'
5

Query transactions

View transaction activity for the card.
curl https://api.contro.me/v1/partner/cards/card_def456/transactions \
  -H "x-contro-api-key: $CONTRO_API_KEY"

​
Next steps

Cardholders

Learn about cardholder management and KYC methods

Cards

Card lifecycle, limits, and actions

Webhooks

Set up real-time event notifications

SDKs

Use the Node.js or Python SDK

API reference

Explore all endpoints in the playground

Sample demo app

Download a runnable end-to-end example against the sandbox