Visa & Mastercard Card Issuing API Reference

Quickstart — Sandbox onboarding

Self-serve sandbox access in three steps. You'll get a whitelabel id and a sandbox API key (vcck_sbx_…) by email within minutes. Sandbox runs on a fully isolated database — your test calls never touch the live ledger.

1 · Sign up — get your sandbox API key

Open apikey-visacard-sandbox.codegotech.com and submit the short signup form (name, email, phone, company, website). Within ~30 seconds you'll receive an email containing:

• The sandbox dashboard URL at vcc-whitelabel-sandbox.codegotech.com
• Login email + password
• Your whitelabel id
• Your API key in the form vcck_sbx_… — shown only once, store it safely
• A ready-to-paste curl snippet + link to this reference

2 · Open a KYC session for your first cardholder

Every cardholder onboarding starts with a KYC session. You call it from your backend, pass your own externalUserId, and get back a one-time iframeUrl. You drop that URL into an iframe in your app — the cardholder uses it to capture their ID, take a selfie, verify their address. Documents never leave Codego. When the cardholder finishes, you receive a webhook with the KYC outcome and the resolved profile.

Expected response (201 Created):

Note — no userId here, and that's correct. At session-create time the cardholder hasn't been verified yet, so no user exists. The userId you use for every later call (GET /users/{userId}, POST /users/{userId}/cards, …) is delivered in the user.updated webhook once KYC resolves — see KYC outcomes below. Keep your own externalUserId as the correlation key until then.

Sandbox shortcut: every individual KYC outcome in sandbox is auto-approved — the iframe accepts any sample image and resolves the session in seconds. Real KYC review (production) can take 1–2 business days.

Then embed the iframe in your app and listen for completion:

Integration flow

A complete integration follows the seven sequential steps below — the same order as the left navigation. The endpoints in the left navigation are grouped accordingly. Cardholder onboarding is iframe-only by design: your end-user captures their ID and selfie directly inside the Codego KYC iframe — you never receive, store or forward identity documents, which keeps you out of the regulated data-processor scope. You receive only the final structured result via webhook.

Two tracks: individual and business

Only the onboarding differs. Once a cardholder exists — whether they are a private person or an authorised user of a company — funding, card issuance, card management, transactions and webhooks are the same endpoints. Cards for a company's users are issued with the very same POST /users/{userId}/cards, spending against the company collateral instead of a personal one.

Step by step

Which wallet belongs to which cardholder

A wallet is self-custodial: at the moment you create it the cardholder does not exist yet, so there is no userId to attach it to. The relation is established by you, at two points.

Authentication

Every request is authenticated with your whitelabel API key in the X-Api-Key header. Keys look like vcck_sbx_… (sandbox) or vcck_live_… (production) and are issued at onboarding. Keep the key server-side — never expose it in client code.

Each key is scoped to one whitelabel tenant; all resources you create or read are isolated to it. Sandbox and live are fully separated. To rotate a key, contact [email protected].

IP allowlist (optional). Your key can be restricted to a set of source IPs. While the list is empty the key works from anywhere; once you register one or more addresses (single IPv4 or CIDR, e.g. 203.0.113.10 or 203.0.113.0/24) only those addresses may use that key, and a request from any other address is refused with 403 — IP not authorised for this API key. The restriction is bound to the key, not to the network: an address authorised for another integrator cannot be used with your key, and yours cannot be used with theirs. To register or change your addresses, contact [email protected].

Environments — sandbox & live

Both environments share the same endpoint paths, request and response shapes — the same code works in both. Switch hosts, switch keys, and you're done. Webhooks are configured separately per environment.

Fund the card — deposits & multi-coin top-up

A card spends against its USDC collateral. You fund it in one of two ways. Direct: send USDC (or USDT) on Base or Arbitrum straight to the cardholder's collateral contract — instant, no fee. Multi-coin top-up: let the cardholder deposit any supported coin on any supported network (e.g. USDT-TRON, ETH, USDC on Ethereum) to the deposit address we return — Codego auto-converts it to USDC and credits the card in a few minutes, minus a small top-up fee. No amount needs to be declared up front: the cardholder simply sends to the address and the deposit is detected and credited automatically.

Direct funding (instant)

Fetch the collateral contract for the chain you want and send USDC/USDT to that address on that network. The card balance updates when the deposit confirms on-chain (a transaction webhook is delivered). Supported direct networks: Base (chainId 8453) and Arbitrum One (chainId 42161).

GET /users/{userId}/contracts
GET /users/{userId}/balances

1 · List supported coins & networks

Returns every coin/network the cardholder can deposit, with per-network mode, speed, fee and live availability. Render your deposit UI directly from this.

GET /users/{userId}/topup/assets

// 200 OK
{
  "assets": [
    {
      "coin": "USDC",
      "name": "USD Coin",
      "logoUrl": "https://.../usdc.png",
      "networks": [
        { "network": "arbitrum", "label": "Arbitrum One", "mode": "direct",
          "speed": "instant", "feePct": 0, "feeFixedUsd": 0, "feeNetworkUsd": 0,
          "available": true, "reason": null },
        { "network": "ethereum", "label": "Ethereum (ERC-20)", "mode": "convert",
          "speed": "few_minutes", "feePct": 0.5, "feeFixedUsd": 0, "feeNetworkUsd": 3,
          "available": true, "reason": null }
      ]
    },
    { "coin": "USDT", "name": "Tether", "logoUrl": "...", "networks": [ /* … */ ] },
    { "coin": "ETH",  "name": "Ethereum", "logoUrl": "...", "networks": [ /* … */ ] }
  ]
}

2 · Get the deposit address

Returns the current deposit address for that coin/network. The address is reusable, but always call this endpoint to fetch it right before you show it — do not hardcode or cache it long-term, as it can change if the coin’s routing changes. For a direct network there is no deposit address: the response tells you to use the cardholder’s collateral contract instead.

POST /users/{userId}/topup/address
{ "coin": "USDT", "network": "tron" }

// 200 OK (convert network)
{ "mode": "convert", "coin": "USDT", "network": "tron",
  "depositAddress": "T…", "persistent": true }

// 200 OK (direct network → use the collateral contract)
{ "mode": "direct", "coin": "USDC", "network": "arbitrum", "useExistingDeposit": true }

Maintenance / disabled networks. A coin or network can be temporarily switched off. When it is, GET …/topup/assets returns that network with "available": false, "reason": "maintenance" and a human-readable "reason_message" you can show to the user, and POST …/topup/address responds 400 with { "error": "maintenance", "message": "…" }. Other networks stay available — build your UI from the live topup/assets response.

// GET …/topup/assets — a network under maintenance
{ "network": "tron", "label": "Tron (TRC-20)", "mode": "convert",
  "available": false, "reason": "maintenance",
  "reason_message": "USDT deposits on the Tron network are temporarily unavailable for maintenance." }

// POST …/topup/address on a network under maintenance → 400
{ "error": "maintenance",
  "message": "USDT deposits on the Tron network are temporarily unavailable for maintenance." }

3 · (Optional) Quote the net amount

Preview how much USDC a deposit would credit. Optional — the flow works without it (the deposit is credited automatically). For volatile coins the amount is an estimate (the real credit is the amount realised from the conversion).

POST /users/{userId}/topup/quote
{ "coin": "USDC", "network": "ethereum", "amount": 100 }

// 200 OK
{ "coin": "USDC", "network": "ethereum",
  "grossAmount": 100, "feePct": 0.5, "feeNetworkUsd": 3,
  "feeAmount": 3.5, "netUsdc": 96.5,
  "speed": "few_minutes", "needsPrice": false }
// volatile coins (e.g. ETH) also return: "priceUsd", "grossUsd", "estimate": true

4 · Track the deposit

Poll the cardholder's deposits and their live status. Statuses are neutral (no internal mechanics exposed). The card balance also updates via GET /users/{userId}/balances once credited.

GET /users/{userId}/topup/orders?limit=20

// 200 OK
{
  "orders": [
    {
      "orderRef": "top_…",
      "coin": "USDT", "network": "tron",
      "amountIn": 50, "creditedUsdc": 46.75,
      "feePctUsd": 0.25, "feeGasUsd": 0, "feeTotalUsd": 3.25,
      "status": "completed",          // processing | completed | below_minimum | failed | expired
      "progressLabel": "Completed",   // Detected | Processing | Almost done | Finalizing | Completed
      "etaSec": 0, "step": 4, "steps": 4,
      "detectedAt": "…", "creditedAt": "…", "createdAt": "…"
    }
  ]
}

// Single deposit: GET /users/{userId}/topup/orders/{orderRef}

KYC SDK — drop-in iframe

If you don't want to build the document-capture UI yourself, embed the Codego KYC iframe in your app. The wizard handles ID capture, liveness, address proof, UBOs (for KYB) and (for selfies) anti-AI flash + zoom challenges — entirely on Codego infrastructure. Documents never touch your servers.

Two steps: (1) POST to https://kyc-sandbox.codegotech.com/api/session/create from your backend with your KYC sandbox key → you get an iframeUrl. (2) Drop the URL into an <iframe allow="camera"> in your app and listen for postMessage on completion. The session forwards the result to the card issuing API automatically.

KYC outcomes — the user.updated webhook

After the cardholder submits, Codego runs identity review and notifies you with a user.updated webhook. This webhook is where you receive the userId (field body.id) used for all later /users/{userId}/* calls, and it echoes back your externalUserId so you can match it to your own user record. The body.applicationStatus field carries the outcome. Handle these values:

Example user.updated payload (HMAC-signed, delivered to your configured webhook URL):

Map body.id → your record keyed by body.externalUserId, then continue: GET /users/{userId}, fund the contract, and POST /users/{userId}/cards.

// Verify a delivery (Node)
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)            // the raw request body, not re-serialised JSON
  .digest('hex');
if (req.headers['signature'] !== expected) return res.status(401).end();

Application states, session states and rejection reasons

Two different state machines are involved, and they are easy to confuse. The application state is the verification decision. The session state is the progress of the cardholder through the KYC iframe. They move independently: a session can be submitted while the application is still pending.

applicationStatus vs kycStatus. The user.updated webhook carries both. In live they always hold the same value — kycStatus is a historical duplicate of applicationStatus, kept for backwards compatibility. Build your logic on applicationStatus and treat kycStatus as an alias. In sandbox both are always approved.

A session in submitted, approved, rejected or expired is terminal and cannot be resumed: resumeSessionId on one of those returns 409 { "error": "not_resumable", "status": "<state>" }. Only needs_action (and a session still in progress) can be resumed.

Reading the session state — and how it relates to the application

Webhooks are delivered once and never re-sent, so if your endpoint was unavailable the event is gone. Read the state back whenever you need it: GET /kyc/sessions/{sessionId}, or GET /kyc/sessions?externalUserId=… when you did not store our sessionId. The response carries the same fields as the kyc.* events — status and, on needs_action, the reason, the steps to redo and the message to show the cardholder. A periodic sweep of ?status=needs_action is enough to catch anything you missed.

In short: drive the KYC flow on the session status (kyc.* webhooks, or GET /kyc/sessions), and use applicationStatus for one decision only — whether a card can be issued (approved).

Matching a cardholder to your own records

Every object that concerns one of your cardholders carries your own reference, never a Codego identifier: externalUserId in the kyc.* and user.updated events and in GET /kyc/sessions; externalId in GET /applications/{userId} and GET /users/{userId}. In every case it is the value you sent to POST /api/session/create (or to POST /applications), so the same key matches a cardholder across webhooks and API.

The field is null in one case only: a cardholder Codego created on your behalf — for example a profile assigned from the Codego console — where no reference of yours exists. Use userId for those.

Rejection reasons. When the application is needsInformation or denied, applicationReason holds one or more codes, comma-separated (for example "BAD_SELFIE, GRAPHIC_EDITOR, UNSATISFACTORY_PHOTOS"). Match on substrings rather than on the whole string, since codes are combined.

Resuming a needsInformation session (live). Call POST /api/session/create again, passing resumeSessionId set to the original sessionId instead of starting a fresh session. You get back a new iframeUrl that re-opens the same application at exactly the step flagged in review (e.g. just the selfie/liveness). The cardholder re-submits only that document — no new application is created, no data re-entered. On success the status returns to submitted (back in review).

// On a needsInformation webhook, re-open the SAME session — fix only what's needed.
POST https://kyc-live.codegotech.com/api/session/create
{ "resumeSessionId": "<original sessionId>" }
// → { "iframeUrl": "…?resume=selfie", "resume": "selfie", "sessionId": "<same id>" }

Errors

The API uses standard HTTP status codes. 2xx = success; 4xx = client error with a JSON { error, message } body; 5xx = transient — retry with backoff.