Skip to main content
GET
/
v1
/
card-issuer
/
customers
curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "success": true,
  "data": {
    "customers": [
      {
        "customer_id": "69f0bdf29a84752db9cc8ff9",
        "yativo_card_id": "yativo_card_customer_8f9a..._1769031332068",
        "external_customer_id": "usr_8821",
        "email": "alice@yourapp.com",
        "flow_status": "active",
        "step": 6,
        "next_action": "Card is active — customer can spend",
        "safe_deployed": true,
        "currency": "USD",
        "ledger_balance": 45.23,
        "available_balance": 38.50,
        "pending_balance": 6.73,
        "balance_freshness": "realtime",
        "cards_count": 1,
        "created_at": "2026-04-20T08:00:00.000Z"
      },
      {
        "customer_id": "6627f3a2c5d4e100123abcde",
        "yativo_card_id": "yativo_card_customer_ab12..._1769031332999",
        "external_customer_id": "usr_7714",
        "email": "bob@yourapp.com",
        "flow_status": "kyc_initiated",
        "step": 3,
        "next_action": "Awaiting KYC verification",
        "safe_deployed": false,
        "currency": null,
        "ledger_balance": null,
        "available_balance": null,
        "pending_balance": null,
        "balance_freshness": null,
        "cards_count": 0,
        "created_at": "2026-04-25T10:00:00.000Z"
      }
    ],
    "total": 87,
    "page": 1,
    "limit": 20,
    "balances_included": true
  }
}

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.

Card customers are separate from WaaS customers. This endpoint returns all customer card records regardless of onboarding stage. For wallet sub-accounts (crypto deposits/withdrawals/transfers), see WaaS Customers.
​
Authorization
string
required
Bearer token: Bearer YOUR_ACCESS_TOKEN
​
page
integer
Page number. Defaults to 1.
​
limit
integer
Results per page. Defaults to 20, max 100.
​
status
string
Filter by onboarding status. One of: otp_requested, otp_verified, kyc_initiated, kyc_completed, card_created, active.
​
include_balances
boolean
Include balance fields for each customer’s account wallet. Defaults to true. Pass false for faster responses when balances are not needed.
curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "success": true,
  "data": {
    "customers": [
      {
        "customer_id": "69f0bdf29a84752db9cc8ff9",
        "yativo_card_id": "yativo_card_customer_8f9a..._1769031332068",
        "external_customer_id": "usr_8821",
        "email": "alice@yourapp.com",
        "flow_status": "active",
        "step": 6,
        "next_action": "Card is active — customer can spend",
        "safe_deployed": true,
        "currency": "USD",
        "ledger_balance": 45.23,
        "available_balance": 38.50,
        "pending_balance": 6.73,
        "balance_freshness": "realtime",
        "cards_count": 1,
        "created_at": "2026-04-20T08:00:00.000Z"
      },
      {
        "customer_id": "6627f3a2c5d4e100123abcde",
        "yativo_card_id": "yativo_card_customer_ab12..._1769031332999",
        "external_customer_id": "usr_7714",
        "email": "bob@yourapp.com",
        "flow_status": "kyc_initiated",
        "step": 3,
        "next_action": "Awaiting KYC verification",
        "safe_deployed": false,
        "currency": null,
        "ledger_balance": null,
        "available_balance": null,
        "pending_balance": null,
        "balance_freshness": null,
        "cards_count": 0,
        "created_at": "2026-04-25T10:00:00.000Z"
      }
    ],
    "total": 87,
    "page": 1,
    "limit": 20,
    "balances_included": true
  }
}

​
Balance fields

Each customer object includes three balance fields (all null when the wallet is not deployed or include_balances=false):
FieldDescription
ledger_balanceTotal token balance in the customer’s account wallet
available_balanceSpendable balance after deducting pending authorizations
pending_balanceAmount held for authorized but not yet settled transactions
balance_freshness"realtime" when sourced from live card notifications, "on_chain" when fetched directly from the blockchain
Balances are updated in real time whenever the card provider sends a balance change notification (e.g. after a card purchase). For wallets where no such notification has been received yet, a live on-chain query is made as a fallback — in that case available_balance equals ledger_balance since pending information is not available from the chain alone.

​
Onboarding stages

flow_statusstepnext_action
otp_requested1Customer must verify the OTP sent to their email
otp_verified2Complete KYC — call the kyc-link endpoint
kyc_initiated3Awaiting KYC verification
kyc_completed4Submit source-of-funds questionnaire
safe_deploying5Account wallet is being deployed — wait a few minutes
card_created / active6Card is active — customer can spend

​
Using customer identifiers

The id field is the canonical identifier for a customer card record. You can also use yativo_card_id, external_customer_id, or email interchangeably in endpoints that accept a customer identifier (e.g. Fund Customer, Look Up Customer). Customers with safe_deployed: false cannot be funded yet — the account wallet deploys automatically once KYC is approved.