Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yativo.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Virtual cards are instantly issued, digital-only payment cards. Use them for online purchases, subscriptions, and contactless payments. You can create multiple virtual cards, set custom spending limits, and freeze or void them at any time.
Before creating a card, you must complete the onboarding flow including KYC approval, terms acceptance, and wallet deployment.
interface Card {
  card_id: string;
  yativo_card_id: string;
  display_name: string;
  type: "virtual" | "physical";
  status: "active" | "frozen" | "voided";
  last_four: string;
  expiry_month: number;
  expiry_year: number;
  spending_limit_amount: number;
  spending_limit_frequency: "daily" | "weekly" | "monthly";
  created_at: string;
}

interface CreateCardRequest {
  card_type?: "virtual" | "physical";
  display_name?: string;
  spending_limit_amount?: number;
  spending_limit_frequency?: "daily" | "weekly" | "monthly";
}

interface CardViewTokenResponse {
  secure_view_url: string;
  url: string;
  expires_at: string;
  last_four: string;
  card_type: string;
  holder_name: string;
  enabled_views: string[];
  requires_access_code: boolean;
}

​
List Cards

Retrieve all cards associated with the authenticated account. 
GET /yativo-card/list-cards

curl -X GET 'https://crypto-api.yativo.com/api/v1/yativo-card/list-cards' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "data": [
    {
      "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
      "display_name": "Online Shopping",
      "card_type": "virtual",
      "status": "active",
      "last_four": "4242",
      "spending_limit_amount": 500.00,
      "spending_limit_frequency": "monthly",
      "created_at": "2026-03-25T10:30:00Z"
    }
  ]
}

​
Create Virtual Card

Issue a new virtual card. Specify a display name and optional spending limit. 
POST /yativo-card/create-card
​
card_type
string
required
Must be "virtual" for virtual card creation.
​
display_name
string
required
A human-readable label for the card (e.g., “Monthly Subscriptions”, “Travel Expenses”).
​
spending_limit_amount
number
Maximum amount the card can spend per period. Omit to set no limit.
​
spending_limit_frequency
string
The reset frequency for the spending limit. Accepted values: daily, weekly, monthly, yearly, per_authorization.
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/create-card' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "virtual",
    "display_name": "Online Shopping",
    "spending_limit_amount": 500.00,
    "spending_limit_frequency": "monthly"
  }'

{
  "status": "success",
  "data": {
    "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
    "display_name": "Online Shopping",
    "card_type": "virtual",
    "status": "active",
    "last_four": "4242",
    "spending_limit_amount": 500.00,
    "spending_limit_frequency": "monthly",
    "created_at": "2026-03-25T10:30:00Z"
  }
}

​
View Card Details and PIN (Secure hosted page)

Sensitive card data — the full card number (PAN), CVV, expiry, and PIN — is never returned in API responses. To display it, your backend requests a secure view URL from Yativo. You open that URL for the cardholder in an iframe, WebView, or browser tab. Yativo hosts the page and handles all the cryptography internally — no SDK integration required on your side. How it works:
  1. Your backend calls POST /yativo-card/{yativoCardId}/cards/{cardId}/view-token
  2. You receive a secure_view_url
  3. Open the URL for the cardholder (iframe, WebView, new tab)
  4. Yativo’s hosted page displays PAN, CVV, expiry and/or PIN securely
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/card_01HX9KZMB3F7VNQP8R2WDGT4E5/view-token' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled_views": ["data", "pin"],
    "theme": { "accent_color": "#6366f1", "logo_url": "https://yourapp.com/logo.png" }
  }'
Response
{
  "success": true,
  "data": {
    "secure_view_url": "https://crypto-api.yativo.com/api/v1/yativo-card/view/eyJhbGci...",
    "expires_at": "2026-03-26T12:01:00Z",
    "last_four": "4242",
    "enabled_views": ["data", "pin"],
    "requires_access_code": false
  }
}
Always request a fresh URL immediately before showing card details. Never cache or reuse a previous secure_view_url.

Full integration guide

Backend proxy pattern, iframe embedding, access code flow, theming options, React/Vue/Vanilla JS examples, and CSP requirements.

​
Freeze a Card

Temporarily suspend a card. All transactions on a frozen card will be declined until unfrozen. 
POST /yativo-card/cards/{cardId}/freeze
​
cardId
string
required
The card ID to freeze.
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/cards/card_01HX9KZMB3F7VNQP8R2WDGT4E5/freeze' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "status": "success",
  "data": {
    "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
    "status": "frozen",
    "frozen_at": "2026-03-25T11:00:00Z"
  }
}

​
Unfreeze a Card

Re-activate a frozen card. 
POST /yativo-card/cards/{cardId}/unfreeze

curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/cards/card_01HX9KZMB3F7VNQP8R2WDGT4E5/unfreeze' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "status": "success",
  "data": {
    "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
    "status": "active",
    "unfrozen_at": "2026-03-25T11:05:00Z"
  }
}

​
Void a Card

Permanently cancel a card. This action is irreversible. A voided card cannot be reactivated. 
POST /yativo-card/cards/{cardId}/void

curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/cards/card_01HX9KZMB3F7VNQP8R2WDGT4E5/void' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "status": "success",
  "data": {
    "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
    "status": "voided",
    "voided_at": "2026-03-25T11:10:00Z"
  }
}
Voiding a card is permanent. If you only need to temporarily stop spending, use freeze instead.

​
Set Card PIN

Setting a PIN requires a two-step process: first request an OTP, then submit the OTP along with the new PIN.

​
Step 1 — Request OTP

POST /yativo-card/cards/{cardId}/pin/otp

curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/cards/card_01HX9KZMB3F7VNQP8R2WDGT4E5/pin/otp' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "status": "success",
  "data": {
    "otp_sent": true,
    "delivery_method": "email",
    "expires_in_seconds": 300
  }
}

​
Step 2 — Set PIN

POST /yativo-card/cards/{cardId}/pin/set
​
cardId
string
required
The card ID for which to set the PIN.
​
otp
string
required
The one-time password received via email or SMS.
​
pin
string
required
The new 4-digit PIN. Must be numeric only.
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/cards/card_01HX9KZMB3F7VNQP8R2WDGT4E5/pin/set' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "otp": "847291",
    "pin": "4821"
  }'

{
  "status": "success",
  "data": {
    "pin_set": true,
    "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5"
  }
}

​
Get User Profile

Retrieve the card account profile for a given Yativo Card ID. 
GET /yativo-card/{yativoCardId}/profile
​
yativoCardId
string
required
The Yativo Card account ID.
curl -X GET 'https://crypto-api.yativo.com/api/v1/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/profile' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "data": {
    "yativo_card_id": "yc_01HX9KZMB3F7VNQP8R2WDGT4E5",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "kyc_status": "approved",
    "terms_accepted": true,
    "wallet_deployed": true,
    "created_at": "2026-03-25T10:00:00Z"
  }
}

​
Card Status Reference

StatusDescription
activeCard is in good standing and can be used for transactions.
frozenCard is temporarily suspended. Transactions will be declined.
voidedCard has been permanently cancelled. Cannot be reactivated.
pendingCard is being provisioned. Usually resolves within seconds.

​
Sandbox Testing

Replace YOUR_SANDBOX_TOKEN with a token obtained by authenticating against https://crypto-sandbox.yativo.com/api/v1/. See Sandbox Overview.

​
Create a Virtual Card (Sandbox)

curl -X POST 'https://crypto-sandbox.yativo.com/api/v1/yativo-card/create-card' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "virtual",
    "display_name": "Sandbox Test Card",
    "spending_limit_amount": 100.00,
    "spending_limit_frequency": "monthly"
  }'

​
List Cards (Sandbox)

curl -X GET 'https://crypto-sandbox.yativo.com/api/v1/yativo-card/list-cards' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN'