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 (Authentication)
• ✅ You have your API credentials ready

User Lifecycle

graph LR
    A[Create User] --> B[Initiate Verification]
    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
• Retrieve user information
• Update user data
• Handle user types and statuses

Key endpoints:

• POST /v1/users - Create user
• GET /v1/users/{userId} - Get user details

2. Identity Verification (KYC/KYB)

📖 Verification Guide

Learn how to:

• Initiate KYC verification for individuals
• Initiate KYB verification for businesses
• Use embedded link verification mode
• Use API verification mode
• Track verification status
• Handle verification webhooks

Key endpoints:

• POST /v1/users/{userId}/verifications - Create verification session

User Types

Individual Users

For persons who will receive payments directly.

Required information:

• First name, last name
• Email, phone number
• Date of birth
• Country and address
• Government ID for verification

Use cases:

• Freelancers
• Contractors
• Individual service providers

Business Users

For companies and organizations.

Required information:

• Business name
• Tax ID (EIN)
• Business address
• Email, phone number
• Beneficial owner information

Use cases:

• Small businesses
• Corporations
• Partnerships

Verification Status Flow

Quick Example

# 1. Create user
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_number": "+1234567890",
    "first_name": "John",
    "last_name": "Doe",
    "country": "US"
  }'

# 2. Initiate verification
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": "95fbd1c9-46cf-405c-bf38-a28344ff4707",
    "user_id": "6487276d-e86c-46ad-bc7b-afe43310ae01",
    "type": "individual",
    "email": "[email protected]",
    "phone": "+573013185684",
    "status": "active",
    "verification_status": "unverified",
    "created_at": "2026-01-14 20:27:54.863",
    "metadata": {}
  }
}

2. Verification Accepted

Sent when user verification is approved:

{
  "event": "user.verification.accepted",
  "data": {
    "event_id": "ebd2325e-f16d-4917-8a83-7dcb3a2ebf73",
    "id": "ebd2325e-f16d-4917-8a83-7dcb3a2ebf73",
    "user_id": "147ba2c0-0637-4949-b0e2-f89d228b69c8",
    "verification_status": "verified",
    "kyc_type": "simplified",
    "tier": 1
  }
}

Note: kyc_type can be either "simplified" or "full" depending on the verification level.

3. Verification Failed

Sent when user verification is rejected:

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

Note: The reasons array provides details about why verification failed, including both 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
• Full Verification Guide: verification