Partner APIs

OpenG2P G2P Bridge Partner API Documentation

Overview

The Partner API module (openg2p-g2p-bridge-partner-api) provides a comprehensive set of REST APIs for partner systems to interact with the G2P Bridge. The APIs handle disbursement operations, status inquiries, and account statement uploads, with all requests authenticated using JWT signature validation.

Module Location: openg2p-g2p-bridge/openg2p-g2p-bridge-partner-api

---

Authentication

All API endpoints (except account statement upload) require JWT signature validation. The signature is validated using the JWTSignatureValidator dependency from openg2p_fastapi_partner_auth.

• Validator: JWTSignatureValidator()

• Requirement: All requests must include valid JWT signatures

• Error Code on Invalid Signature: Request validation error

• Enforcement gate: enforced when signature_validation_enabled is set. The Helm chart turns this on by default (secure-by-default); disable it only for an unauthenticated demo.

For the operational steps — supplying the Bridge's signing .p12 and onboarding partner certificates — see Partner Signing Key and Onboarding Partners.

How the signature is verified

The signature mechanism is not implemented in the Bridge — it lives entirely in openg2p-fastapi-common behind the CryptoHelper interface. The Bridge uses the partner-mgmt backend (PyJWTCryptoHelper + PartnerMgmtKeyStore): it fetches the signer's public key from the Partner Manager (PM) service — no local key store, no MOSIP Keymanager (1.0.0 used Keymanager; earlier develop builds used a local partner_keys table; both are superseded by PM). See PyJWTCryptoHelper for the full design. In brief:

• The partner sends a detached JWS (header..signature) in the Signature header; the JSON business payload is the request body (the signature is over base64url(header) + "." + base64url(canonical_json(body))).

• The Bridge fetches the partner's public key from PM — GET {partner_mgmt_api_url}/keys/PARTNER_<sender_app_mnemonic> (unauthenticated, in-cluster) — matching on the JWS kid, and caches it (short TTL, refresh-on-unknown-kid). Signature validity only — no trusted-root / CA-chain check.

• RS256 only; none and HMAC (HS*) are always rejected.

The Bridge's only crypto wiring is one line in its Initializer — build_crypto_helper() — which registers the configured backend; controllers and JWTSignatureValidator are unchanged. Partners are registered in PM (see Onboarding Partners), not in the Bridge.

---

Integration with Partner Manager (PM)

The Partner Manager (PM) service is the shared registry of partners and their public signing keys. It is the single source of truth that replaced both MOSIP Keymanager (1.0.0) and the Bridge's short-lived local partner_keys table. The Bridge integrates with PM in two directions:

1. As a partner — the Bridge registers its own public key in PM (id PARTNER_G2P_BRIDGE) so that downstream services (notably SPAR) can verify the Bridge's signed calls.

2. As a verifier — the Bridge fetches partner public keys from PM to verify the signature on every inbound Partner API request.

All of this uses openg2p-fastapi-common (PyJWTCryptoHelper + PartnerMgmtKeyStore); there is no crypto or partner-key storage in the Bridge itself.

PM's two API surfaces

Surface	Config value	Auth	Used by the Bridge for
Read — partner-api	global.partnerManagementApiUrl (…-pm-partner-api)	none (in-cluster)	Fetching partner public keys at runtime (GET /keys/…)
Admin — staff-portal-api	global.partnerManagementAdminApiUrl (…-pm-staff-portal-api)	Keycloak staff-realm token holding the partner_manager role	Onboarding / approving / updating partners (the pm-register Job)

1. Seeding the Bridge's own public key (self-registration)

Done once per install/upgrade by the chart's pm-register Job (it derives the Bridge's public certificate + kid from the same signing .p12 the Bridge signs with). This is the Bridge's own responsibility — customers do not register it by hand. The onboarding flow is a two-step request → approve (idempotent):

Seeding PARTNER_G2P_BRIDGE            chart Job: <release>-pm-register
────────────────────────────────────────────────────────────────────────────

 pm-register Job     Keycloak (staff)   PM staff-portal-api    PM partner-api
 (signing .p12)      (admin token)      (admin, authorized)    (read, public)
      │                    │                    │                    │
      │ derive public cert │                    │                    │
      │ + kid from .p12    │                    │                    │
      │                    │                    │                    │
      │ (1) already servable? GET /keys/PARTNER_G2P_BRIDGE/{kid} ────►│
      │◄──────────────────────────────────────────────── 200 | 404 ──│
      │      200 → "exists", stop.   404 → onboard (below).           │
      │                    │                    │                    │
      │ (2) client-creds token (role partner_manager)                 │
      │  ─────────────────►│                    │                    │
      │◄── access_token ───│                    │                    │
      │                    │                    │                    │
      │ (3) POST /partners/requests/onboarding ►│  partner_id =      │
      │   {partner_id, name, keys:[{public_key, │  PARTNER_G2P_BRIDGE │
      │    kid, algorithm:"RS256"}]}            │                    │
      │◄────────────── {request_id} ───────────│  (409 if it exists  │
      │                    │                    │   → enable +        │
      │ (4) POST /partners/requests/{id}/approve►│   key-update)      │
      │◄──────────────────── 200 ──────────────│  partner+key ACTIVE │
      │                    │                    │                    │
      │ (5) verify servable: GET /keys/PARTNER_G2P_BRIDGE/{kid} ─────►│
      │◄──────────────────────────────────────────────────── 200 ────│
      ▼
  For the trial, the same Job also onboards the test partners
  PARTNER_TEST_SANITY / PARTNER_TRAINING from the committed test cert
  (only when testPartnerEnabled + signature validation are on).

The admin client is commons-services-staff-portal (PM provisions this <release>-staff-portal client; its service account must hold the partner_manager role for the client-credentials grant to be authorized).

2. Verifying an inbound partner signature

At runtime, every signed Partner API request is verified against the signer's public key fetched from PM's read surface — no admin token, no local key store:

Verifying an inbound partner signature          runtime, per signed request
────────────────────────────────────────────────────────────────────────────

 Partner (signs)     Bridge Partner API                       PM partner-api
                     (JWTSignatureValidator →                 (read, public)
                      PyJWTCryptoHelper + PartnerMgmtKeyStore)
      │                    │                                        │
      │ POST /create_…     │                                        │
      │  body: G2PConnect envelope                                  │
      │  header Signature: b64url(hdr)..b64url(sig)                 │
      │   hdr = {alg:"RS256", kid}                                  │
      │   sender_app_mnemonic = MY_PSP                              │
      │  ─────────────────►│                                        │
      │                    │ key for PARTNER_MY_PSP + kid cached?   │
      │                    │  ├─ hit  → use cache                   │
      │                    │  └─ miss → GET /keys/PARTNER_MY_PSP ──►│
      │                    │◄────────── {public_key, kid, alg} ─────│
      │                    │   cache: soft TTL 300s · refresh on    │
      │                    │   unknown kid · negative-cache 404 ·   │
      │                    │   serve-stale if PM briefly down       │
      │                    │                                        │
      │                    │ check alg ∈ allow-list (RS256 only)    │
      │                    │ verify RS256 signature over            │
      │                    │  b64url(hdr) "." b64url(canonical_json(body))
      │                    │                                        │
      │◄─ 200 SUCCESS ─────│  signature valid                       │
      │◄─ 200 ERROR ───────│  invalid → rjct.jwt.invalid            │

The partner id PM is queried under is PARTNER_ + the upper-cased sender_app_mnemonic from the request envelope, so a partner must be onboarded in PM under exactly that id, with a kid matching the JWS header.

3. Why both directions matter (Bridge → SPAR)

The Bridge signs its own resolve calls to SPAR (as PARTNER_G2P_BRIDGE). SPAR runs the same PartnerMgmtKeyStore verification as flow 2, fetching PARTNER_G2P_BRIDGE from the same PM. So step 1 (self-registration) is what makes the Bridge → SPAR call verify — the Bridge is simultaneously a verifier of inbound partners and a registered partner of SPAR, both through one PM.

Caching & resilience

PartnerMgmtKeyStore holds an in-memory cache so PM is not hit on every request: soft TTL (partner_key_cache_ttl_seconds, 300s) with background refresh, a hard TTL, refresh-on-unknown-kid (so key rotation is picked up without a redeploy), a short negative cache for 404s, and serve-stale-on-outage so a brief PM outage does not immediately fail verification. Key changes in PM therefore take effect within the cache TTL — no Bridge restart needed.

See the Partner Manager service docs for PM itself, Onboarding Partners for the operational steps, and PyJWTCryptoHelper for the crypto engine.

---

API Endpoints

1. Disbursement Controller

Base Tag: G2P Bridge Disbursement Envelope

1.1 Create Disbursements

Endpoint: POST /create_disbursements

Description: Create new disbursements for a batch of beneficiaries.

Request Body:

• Type: DisbursementRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement request structure

3. Calls disbursement service to create disbursements

4. Returns list of created disbursement payloads with unique IDs

5. Returns error response if validation or creation fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• DisbursementException: Returns error response with disbursement error code and partial payloads

Example:

POST /create_disbursements
Content-Type: application/json

{
  "disbursement_request_data": {...}
}

---

1.2 Cancel Disbursements

Endpoint: POST /cancel_disbursements

Description: Cancel existing disbursements.

Request Body:

• Type: DisbursementRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement request structure

3. Calls disbursement service to cancel disbursements

4. Returns list of cancelled disbursement payloads

5. Returns error response if validation or cancellation fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• DisbursementException: Returns error response with disbursement error code and partial payloads

---

2. Disbursement Envelope Controller

Base Tag: G2P Bridge Disbursement Envelope

2.1 Create Disbursement Envelopes

Endpoint: POST /create_disbursement_envelopes

Description: Bulk create disbursement envelopes. An envelope is a container for multiple disbursements.

Request Body:

• Type: DisbursementEnvelopeRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementEnvelopeResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement envelope request structure

3. Calls disbursement envelope service to create envelopes

4. Returns list of created disbursement envelope payloads

5. Returns error response if validation or creation fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• DisbursementEnvelopeException: Returns error response with envelope creation error code

Example:

POST /create_disbursement_envelopes
Content-Type: application/json

{
  "envelopes": [...]
}

---

2.2 Cancel Disbursement Envelope

Endpoint: POST /cancel_disbursement_envelope

Description: Cancel an existing disbursement envelope. Cancelling an envelope cancels all disbursements within it.

Request Body:

• Type: DisbursementEnvelopeRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementEnvelopeResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement envelope request structure

3. Calls disbursement envelope service to cancel envelope

4. Returns cancelled disbursement envelope payload

5. Returns error response if validation or cancellation fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• DisbursementEnvelopeException: Returns error response with envelope cancellation error code

---

2.3 Amend Disbursement Envelope

Endpoint: POST /amend_disbursement_envelope

Description: Amend/modify an existing disbursement envelope.

Request Body:

• Type: DisbursementEnvelopeRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementEnvelopeResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement envelope request structure

3. Calls disbursement envelope service to amend envelope

4. Returns amended disbursement envelope payload

5. Returns error response if validation or amendment fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• DisbursementEnvelopeException: Returns error response with envelope amendment error code

---

3. Disbursement Status Controller

Base Tag: G2P Bridge Disbursement Status

3.1 Get Disbursement Status

Endpoint: POST /get_disbursement_status

Description: Retrieve the current status of one or more disbursements.

Request Body:

• Type: DisbursementStatusRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementStatusResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement status request structure

3. Calls disbursement status service to retrieve status payloads

4. Constructs success response with status information

5. Returns error response if validation or retrieval fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• DisbursementException: Returns error response with disbursement error code

Response Data:

• Returns list of DisbursementStatusPayload objects containing current status of requested disbursements

---

3.2 Get Disbursement Batch Control

Endpoint: POST /get_disbursement_batch_control

Description: Retrieve batch-level control information and status for a disbursement batch.

Request Body:

• Type: DisbursementBatchControlRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementBatchControlResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement batch control request structure

3. Calls disbursement status service to retrieve batch control payload

4. Constructs success response with batch control information

5. Returns error response if validation or retrieval fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• Generic Exception: Returns error response with "internal_error" code

Response Data:

• Returns DisbursementBatchControlPayload containing batch-level information (totals, counts, status)

---

4. Disbursement Envelope Status Controller

Base Tag: G2P Bridge Disbursement Envelope Status

4.1 Get Disbursement Envelope Status

Endpoint: POST /get_disbursement_envelope_status

Description: Retrieve the current status of a disbursement envelope and its enclosed disbursements.

Request Body:

• Type: DisbursementEnvelopeStatusRequest

• Authentication: JWT Signature validation required

Response:

• Type: DisbursementEnvelopeStatusResponse

• HTTP Status: 200 (OK)

Process:

1. Validates JWT signature

2. Validates disbursement envelope status request structure

3. Calls disbursement envelope status service to retrieve status

4. Constructs success response with envelope status information

5. Returns error response if validation or retrieval fails

Error Handling:

• RequestValidationException: Returns error response with validation error code

• DisbursementStatusException: Returns error response with status retrieval error code

Response Data:

• Returns DisbursementEnvelopeStatusPayload containing envelope status and enclosed disbursement statuses

---

5. Account Statement Controller

Base Tag: G2P Bridge Account Statement

5.1 Upload MT940

Endpoint: POST /upload_mt940

Description: Upload a bank account statement in MT940 format. MT940 is a standardized SWIFT format for bank statements.

Request:

• Method: POST (multipart/form-data)

• Parameter: statement_file (File upload, required)

• Authentication: NO JWT signature validation required

Response:

• Type: AccountStatementResponse

• HTTP Status: 200 (OK)

Process:

1. Validates uploaded file exists

2. Validates file format is valid MT940

3. Calls account statement service to process and store statement

4. Returns account statement ID and success response

5. Returns error response if validation or upload fails

Error Handling:

• RequestValidationException: Returns error response with REQUEST_VALIDATION_ERROR code

• AccountStatementException: Returns error response with STATEMENT_UPLOAD_ERROR code

Response Data:

• Returns success response containing the unique account statement ID assigned to the upload

Example:

POST /upload_mt940
Content-Type: multipart/form-data

statement_file: [MT940 file content]

---

Request/Response Schema Overview

Common Response Structure

All API responses follow a standard structure:

Success Response:

{
  "status": "success",
  "code": "200",
  "message": "Operation completed successfully",
  "data": {
    // Response-specific data
  }
}

Error Response:

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Error description",
  "data": null
}

Disbursement Request

Type: DisbursementRequest

Used for creating and cancelling disbursements.

Key Fields:

• Disbursement details (amount, currency, beneficiary info)

• Batch control information

• Payment method details

Disbursement Response

Type: DisbursementResponse

Returns list of disbursement payloads and status information.

Disbursement Envelope Request

Type: DisbursementEnvelopeRequest

Used for creating, cancelling, and amending disbursement envelopes.

Disbursement Envelope Response

Type: DisbursementEnvelopeResponse

Returns disbursement envelope payload(s) with status.

Disbursement Status Request

Type: DisbursementStatusRequest

Parameters to query disbursement status.

Disbursement Status Response

Type: DisbursementStatusResponse

Returns list of disbursement status payloads.

Disbursement Batch Control Request

Type: DisbursementBatchControlRequest

Parameters to query batch control information.

Disbursement Batch Control Response

Type: DisbursementBatchControlResponse

Returns batch control payload with aggregated information.

Disbursement Envelope Status Request

Type: DisbursementEnvelopeStatusRequest

Parameters to query envelope status.

Disbursement Envelope Status Response

Type: DisbursementEnvelopeStatusResponse

Returns envelope status payload.

Account Statement Response

Type: AccountStatementResponse

Returns account statement ID and upload status.

---

Error Codes and Exceptions

The Partner API handles several types of errors:

Exception Types

1. RequestValidationException

   • Raised when request validation fails

   • Includes error code indicating validation failure

   • Returned in HTTP 200 with error status

2. DisbursementException

   • Raised during disbursement creation/cancellation

   • Includes error code and partially processed payloads

   • Allows caller to identify which disbursements failed

3. DisbursementEnvelopeException

   • Raised during envelope operations

   • Includes error code for envelope-specific failures

4. DisbursementStatusException

   • Raised during status retrieval operations

   • Includes error code for status-related errors

5. AccountStatementException

   • Raised during statement upload/processing

   • Includes error code for statement-specific failures

Error Code Usage

• All endpoints return HTTP 200 even for errors (consistent with G2P Bridge pattern)

• Error details are in the response body with appropriate error code

• Callers should check response status field (not HTTP status) to determine success/failure

---

Request Validation

All endpoints perform validation through the RequestValidation service:

1. Signature Validation (Disbursement/Status/Envelope APIs):

   • Validates JWT signature using JWTSignatureValidator

   • Rejects requests with invalid signatures

2. Request Structure Validation (All endpoints):

   • Validates required fields are present

   • Validates data types and formats

   • May validate business rules (e.g., amounts, dates)

3. File Validation (Account Statement):

   • Validates file is present

   • Validates file format is valid MT940

---

API Flow Examples

Example 1: Create Disbursements Workflow

1. Partner calls POST /create_disbursements
2. API validates JWT signature
3. API validates disbursement request structure
4. Service creates disbursements in database
5. Returns DisbursementResponse with created disbursement IDs
6. Partner receives response and processes results

Example 2: Check Disbursement Status Workflow

1. Partner calls POST /get_disbursement_status
2. API validates JWT signature
3. API validates status request parameters
4. Service queries database for disbursement status
5. Returns DisbursementStatusResponse with current status
6. Partner receives and displays status to user

Example 3: Upload Bank Statement Workflow

1. Partner calls POST /upload_mt940 with MT940 file
2. API validates file presence and format
3. Service parses and processes MT940 file
4. Service stores statement in database
5. Returns AccountStatementResponse with statement ID
6. Partner receives statement ID for future reference

---

Service Components

The Partner API uses the following service components:

1. DisbursementService: Handles disbursement creation and cancellation

2. DisbursementEnvelopeService: Manages envelope lifecycle operations

3. DisbursementStatusService: Retrieves disbursement and batch status information

4. DisbursementEnvelopeStatusService: Retrieves envelope status

5. AccountStatementService: Processes and stores account statements

6. RequestValidation: Validates all incoming requests

---

Configuration

Configuration is loaded from Settings class:

• Logging configuration: Uses logging_default_logger_name from settings

• Logger instances created with module-specific names

---

Logging

All controllers log using the configured logger:

• INFO: Start of operations, successful completions

• ERROR: Validation failures, service errors

• DEBUG: Detailed request/response information

---

Base Controller

All controllers extend BaseController from openg2p_fastapi_common.controller, providing:

• FastAPI router setup

• Tag management for API documentation

• Request/response handling

• Common patterns for API route registration

---

Summary Table

Endpoint	Method	Auth Required	Purpose
/create_disbursements	POST	Yes	Create new disbursements
/cancel_disbursements	POST	Yes	Cancel disbursements
/create_disbursement_envelopes	POST	Yes	Create disbursement envelopes
/cancel_disbursement_envelope	POST	Yes	Cancel disbursement envelope
/amend_disbursement_envelope	POST	Yes	Amend disbursement envelope
/get_disbursement_status	POST	Yes	Retrieve disbursement status
/get_disbursement_batch_control	POST	Yes	Retrieve batch control info
/get_disbursement_envelope_status	POST	Yes	Retrieve envelope status
/upload_mt940	POST	No	Upload bank statement file

---

Notes

1. All endpoints use POST method for consistency (including GET-like operations)

2. HTTP status code is always 200; check response body for actual status

3. Responses are async (using async def)

4. All disbursement operations support partial failures with detailed error reporting

5. Account statement upload does not require JWT signature validation

6. All date/time values should follow ISO 8601 format