Integration Overview

Background & References

The UBI Network is built as a fork of the ONEST Financial Domain. The underlying Beckn-style protocol and interaction patterns remain consistent with ONEST.

For further details and foundational concepts, you can refer to the ONEST Financial Domain documentation here: 👉 ONEST Financial Domain Documentation

Network Participant Roles

Any Network Participant (NP) can onboard to the UBI Network in one of the following roles:

• Seeker (BAP) – An application that allows beneficiaries to discover and apply for benefits.

• Provider (BPP) – An application that offers benefits and processes applications.

• Dual Role (BAP + BPP) – A participant may also choose to operate as both Seeker and Provider simultaneously.

👉 For integration steps as a Seeker (BAP), refer to the Seeker Integration Guide. 👉 For integration steps as a Provider (BPP), refer to the Provider Integration Guide.

End-to-End Flow Between BAP and BPP

The UBI Network follows a standard request–response pattern between the Seeker (BAP) and Provider (BPP).

1. Search

• BAP → /search The Seeker app sends a search request to discover available benefits from providers.

• BPP → /on_search The Provider responds with a list of available benefits and basic details.

2. Select

• BAP → /select Triggered when the user selects a specific benefit to view more details.

• BPP → /on_select Provider shares:

  • Detailed benefit information

  • Eligibility criteria

  • Required documents and proof types

  • Application form schema

The BAP dynamically generates the application form using the form schema received in the /on_select response. The collected form data will later be sent in the /init call.

3. Init

• BAP → /init Initializes the application process for a selected benefit.

  Before calling /init:

  • The BAP creates an application record in its database.

  • A unique bap_application_id is generated and included in the /init request.

  • It is recommended to store:

    • transaction_id

    • bap_application_id

    • benefit_id

    • bpp_id

    • user_id

    • Current application_state (e.g., initiated)

  Database Example (BAP):

  Field	Description
  bap_application_id	Unique ID generated on BAP
  transaction_id	Shared across the lifecycle of the application
  benefit_id	ID of the selected benefit
  bpp_id	Target provider BPP
  user_id	Beneficiary identifier
  status	Initiated / Confirmed / Approved / Rejected
  order_id	Received from BPP (post /on_init)

• BPP → /on_init When the BPP receives the /init request:

  • It creates a new application record in its database.

  • It should store:

    • bap_application_id

    • transaction_id

    • bap_id

    • user_id

    • Application metadata (VCs, form data, etc.)

  The BPP then returns a response with:

  • order_id (to be stored by the BAP)

  • Application form metadata or confirmation URL (if required)

4. Confirm

• BAP → /confirm The Seeker app submits the completed application form along with user Verifiable Credentials (VCs).

• BPP → /on_confirm The Provider:

  • Validates submitted data and VCs using the Verification SDK

  • Creates or updates an internal application record

  • Returns a response including:

    • bpp_application_id

    • order_id

    • Application status (e.g., received, in-progress, approved, rejected)

The bpp_application_id returned must be stored by the BAP for reference and tracking.

5. Update (Optional)

If a user resubmits or modifies an existing application:

• BAP → /update Sends updated form data or documents for an existing transaction.

• BPP → /on_update Updates the stored application record and returns acknowledgment.

6. Status

• BAP → /status The Seeker queries the current state of a submitted application.

• BPP → /on_status The Provider returns:

  • application_status (e.g., in-progress, approved, rejected)

  • Associated benefit and form metadata

  • Any remarks or rejection reasons

This flow ensures smooth interaction between seekers and providers, with clear hand-offs at each stage.