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