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