Skip to main content
POST
/
v1
/
yativo-card
/
customers
/
onboard
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/customers/onboard' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "external_customer_id": "usr_8821"
  }'

{
  "success": true,
  "message": "Customer card onboarding initiated. Verification code sent to customer email.",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a2b3c4d5e6f7a8b9c0d1e_1769031332068",
    "customer_id": "6627f3a2c5d4e100123abcde",
    "external_customer_id": "usr_8821",
    "email_masked": "cu***@example.com",
    "next_step": "verify_otp",
    "otp_expires_in_seconds": 600
  }
}

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.

Issuer program required. This endpoint is only available to users with an approved Card Issuer Program. Each customer gets a dedicated yativo_card_id used for all subsequent onboarding steps.
​
Authorization
string
required
Bearer token: Bearer YOUR_ACCESS_TOKEN
​
email
string
required
The customer’s email address. Yativo sends a one-time verification code to this address. Must be unique per active customer card under your account — you cannot reuse your own issuer account email.
​
external_customer_id
string
Your own reference ID for this customer (e.g., a user ID from your platform). Stored as-is and returned on all customer records so you can correlate them on your side. No two active customer sessions may share the same external_customer_id under your account.
curl -X POST 'https://crypto-api.yativo.com/api/v1/yativo-card/customers/onboard' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "external_customer_id": "usr_8821"
  }'

{
  "success": true,
  "message": "Customer card onboarding initiated. Verification code sent to customer email.",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a2b3c4d5e6f7a8b9c0d1e_1769031332068",
    "customer_id": "6627f3a2c5d4e100123abcde",
    "external_customer_id": "usr_8821",
    "email_masked": "cu***@example.com",
    "next_step": "verify_otp",
    "otp_expires_in_seconds": 600
  }
}

​
Response Fields

FieldTypeDescription
yativo_card_idstringUnique customer card identifier. Save this — required for every subsequent onboarding call.
customer_idstringInternal Yativo database ID for this customer record.
external_customer_idstring | nullYour reference ID, echoed back unchanged.
email_maskedstringPartially masked version of the customer’s email for display purposes.
next_stepstringAlways "verify_otp" on creation.
otp_expires_in_secondsnumberHow long the emailed code is valid (600 = 10 minutes).

​
Idempotency

If you call this endpoint again with the same external_customer_id or the same email while an active session already exists, the API returns a 409 with the existing yativo_card_id instead of creating a duplicate. Use the returned ID to resume the onboarding flow. If the customer has already completed onboarding (flow_status is active, safe_deployed, or kyc_approved), the API returns 409 CUSTOMER_ALREADY_ONBOARDED with next_step: "none" — no further action is needed for this customer.

​
Next Steps

After a 201 response, direct your customer to check their email and proceed:
  1. Verify OTP — POST /v1/yativo-card/customers/{yativoCardId}/verify-otp
  2. Get KYC link — GET /v1/yativo-card/customers/{yativoCardId}/kyc-link
  3. Poll KYC status — GET /v1/yativo-card/customers/{yativoCardId}/kyc-status
  4. Submit source of funds — POST /v1/yativo-card/customers/{yativoCardId}/source-of-funds
  5. Create virtual card — POST /v1/yativo-card/customers/{yativoCardId}/cards/virtual