Customer Statuses

​

Overview

The customer verification engine manages customer verification through a well-defined state machine with six statuses. Understanding these statuses helps you build better integrations and provide clear user experiences. Each status represents a distinct phase in the verification lifecycle, from initial creation through final approval or rejection. Every customer has a customerStatus field that indicates their current verification status. This status determines what actions you can perform and what your customer can access on your platform. Related guides:

• For verification process see Verification workflow
• For webhook notifications see Webhook integration
• For API operations see Customer API

​

Status overview

The six possible statuses represent different phases of the verification lifecycle:

​

Status definitions

​

CREATED

What it means: Customer profile has been created but verification has not started yet. Characteristics:

• No verification process initiated
• Customer data collection phase
• All fields can be freely updated
• Default status for new customers

Developer actions:

• Use PATCH customers/:id to update customer data
• Add or update KYC/KYB information
• Upload identity documents
• Prepare customer for verification submission

When it transitions:

• Customer data is submitted and verification is automatically initiated
• Status changes to UNDER_REVIEW when verification begins

​

UNDER_REVIEW

What it means: Customer verification is actively being processed. Characteristics:

• Verification submission has been sent to providers
• Identity and compliance checks are in progress
• Customer data is locked to maintain submission integrity
• No action required from developer (monitoring only)

Developer actions:

• Monitor status via GET customers/:id
• Set up webhooks to receive status change notifications
• Display “Verification in progress” status to user
• Cannot update customer data (PATCH will return error)

When it transitions:

• To ACTIVE: All verification checks pass
• To NEEDS_ADDITIONAL_INFORMATION: Provider requests more information

Typical duration: Less than 10 minutes for individuals (1 to 3 business days if manual intervention is required), 4-7 business days for businesses

​

NEEDS_ADDITIONAL_INFORMATION

What it means: The verification provider requires additional information, documents, or clarifications (Request for Information - RFI). Characteristics:

• Verification process is reset as critical details require correcting
• Specific issues or missing data have been flagged
• Customer must take action to proceed

Developer actions:

• Use PATCH customers/:id to update customer data
• Upload additional documents
• Review webhook payload for specific requirements
• After updates, verification automatically re-submits

Common reasons for RFI:

• Missing or expired identity documents
• Unclear business ownership structure
• Insufficient address verification
• Ambiguous beneficial owner information
• Document quality issues (blurry images, partial visibility)

Recovery process:

1. Receive RFI notification via webhook or API polling
2. Review requirements indicated in the response
3. Update customer data using PATCH endpoint
4. Verification automatically re-initiates after update
5. Status transitions to UNDER_REVIEW when resubmitted

​

ACTIVE

What it means: Customer has successfully completed verification and is approved for platform use. Characteristics:

• All verification checks passed
• Customer is fully verified
• Can perform transactions and operations
• Full platform access granted

Developer actions:

• Enable all platform features for the customer
• Allow transaction creation
• Grant access to payment operations
• Display verification success status
• Cannot update core customer data (contact support for changes)

When it transitions:

• To DEACTIVATED: Account is administratively closed
• To REJECTED: Post-approval compliance issues detected (rare)

​

REJECTED

What it means: Customer verification has permanently failed and cannot be approved. Characteristics:

• Verification process ended negatively
• Customer cannot use platform services
• Typically due to compliance or identity verification issues
• Account closure or manual review may be required

Developer actions:

• Display rejection status to customer
• Provide support contact information
• Log rejection for compliance records
• Cannot update customer data
• Cannot re-initiate verification (contact support)

Common reasons:

• Identity documents could not be verified
• Compliance concerns or sanctions list matches
• Fraudulent information detected
• Regulatory restrictions
• Customer-requested cancellation during verification

​

DEACTIVATED

What it means: Customer account has been administratively deactivated. Characteristics:

• Account is inactive by administrative action
• Not related to verification failure
• May be temporary or permanent
• Can potentially be reactivated (contact support)

Developer actions:

• Display deactivation status
• Prevent new transactions
• Allow view-only access to historical data
• Provide reactivation contact information
• Cannot update customer data
• Cannot create new transactions

Common reasons:

• Customer requested account closure
• Compliance hold or investigation
• Regulatory requirement
• Inactivity-based closure
• Terms of service violation

​

Status transition diagram

​

Transition summary

​

Testing customer statuses

​

Test checklist

Test your integration handles all statuses:

• CREATED - Show profile completion UI
• UNDER_REVIEW - Show waiting/progress indicator
• NEEDS_ADDITIONAL_INFORMATION - Show RFI resolution flow
• ACTIVE - Enable full platform features
• REJECTED - Show support contact and disable features
• DEACTIVATED - Show reactivation contact and disable transactions

​

Frequently asked questions

​

How long does verification take?

• Individuals (KYC): Typically under 10 minutes
• Businesses (KYB): Typically 4-7 business days
• Complex cases may take longer

​

Can I expedite verification?

Contact your account manager to discuss expedited processing options for your use case.

​

What happens if verification fails?

If verification transitions to NEEDS_ADDITIONAL_INFORMATION, you can provide the requested information and resubmit. If it transitions to REJECTED, contact support.

​

Can I update customer data after approval?

Once a customer is ACTIVE, profile data cannot be updated via the API. Contact support for approved customer data changes.

​

How do I handle RFI situations?

1. Monitor for NEEDS_ADDITIONAL_INFORMATION status
2. Review webhook payload or API response for specific requirements
3. Update customer data with requested information
4. System automatically re-submits for verification

​

What is the difference between REJECTED and DEACTIVATED?

• REJECTED: Verification failed due to identity or compliance issues
• DEACTIVATED: Administrative account closure unrelated to verification failure