List Card Customers

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

curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers?status=kyc_initiated' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers?include_balances=false' \
  -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
  }
}

{
  "success": false,
  "error": "NOT_APPROVED",
  "message": "Card issuer program not approved"
}

GET

card-issuer

customers

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

curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers?status=kyc_initiated' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers?include_balances=false' \
  -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
  }
}

{
  "success": false,
  "error": "NOT_APPROVED",
  "message": "Card issuer program not approved"
}

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.

string

required

Bearer token: Bearer YOUR_ACCESS_TOKEN

integer

Page number. Defaults to 1.

integer

Results per page. Defaults to 20, max 100.

string

Filter by onboarding status. One of: otp_requested, otp_verified, kyc_initiated, kyc_completed, card_created, active.

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'

curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers?status=kyc_initiated' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

curl -X GET 'https://crypto-api.yativo.com/api/v1/card-issuer/customers?include_balances=false' \
  -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
  }
}

{
  "success": false,
  "error": "NOT_APPROVED",
  "message": "Card issuer program not approved"
}

Balance fields

Each customer object includes three balance fields (all null when the wallet is not deployed or include_balances=false):

Field	Description
`ledger_balance`	Total token balance in the customer’s account wallet
`available_balance`	Spendable balance after deducting pending authorizations
`pending_balance`	Amount 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_status`	`step`	`next_action`
`otp_requested`	1	Customer must verify the OTP sent to their email
`otp_verified`	2	Complete KYC — call the kyc-link endpoint
`kyc_initiated`	3	Awaiting KYC verification
`kyc_completed`	4	Submit source-of-funds questionnaire
`safe_deploying`	5	Account wallet is being deployed — wait a few minutes
`card_created` / `active`	6	Card 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.

Overview

Authentication

Accounts

Assets

Transactions

Swap

Yativo Card (Own Account)

Card Customer — Onboarding

Card Customer — Card Operations

Card Issuer Program

Payment Gateway

Agentic Wallets

Unified Transactions

Auto-Forwarding

Compliance Screener

Subscriptions

IBAN

Webhooks

WaaS Customers (Wallet Sub-accounts)

Analytics

API Keys

List Card Customers

Balance fields

Onboarding stages

Using customer identifiers

​Balance fields

​Onboarding stages

​Using customer identifiers

Balance fields

Onboarding stages

Using customer identifiers