Codego Developers · Card · Visa Crypto USD · v1.0

Visa Card International USD API Reference

Issue USD-denominated Visa cards backed by crypto collateral under your brand. Onboard cardholders with KYC/KYB, issue virtual & physical cards, fund the credit line with USDC, manage PINs & limits, and receive HMAC-signed webhooks on every event.

Sandbox https://vcc-sandbox.codegotech.com/api/v1
Live https://visacard.codegotech.com/api/v1

Auth API key (X-Api-Key) · Body application/json

This reference covers the API integration for the Visa Crypto Card programme. If your programme runs in "Core banking Included" mode (a fully managed, branded cardholder portal that Codego hosts for you) there is nothing to integrate here — your cardholders use the portal directly and you manage everything from your whitelabel console.

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

Sandbox provisioning is fully automated and instant — no approval needed. The dashboard lets you inspect cardholders, cards, transactions and KYC sessions you create via the API.

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.

curl -X POST https://kyc-sandbox.codegotech.com/api/session/create \
  -H 'X-API-Key: your_kyc_sandbox_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalUserId": "your-user-001",
    "applicantType": "individual",
    "email": "[email protected]",
    "origin": "https://app.your-brand.com",
    "locale": "en",
    "returnUrl": "https://app.your-brand.com/onboarding/done"
  }'

Expected response (201 Created):

{
  "sessionId": "01HXY3FZK7QM2N8RP6V4XBJDGC",
  "iframeUrl": "https://kyc-sandbox.codegotech.com/embed?sid=01HXY3FZK7QM2N8RP6V4XBJDGC&t=eyJ…",
  "expiresAt": "2026-05-25T18:42:00Z"
}

Sandbox shortcut: every 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:

<iframe src={iframeUrl} style={{ width:'100%', height:780 }} allow="camera" />

window.addEventListener('message', e => {
  if (e.origin !== 'https://kyc-sandbox.codegotech.com') return;
  if (e.data?.type === 'kyc:done') {
    // KYC submitted — wait for the user.updated webhook for the final outcome.
  }
});

Integration flow

A complete integration follows six sequential steps. 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.

step	What happens	Endpoints involved
1 · Onboard	Your backend opens a KYC session with your own `externalUserId` and gets a one-time `iframeUrl`. For an individual the iframe captures ID + selfie + address proof; for a company (KYB) the same iframe also collects legal entity info, UBOs and incorporation documents. Codego runs identity review and creates the on-chain collateral contract on approval. You receive the outcome via the `user.updated` (individual) or `company.updated` (KYB) webhook.	`POST /api/session/create` { applicantType: `individual`\|`company` } · `<iframe>` embed · `GET /applications/{userId}` or `GET /applications/companies/{companyId}`
2 · Fund	Fetch the cardholder's collateral contract (deposit address + chain). Send USDC. Monitor the available balance.	`GET /users/{userId}/contracts` · `GET /users/{userId}/balances`
3 · Issue	Issue a virtual or physical Visa card to an approved cardholder, with per-frequency spending limits.	`POST /users/{userId}/cards` · `GET /cards` · `GET /cards/{cardId}`
4 · Manage	Lock / unlock / cancel cards; adjust limits; render the PAN, CVC or PIN under the encrypted-secrets flow.	`PATCH /cards/{cardId}` · `GET /cards/{cardId}/secrets` · `GET /cards/{cardId}/pin`
5 · Transactions	List and inspect authorisations, captures and settled spend. Open a dispute if needed.	`GET /transactions` · `GET /transactions/{txId}` · `POST /transactions/{txId}/disputes`
6 · Webhooks	Receive real-time notifications for every state change — KYC outcome, contract creation, card status, authorisations, settlements, disputes.	Configured in the partner dashboard. HMAC-signed deliveries.

Sandbox parity: every endpoint, request shape, response shape, error code and webhook event is identical between sandbox and live. To promote your integration, change only the base URL host and the API key prefix. KYC outcomes in sandbox are auto-decided (always approved) so you can exercise the full lifecycle without waiting for human review.

Regulatory notice: issuance and KYC are subject to the rules of the underlying issuing programme and applicable AML/CTF regulation. Sandbox is for technical integration only — no real funds, no real identity verification, and no card may be presented for payment.

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].

Rate limit: 1,000 requests / minute per key. Responses include X-RateLimit-Remaining and X-RateLimit-Reset. On 429, back off until the reset timestamp.

Card PAN / CVC / PIN are PCI-sensitive: retrieved only via the encrypted-secrets endpoints with an RSA-OAEP SessionId header, and must never be stored.

Environments — sandbox & live

environment	Base URL	Key prefix	Notes
Sandbox	https://vcc-sandbox.codegotech.com/api/v1	`vcck_sbx_…`	Test cards, simulated balances. KYC instant-approval shortcut: set `lastName` to `TestApproved` on a consumer application.
Live	https://visacard.codegotech.com/api/v1	`vcck_live_…`	Real Visa rails, real cards, real KYC. Authorisation required — contact [email protected] to enable.

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.

Going live: when your sandbox integration is ready, email [email protected] with your whitelabel id. We'll verify your compliance setup and issue your vcck_live_… key. To activate: 1) switch the base URL to https://visacard.codegotech.com/api/v1, 2) swap the sandbox key for your live key, 3) send us the server IP(s) that will call the live API — live access is IP-allowlisted (default-deny), so calls from non-allowlisted IPs are rejected, 4) reconfigure your webhook URL for the live environment.

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 Visa Crypto Card API automatically.

The KYC sandbox key is issued together with your Visa Crypto Card sandbox key — same email, same onboarding step. See the KYC SDK section below for the full request/response shape.

Errors

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

code	Meaning
200 / 201	Success
400	Validation failed — see `message`
401	Missing or invalid API key
404	Resource not found
429	Rate limit exceeded — honour `X-RateLimit-Reset`