Users and verification

Overview

This section covers creating and managing users, as well as the identity verification (KYC/KYB) process required before users can create virtual accounts.

Prerequisites

• ✅ You have authenticated and obtained an access token (Getting Started)
• ✅ You have your API credentials ready

User Lifecycle

Kira supports two verification flows:

Recommended: Automatic Verification

When you create a user with all required fields, the verification process starts automatically in the background. No additional API calls are needed.

graph LR
    A[Create User with Required Fields] --> B{Fields Complete?}
    B -->|Yes| C[Automatic KYC/KYB Triggered]
    B -->|No| D[User Created - Unverified]
    C --> E[Background Verification]
    E --> F{Verification Status}
    F -->|Approved| G[User Verified]
    F -->|Rejected| H[Review & Retry]
    G --> I[Can Create Virtual Accounts]

Legacy: Manual Verification

You can also trigger verification manually after creating a user. This flow will be deprecated in a future release.

graph LR
    A[Create User] --> B[Initiate Verification Manually]
    B --> C[User Completes KYC/KYB]
    C --> D{Verification Status}
    D -->|Approved| E[User Verified]
    D -->|Rejected| F[Review & Retry]
    E --> G[Can Create Virtual Accounts]

Guides in This Section

1. User Management

📖 User Management Guide

Learn how to:

• Create individual and business users with automatic verification
• Understand required fields for automatic KYC/KYB
• Retrieve user information
• Update user data
• Handle user types and statuses

Key endpoints:

• POST /v1/users - Create user (triggers automatic verification if all required fields are provided)
• GET /v1/users/{userId} - Get user details
• PUT /v1/users/{userId} - Update user

2. Identity Verification (KYC/KYB)

📖 Verification Guide

Learn how to:

• Understand automatic verification (recommended)
• Initiate manual KYC verification for individuals (legacy)
• Initiate manual KYB verification for businesses (legacy)
• Track verification status
• Handle verification webhooks

Key endpoints:

• POST /v1/users/{userId}/verifications - Create verification session (legacy - for manual verification only)

User Types

Individual Users

For persons who will receive payments directly.

Use cases:

• Freelancers
• Contractors
• Individual service providers

Business Users

For companies and organizations.

Use cases:

• Small businesses
• Corporations
• Partnerships

User Status Flow

Quick Example

Recommended: Automatic Verification

Create a user with all required fields - verification starts automatically:

curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: user-123" \
  -d '{
    "type": "individual",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "birth_date": "1990-01-15",
    "ssn": "123-45-6789",
    "document_type": "passport",
    "document_number": "AB1234567",
    "document_country": "USA",
    "address_street": "123 Main St",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_zip_code": "94105",
    "address_country": "USA"
  }'

# Response includes verification_triggered: true if automatic verification was started

Legacy: Manual Verification

If you prefer to trigger verification manually (will be deprecated):

# 1. Create user (without all required fields)
curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: user-123" \
  -d '{
    "type": "individual",
    "email": "[email protected]",
    "phone": "+1234567890",
    "first_name": "John",
    "last_name": "Doe"
  }'

# 2. Initiate verification manually
curl -X POST https://api.balampay.com/v1/users/{userId}/verifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: verification-123" \
  -d '{
    "type": "embedded-link",
    "redirect_uri": "https://yourapp.com/verification-complete"
  }'

# Response includes provider_link where user completes verification

Webhooks

Receive real-time updates about user and verification events:

1. User Created

Sent when a new user is created:

{
  "event": "user.created",
  "data": {
    "event_id": "061cc7aa-4a31-4d49-aada-f5b44ef08e17",
    "type": "individual",
    "email": "[email protected]",
    "phone": "+5215512345678",
    "status": "CREATED",
    "user_id": "e9610a11-d514-4587-85dc-e18e2b461e55",
    "created_at": "2026-02-02 20:01:34.249",
    "verification_triggered": true
  }
}

Key fields:

• verification_triggered: true if automatic verification was started, false otherwise

2. Verification Accepted

Sent when user verification is approved:

{
  "event": "user.verification.accepted",
  "data": {
    "event_id": "ec538bcc-53e3-4d1b-bb8b-0e8cfd6e6aac",
    "user_id": "e9610a11-d514-4587-85dc-e18e2b461e55",
    "status": "VERIFIED",
    "verified_fields": [
      "first_name",
      "last_name",
      "date_of_birth",
      "document_type",
      "document_number",
      "document_country",
      "address_street",
      "address_city",
      "address_state",
      "address_zip_code"
    ]
  }
}

Key fields:

• status: User verification status (VERIFIED)
• verified_fields: List of fields that were verified

3. Verification Failed

Sent when user verification is rejected:

{
  "event": "user.verification.failed",
  "data": {
    "event_id": "ee8e3df9-6ad8-40d6-81de-ddea5399d011",
    "user_id": "8d05b02e-9d15-46d6-bb33-9c81d461a969",
    "status": "REJECTED",
    "reasons": [
      {
        "reason": "Your information could not be verified",
        "developer_reason": "Inconsistent details between submissions.",
        "created_at": "2026-01-14T03:44:00.884Z"
      }
    ]
  }
}

Key fields:

• status: User verification status (REJECTED)
• reasons: Array with details about why verification failed (user-facing and developer-facing explanations)

See the Webhooks Guide for setup instructions.

Next Steps

Once users are verified:

1. Create Virtual Accounts - Set up virtual accounts
2. Track Deposits - Monitor incoming payments
3. Set up Webhooks - Get real-time notifications

Support

• Email: [email protected]
• Full User Guide: users.md
• Full Verification Guide: verification.md