Provider App Integration
This document is a guide for integrating Provider Apps as network participants on the UBI Network. Providers are responsible for publishing benefits, receiving applications from seekers, validating them using eligibility and verification SDKs, and confirming or rejecting applications.
Sequence of API Calls
on_search → Respond to beneficiary search with available benefits.
on_select → Confirm selected benefit details.
on_init → Verify eligibility and initialize application.
on_confirm → Approve or reject application.
Integration Flow
Receive Search Request (from Seeker via UBI Network).
Respond with Benefit Catalog (
on_search).Handle Selection (
on_select) → return details + form schema.Initialize Application (
on_init) → validate user + eligibility + docs.Confirm Application (
on_confirm) → finalize approval/rejection.
API References
1. on_search API – Return Available Benefits
Purpose: Respond to seeker’s benefit search query.
Input: Search payload from seeker.
Output: List of available benefits with metadata (title, description, eligibility, sponsoring entities, documents).
Endpoint
POST https://<BAP-URI>/on_searchSample Response
{
"context": {
"domain": "ubi:financial-support",
"action": "on_search",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.provider.com",
"bpp_uri": "https://dev-uba-bpp.provider.com/",
"bap_id": "dev-uba-bap.provider.com",
"bap_uri": "https://dev-uba-bap.provider.com/",
"transaction_id": "9278060e-562b-4616-a4a9-75dd85425e65",
"message_id": "18534162-08a6-4d85-8cf1-ab5fa3782398",
"timestamp": "2025-09-16T07:09:31.025Z",
"ttl": "PT10M",
"location": {
"country": { "name": "India", "code": "IND" },
"city": { "name": "Bangalore", "code": "std:080" }
}
},
"message": {
"catalog": {
"descriptor": { "name": "Protean DSEP Scholarships and Grants BPP Platform" },
"providers": [
{
"id": "PROVIDER_UNIFIED",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Multiple scholarships offered"
},
"categories": [
{ "id": "CAT_SCHOLARSHIP", "descriptor": { "code": "scholarship", "name": "Scholarship" } }
],
"items": [
{
"id": "ohleagovqoattadq72mlhe4y",
"descriptor": {
"name": "ADIP - Assistance To Disabled Persons",
"long_desc": "Scheme provides aids and devices for PwDs."
},
"price": { "currency": "INR", "value": "0" }
}
]
}
]
}
}
}
2. on_select API – Return Benefit Details + Form Schema
Purpose: Provide details of a selected benefit.
Input: Seeker’s selected benefit ID.
Output:
Detailed benefit info.
Application form schema (form fields, types, validation rules).
👉 This form schema must be sent in the response, as seekers will load the form URL in their app (iframe).
Endpoint
POST https://<BAP-URI>/on_selectSampe Response
{
"context": {
"domain": "ubi:financial-support",
"action": "on_select",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.provider.com",
"bpp_uri": "https://dev-uba-bpp.provider.com/",
"bap_id": "dev-uba-bap.provider.com",
"bap_uri": "https://dev-uba-bap.provider.com/",
"transaction_id": "1f750d37-8111-4d06-b929-c3148987d78c",
"message_id": "4aa1f187-92b6-4e93-818e-5321ce82d84a",
"timestamp": "2025-08-01T12:10:35.394Z",
"ttl": "PT10M",
"location": {
"country": { "name": "India", "code": "IND" },
"city": { "name": "Bangalore", "code": "std:080" }
}
},
"message": {
"order": {
"items": [
{
"id": "uuzx97qeybdwjjwj02vmda7u",
"descriptor": {
"name": "Ekstep Disability Support Scheme - Test",
"long_desc": "This scheme supports students with disabilities."
},
"price": { "currency": "INR", "value": "0" }
}
],
"provider": { "id": "PROVIDER_UNIFIED", "descriptor": { "name": "Scholarlify" } }
}
}
}
3. on_init API – Initialize Application
Purpose: Validate initial application request.
Input: User profile (from VCs), filled application form, supporting documents.
Processing:
Optionally use Eligibility SDK to check user eligibility.
Optionally use Verification SDK to validate authenticity of submitted VCs.
Output: Application status + form URL (if additional steps needed).
Endpoint
POST https://<BAP-URI>/on_initSample Response
{
"context": {
"domain": "ubi:financial-support",
"action": "on_init",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.provider.com",
"bpp_uri": "https://dev-uba-bpp.provider.com/",
"bap_id": "dev-uba-bap.provider.com",
"bap_uri": "https://dev-uba-bap.provider.com/",
"transaction_id": "0206a019-69c6-46ce-bc64-06cc605b37aa",
"message_id": "c9eff9ef-6502-4638-8f6e-801e77b243f1",
"timestamp": "2025-08-01T12:10:10.468Z",
"ttl": "PT10M",
"location": {
"country": { "name": "India", "code": "IND" },
"city": { "name": "Bangalore", "code": "std:080" }
}
},
"message": {
"order": {
"items": [
{
"id": "uuzx97qeybdwjjwj02vmda7u",
"descriptor": {
"name": "Ekstep Disability Support Scheme - Test",
"long_desc": "This scheme supports students with disabilities."
},
"price": { "currency": "INR", "value": "0" }
}
]
}
}
}
4. on_confirm API – Finalize Application
Purpose: Confirm the application and return final acknowledgment.
Input: Completed application payload (user data, docs, VCs).
Processing: Approve or reject based on internal checks.
Output: Confirmation response (approved/rejected + remarks).
Endpoint
POST https://<BAP-URI>/on_confirmSample Response
{
"context": {
"domain": "ubi:financial-support",
"action": "on_confirm",
"version": "1.1.0",
"bpp_id": "dev-uba-bpp.provider.com",
"bpp_uri": "https://dev-uba-bpp.provider.com/",
"bap_id": "dev-uba-bap.provider.com",
"bap_uri": "https://dev-uba-bap.provider.com/",
"transaction_id": "cb63b4a2-122d-40e6-bc0c-0a3fd3ec9c11",
"message_id": "7f01a16a-0d3f-4a9a-9324-9ea11eafaa82",
"timestamp": "2025-09-15T11:35:42.510Z",
"ttl": "PT10M",
"location": {
"country": { "name": "India", "code": "IND" },
"city": { "name": "Bangalore", "code": "std:080" }
}
},
"message": {
"order": {
"id": "ORDER_123456",
"status": "CONFIRMED",
"provider": {
"id": "PROVIDER_UNIFIED",
"descriptor": {
"name": "Ministry of Social Justice and Empowerment",
"short_desc": "Scholarship and welfare schemes"
}
},
"items": [
{
"id": "uuzx97qeybdwjjwj02vmda7u",
"descriptor": {
"name": "Ekstep Disability Support Scheme - Test",
"long_desc": "This scheme supports students with disabilities."
},
"price": { "currency": "INR", "value": "0" }
}
],
"fulfillments": [
{
"id": "FULFILLMENT_123",
"type": "Application",
"state": { "descriptor": { "code": "submitted", "name": "Submitted" } },
"customer": {
"person": {
"name": "Aman Gupta",
"gender": "male",
"dob": "1990-01-01"
},
"contact": { "phone": "9999999999", "email": "user@example.com" }
}
}
]
}
}
}
Last updated