Skip to content
Last updated

End-to-End Flow: Incremental KYC Upgrade

This flow applies when a user cannot proceed with a transaction because KYC information is required. This includes first-time users whose initial transaction requires KYC and returning users who need to satisfy additonal requirements.

It covers:

  • New users above KYC free levels
  • Returning users attempting a higher-risk transaction
  • Users whose transaction context has changed (amount, payment method, jurisdiction)

The key signal for this flow is an eligibility response where:

  • paymentReady = false
  • requirements is non-empty

When This Flow Is Used

This flow is triggered when eligibility determines that the current transaction cannot proceed without additional identity information.

Common triggers include:

  • Higher transaction amounts
  • Different payment methods
  • Regulatory or jurisdictional requirements
  • Escalation beyond previously completed KYC

Previously submitted identity information is retained and reused.
The identity is not recreated.

End-to-End Flow Diagram

Banxa Native_incremental_kyc.png

Step-by-Step Flow

1. User Requests Pricing

The user requests pricing or a quote for a buy or sell transaction.

This establishes the transaction context, including:

  • Buy or sell direction
  • Amount
  • Asset pair
  • Intended payment method

2. Ensure an Identity Reference Is Available (Before Ramp Creation)

The partner ensures there is a persistent identityReference available to use before creating an order / ramp.

  • For returning users, the existing identityReference is reused.
  • For first-time users, an identityReference can be established either by:
    • creating a basic identity record, or
    • completing KYC provider token sharing (currently Sumsub), which links KYC results to the user’s identity.

Once established, the same identityReference is reused for eligibility checks and any subsequent identity updates. The identity must not be recreated once it exists.

3. Check Eligibility

The partner checks eligibility using:

  • identityReference
  • Transaction parameters (amount, payment method, jurisdiction)

Eligibility evaluates whether the transaction can proceed in its current form.

4. Eligibility Returns Additional Requirements

Eligibility responds with:

  • paymentReady = false
  • One or more entries in requirements

Each requirement represents a category of information that must be satisfied before the transaction can proceed.

Examples include:

  • OCCUPATION
  • SOURCE_FUNDS
  • PURPOSE_OF_TX
  • DOCUMENT
  • SELFIE
  • POA

Previously completed verification is not invalidated.
Only missing information is returned.

5. Collect and Submit Required Information

The partner is responsible for collecting the required information in their own user experience and submitting it to Banxa using the appropriate mechanism for the requirement.

Notes:

  • Multiple requirements may be returned at once
  • All required information can be collected in a single user interaction where possible
  • The identityReference is reused and must not be recreated

Submission methods

Banxa supports the following fulfilment mechanisms:

  • Update identity via API (patch identity)
    Used for structured information and supported evidence submission, including:

    • PERSONAL_DETAILS
    • OCCUPATION
    • SOURCE_FUNDS
    • PURPOSE_OF_TX
    • TIN / US_TAX_ID
    • DOCUMENT
    • POA

  • KYC provider token sharing (currently Sumsub)
    Used when a selfie or liveness step is required:

    • SELFIE

If a required verification step cannot be completed headlessly, a Banxa-hosted step (for example, a webview) may be required.

Order of submission

If multiple requirements are returned:

  1. If SELFIE is required, complete KYC provider token sharing first.
    This may satisfy multiple verification requirements in a single step, depending on the provider configuration.

  2. Submit all remaining structured fields and supported evidence via the identity update endpoint.

6. Re-Check Eligibility

After submitting the required information, the partner must re-run eligibility.

Eligibility is evaluated dynamically and may reflect:

  • Verification completion
  • Asynchronous checks
  • Remaining unmet requirements

A successful outcome is:

  • paymentReady = true
  • requirements = []

Upcoming: KYC Status Endpoint (Coming Soon)

To provide clearer visibility into verification progress, Banxa is introducing a dedicated KYC status endpoint.

This endpoint will allow partners to:

  • Poll the current verification status for an identity
  • Determine when KYC checks have completed
  • Confirm approval before creating a ramp

Until this endpoint is available, eligibility remains the authoritative signal and should be re-checked after submitting identity information.

The KYC status endpoint will be optional and is intended to improve UX and orchestration for partners managing their own onboarding flows.

7. Continue Transaction Flow

Once paymentReady = true, the partner proceeds with ramp creation using the appropriate integration path:

  • Bank transfer → API-driven ramp creation
  • Cards / Apple Pay / Google Pay → SDK-assisted ramp creation (for supported native mobile integrations)
  • Other payment methods → fallback or hosted flow where applicable

Transaction progress is then tracked via status updates and webhooks.

Key Integration Notes

  • Eligibility is authoritative and should always be re-checked after identity updates
  • Identity records are cumulative and must not be recreated
  • Only missing information should be collected
  • Re-running eligibility is recommended before proceeding
Previous page
Next page
Copyright © Banxa 2026. All rights reserved.