Quickstart

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_*)
A tool for making HTTP requests (cURL, Postman)

Authenticate

Set your API key. All examples below use the sandbox key.

export CONTRO_API_KEY="sk_test_your_key_here"

import Contro from "@contro/partner-sdk";

const contro = new Contro({
  apiKey: "sk_test_your_key_here",
});

from contro_partner_sdk import Contro

contro = Contro(api_key="sk_test_your_key_here")

const API_KEY = "sk_test_your_key_here";
const BASE_URL = "https://api.contro.me/v1";

const headers = {
  "x-contro-api-key": API_KEY,
  "Content-Type": "application/json",
};

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"
  }'

const session = await contro.kycSessions.create({
  externalUserId: "user_123",
});
// session = { id: "ks_abc123", url: "https://...", expiresAt: "..." }
// → Open session.url for the user to complete KYC

session = contro.kyc_sessions.create(external_user_id="user_123")
# session = { id: "ks_abc123", url: "https://...", expires_at: "..." }
# → Open session.url for the user to complete KYC

const session = await fetch(`${BASE_URL}/partner/kyc-sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ externalUserId: "user_123" }),
}).then((r) => r.json());
// session = { id: "ks_abc123", url: "https://...", expiresAt: "..." }
// → Open session.url for the user to complete KYC

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"
  }'

const cardholder = await contro.cardholders.create({
  externalUserId: "user_123",
  kycSource: "web",
  kycSessionId: session.id,
  email: "jane@example.com",
  phoneNumber: "+14155552671",
});

console.log(cardholder.id); // "ch_abc123"

cardholder = contro.cardholders.create(
    external_user_id="user_123",
    kyc_source="web",
    kyc_session_id=session.id,
    email="jane@example.com",
    phone_number="+14155552671",
)

print(cardholder.id)  # "ch_abc123"

const cardholder = await fetch(`${BASE_URL}/partner/cardholders`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    externalUserId: "user_123",
    kycSource: "web",
    kycSessionId: session.id,
    email: "jane@example.com",
    phoneNumber: "+14155552671",
  }),
}).then((r) => r.json());

console.log(cardholder.id); // "ch_abc123"

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"
  }'

await contro.cardholders.initiateKyc(cardholder.id, {
  cardProgramId: "cp_xyz789",
});

contro.cardholders.initiate_kyc(cardholder.id, card_program_id="cp_xyz789")

await fetch(`${BASE_URL}/partner/cardholders/${cardholder.id}/kyc`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    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"

const kyc = await contro.cardholders.getKyc(cardholder.id, {
  cardProgramId: "cp_xyz789",
});

console.log(kyc.kycStatus); // "pending" | "approved" | "rejected"

kyc = contro.cardholders.get_kyc(cardholder.id, card_program_id="cp_xyz789")

print(kyc.kyc_status)  # "pending" | "approved" | "rejected"

const kyc = await fetch(
  `${BASE_URL}/partner/cardholders/${cardholder.id}/kyc?cardProgramId=cp_xyz789`,
  { headers }
).then((r) => r.json());

console.log(kyc.kycStatus); // "pending" | "approved" | "rejected"

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"
  }'

const card = await contro.cards.create({
  cardholderId: cardholder.id,
  programId: "cp_xyz789",
});

console.log(card.id); // "card_def456"

card = contro.cards.create(
    cardholder_id=cardholder.id,
    program_id="cp_xyz789",
)

print(card.id)  # "card_def456"

const card = await fetch(`${BASE_URL}/partner/cards`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    cardholderId: cardholder.id,
    programId: "cp_xyz789",
  }),
}).then((r) => r.json());

console.log(card.id); // "card_def456"

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"

const txns = await contro.cards.listTransactions(card.id);

for (const tx of txns.data) {
  console.log(`${tx.type} ${tx.amount} ${tx.currency} - ${tx.merchant}`);
}

txns = contro.cards.list_transactions(card.id)

for tx in txns.data:
    print(f"{tx.type} {tx.amount} {tx.currency} - {tx.merchant}")

const txns = await fetch(
  `${BASE_URL}/partner/cards/${card.id}/transactions`,
  { headers }
).then((r) => r.json());

for (const tx of txns.data) {
  console.log(`${tx.type} ${tx.amount} ${tx.currency} - ${tx.merchant}`);
}

Next steps

Cardholders

Learn about cardholder management and KYC methods

Cards

Card lifecycle, limits, and actions

Webhooks

Set up real-time event notifications

API reference

Explore all endpoints in the playground

Sample demo app

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

Getting started

Core resources

Platform

Prerequisites

Next steps

Cardholders

Cards

Webhooks

API reference

Sample demo app

​Prerequisites

​Next steps

Cardholders

Cards

Webhooks

API reference

Sample demo app

Prerequisites

Next steps