Skip to main content
POST
https://services-staging.bitmama.io/api
/
v2
/
partner
/
card
/
users
curl -X POST https://services-staging.bitmama.io/api/v2/partner/card/users \
  -H "Authorization: Bearer sk_staging_your_api_key" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phoneNumber": "+14155555555",
    "accountPurpose": "personal use",
    "ipAddress": "203.0.113.42",
    "isTermsOfServiceAccepted": true,
    "program": "custodial"
  }'

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "serviceId": "acme-rain-user-abc123def456ghi",
    "verificationUrl": "https://withpersona.com/verify?inquiry-id=inq_abc123..."
  }
}
Creates a new user and initiates KYC verification through Persona. Returns a verificationUrl where the user completes identity verification. This is the v2 flow using Persona for KYC — it requires fewer fields than the legacy v1 endpoint and provides a smoother verification experience.
​
Authorization
string
required
Bearer token. Example: Bearer sk_staging_your_api_key
​
idempotency-key
string
required
Unique key to prevent duplicate user creation. Use a UUID.
​
firstName
string
required
User’s first name. 1-100 characters.
​
lastName
string
required
User’s last name. 1-100 characters.
​
email
string
required
User’s email address. Must be unique across your partner account.
​
phoneNumber
string
required
International phone number. Example: +14155555555
​
accountPurpose
string
required
Purpose of the account. 1-200 characters. Example: personal use, business expenses.
​
ipAddress
string
required
User’s IP address at the time of registration.
​
isTermsOfServiceAccepted
boolean
required
Must be true. Confirms the user has accepted the terms of service.
​
program
string
required
Card program type. Either custodial or non_custodial.
​
walletAddress
string
Ethereum wallet address. Required if program is non_custodial.
​
redirectUrl
string
HTTPS URL to redirect the user after Persona verification. Overrides the default redirect URL set in your profile.
curl -X POST https://services-staging.bitmama.io/api/v2/partner/card/users \
  -H "Authorization: Bearer sk_staging_your_api_key" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phoneNumber": "+14155555555",
    "accountPurpose": "personal use",
    "ipAddress": "203.0.113.42",
    "isTermsOfServiceAccepted": true,
    "program": "custodial"
  }'

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "serviceId": "acme-rain-user-abc123def456ghi",
    "verificationUrl": "https://withpersona.com/verify?inquiry-id=inq_abc123..."
  }
}

​
After User Creation

  1. Redirect the user to the verificationUrl to complete Persona KYC
  2. After verification, the user is redirected to your configured redirect URL with ?referenceId={serviceId}
  3. Listen for KYC webhook events to know when the user is approved
  4. Once approved (user.kyc.approved), you can create a card for the user