Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pcxpay.com/llms.txt

Use this file to discover all available pages before exploring further.

The User Service is the identity backbone of the PCX platform. It owns every user record from initial sign-up through KYC approval and ongoing lifecycle management.

​
What it does

Registration & confirmation — Users register via Cognito (POST /users/register). Cognito sends a verification email; the user confirms with a code (POST /users/confirm). An optional org_name or org_id wires the user into an organization at the same time. Profile management — Standard CRUD for user records. Mutable fields (name, phone, address, ID documents) are updated via PUT /users/{user_id}. Role and status changes go through dedicated endpoints so they can be audited separately. KYC lifecycle — The service integrates with two KYC providers:
  • Veriff (or equivalent) — webhook callback at POST /users/webhook-kyc updates status after a session completes.
  • Bridge — POST /users/{user_id}/bridge-kyc creates a Bridge customer and returns a terms-of-service link; Bridge status transitions arrive at POST /users/webhook/kyc.
Verification data requests — For Nigeria-specific compliance (BVN/NIN), a sub-system tracks requests sent to users and beneficiaries. Admins trigger notifications (POST /users/notifications/verification-request), users submit their numbers (POST /users/verification-requests/submit), and the lifecycle is tracked in VerificationRequest records. Notifications — Internal systems call POST /users/notifications/kyc to push KYC status updates to users via email, SMS, and push channels through the notifications Lambda. Analytics — Nine admin-only analytics endpoints give visibility into active user counts, growth trends, KYC funnel progression, status/role distributions, transaction averages, and geographic spread.

​
Key concepts

ConceptDescription
UserStatusnot_verified → pending_verification → active or rejected. Also pending, sandbox, inactive.
UserRoleretail, freelancer, org-staff, admin, super-admin.
UserTypeuser, staff, merchant, org-admin, internal-admin.
IDTypepassport, drivers_license, national_id, other.
VerificationRequestTracks a BVN/NIN request from creation through submission and verification.

​
Authentication

All endpoints except POST /users/register and POST /users/confirm require a valid Bearer token. Analytics endpoints and admin status-change endpoints additionally enforce the internal-admin role via the roles_required middleware.