8.1 Government to Person (G2P) payments

These APIs link Source BB to the Payments Building Block for bulk payment processing, identity verification, and bank/wallet mapping. Third-party providers may add extra APIs depending on the country's payment landscape.

8.1.1 Collaboration with G2PConnect

GovStack is collaborating with G2P Connect to make it easier for countries to understand, find, and implement the optimal tools for executing digital payments for the aim of sustainable development. For those familiar with the GovStack initiative, it is no surprise we are collaborating with G2P Connect, as we share a common mission (to provide the technological tools to facilitate sustainable development) and similar methods (developing technical specifications and guidance).

G2P Connect is an open-source effort to enable G2P digital payments, built with interoperable standards and design templates. It offers a technology blueprint with a plug-and-play architecture with built-in privacy and security; a set of integration specifications to ensure interoperability across the systems supporting G2P delivery; and an integration sandbox to support the development of solutions adhering to the blueprint and specifications.

As G2PConnect is focused exclusively on G2P payments, this is a cogent area of collaboration for the GovStack Payments building block workstream. Our joint objective is to develop synergies with specific use cases for G2P digital payments so that these use cases can also be implemented using GovStack APIs and building blocks. We will share best practices and lessons learned through defining the technical specifications and architecture components for G2P payments use cases. We will also integrate and test the APIs for G2P payments use cases in an integrated sandbox adhering to the G2P Connect and GovStack Payments building block specifications.

These valuable resources will then enable any country to implement G2P payments with digital sovereignty and minimal effort. Countries can choose to use our open specifications to make existing systems compatible, procure an open-source DPG, or even a proprietary solution compliant with the specifications.

8.1.2 Beneficiary Onboarding - Account Mapper APIs

Once a new G2P beneficiary is onboarded by a G2P Program and assigned a Functional ID, they can be added to the Account Mapper in Payments BB after their eligibility for the social benefit program has been verified.

As the number of beneficiaries can be large, the API supports the addition of beneficiaries in the mapper in bulk. This allows for efficient onboarding and management of multiple beneficiaries at once, streamlining the process and reducing the time required for handling individual beneficiary registrations.

The Register Beneficiary API is invoked by the Information Mediator BB, which is triggered when the Registration BB is registering beneficiaries into the Payments BB's ID Mapper.

a) Register Beneficiary Request()

This is the API that is called by the Information Mediator BB when the Registration BB in turn calls its API for registering beneficiaries into the ID Mapper of the Payments BB.

Register beneficiaries into the ID Mapper.

post

Authorizations

BeneficiaryOnboardingAuth

X-Callback-URLstringRequired

Header parameters

X-Callback-URLstring · max: 100Required

URL on which the result is published

X-Registering-Institution-IDstring · max: 12Required

Unique ID to identify the Source Ministry/Organization that registered the beneficiary.

Body

application/json

RequestIDstring · max: 12Optional

Responses

200

Successfully received request.

application/json

400

Bad request.

application/json

post

/identityAccountMapper/beneficiary

HTTPcURLJavaScriptPython

POST /identityAccountMapper/beneficiary HTTP/1.1
X-Callback-URL: text
X-Registering-Institution-ID: text
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "RequestID": "text",
  "Beneficiaries": [
    {
      "payeeIdentity": "text",
      "PaymentModality": "text",
      "FinancialAddress": "text"
    }
  ]
}

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

b) Register Beneficiary Response() - Callback

This is the API that is called back by the Pay-BB to notify the Source BB via the IM BB that all or selected beneficiaries have been uploaded into the ID Mapper.

Notify the onboarding status of beneficiaries.

post

Body

application/json

requestIDstring · max: 12Required

registerRequestIDstring · max: 12Required

numberFailedCasesintegerRequired

Responses

200

Callback successfully received.

No content

202

Callback acknowledged but not processed yet.

post

/callback

HTTPcURLJavaScriptPython

POST /callback HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "requestID": "text",
  "registerRequestID": "text",
  "numberFailedCases": 1,
  "failedCases": [
    {
      "payeeIdentity": "text",
      "bankingInstitutionCode": "text",
      "paymentModality": "00",
      "failureReason": "text"
    }
  ]
}

No content

8.1.3 Update Beneficiary Details

This is the API that is called by the Information Mediator BB when the Registration BB in turn calls its API for registering beneficiaries into the ID Mapper of the Payments BB.

a) Update Beneficiary Request()

This interface is to be called by the Registry BB (also referred to as Source BB) when an update to either the Payment Modality or Financial Address is required. Payee Functional ID is not updateable and is only part of this call to identify the individual record that needs updating.

Update the beneficiary payment modality or financial address.

put

Body

application/json

requestIDstring · max: 12Required

sourceBBIDstring · max: 12Required

Responses

200

Beneficiary update successfully received.

application/json

put

/identityAccountMapper/beneficiary

HTTPcURLJavaScriptPython

PUT /identityAccountMapper/beneficiary HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 177

{
  "requestID": "text",
  "sourceBBID": "text",
  "beneficiaries": [
    {
      "payeeIdentity": "text",
      "bankingInstitutionCode": "text",
      "paymentModality": "00",
      "financialAddress": "text",
      "status": "0"
    }
  ]
}

200

Beneficiary update successfully received.

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

b) Update Beneficiary Response()

This is the API that is called back by the Pay-BB to notify the Source BB via the IM BB that all or selected beneficiaries have been successfully uploaded into the ID Mapper.

Callback to notify beneficiary upload status.

post

Body

application/json

requestIDstring · max: 12Required

registerRequestIDstring · max: 12Required

numberFailedCasesintegerRequired

Responses

200

Callback successfully received.

application/json

post

/callback

HTTPcURLJavaScriptPython

POST /callback HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 192

{
  "requestID": "text",
  "registerRequestID": "text",
  "numberFailedCases": 1,
  "failedCases": [
    {
      "payeeFunctionalID": "text",
      "bankingInstitutionCode": "text",
      "paymentModality": "00",
      "failureReason": "text"
    }
  ]
}

200

Callback successfully received.

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

8.1.4 Bulk disbursement APIs

a) Bulk Payment()

This API is to be exposed by the Payments BB and Payer FSP; it will be called by the Source BB or Payments BB to handover a batch of credit instructions to be processed.

Handover Batch of Credit Instructions.

post

Query parameters

typestring · enumRequired

Type of batch transaction. Expected value is "raw".

Possible values:

Header parameters

X-CorrelationIDstring · max: 20Required

Globally unique request Id/ client correlation Id

Platform-TenantIdstring · max: 20Required

Tenant Id for Data scoping

X-Program-Idstring · max: 20Optional

In case a Government Entity has specific budget account for a Program

X-Registering-Institution-Idstring · max: 20Optional

This Id is used for data scoping like Tenants

X-Callback-URLstring · max: 100Required

URL on which the result is published

Bodyobject[]

application/json

requestIdstring · max: 16Required

paymentModestring · max: 20Required

amountnumber · floatRequired

currencystring · max: 3Required

descriptionTextstring · max: 50Optional

Responses

202

Accepted. Batch handed over successfully.

application/json

400

Bad Request. Invalid input or missing parameters.

post

/batchtransactions

HTTPcURLJavaScriptPython

POST /batchtransactions?type=raw HTTP/1.1
X-CorrelationID: text
Platform-TenantId: text
X-Callback-URL: text
Content-Type: application/json
Accept: */*
Content-Length: 188

[
  {
    "requestId": "text",
    "creditParty": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "debitParty": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "paymentMode": "text",
    "amount": 1,
    "currency": "text",
    "descriptionText": "text"
  }
]

{
  "batchId": "text"
}

b) BulkPayment_StatusPush()

This API is expected to be invoked by Payer Bank to the Payments BB to provide updates status of a batch or individual credit instructions. This API is a callback. This API will also serve BulkPayment_Status_Update() from Payments BB to Source BB If the callback fails, the same response can be obtained by directly calling this API ( with case 2 endpoint)

c) Payment_Status_Check Request()

This API is to be invoked by the Source BB to the Payments BB in case the Source BB (SBB) does not receive some completed transactions in bulk payment status updates callback or batch by batchId polling from the Payments BB. Then SBB can run a query for a single beneficiary payment status check.

Update Status of a Batch or Individual Credit Instructions.

post

Query parameters

batchIdstring · max: 50Required

Echo referenced GUID of original request by Payments BB.

X-CorrelationIDstring · max: 12Required

Globally unique request Id/ client correlation Id.

Header parameters

X-Callback-URLstring · max: 100Optional

URL registered in the request, used for callbacks.

Body

application/json

requestIdstring · max: 12Required

batchIdstring · max: 50Required

TotalTransactionsnumberRequired

ongoingnumberRequired

failednumberRequired

completednumberRequired

currencystring · max: 3Required

totalAmountnumber · floatRequired

completed_amountnumber · floatRequired

ongoing_amountnumber · floatRequired

failed_amountnumber · floatRequired

result_filestringRequired

Null for JSON type request

resultGeneratedAtstring · date-timeRequired

Timestamp of the result generation in UTC

notestring · max: 200Required

Narration/description

Responses

200

Successfully updated the status.

application/json

202

Accepted. Update request received and is being processed.

400

Bad Request. Invalid input or missing parameters.

post

/api/v1/batch

HTTPcURLJavaScriptPython

POST /api/v1/batch?batchId=text&X-CorrelationID=text HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 270

{
  "requestId": "text",
  "batchId": "text",
  "TotalTransactions": 1,
  "ongoing": 1,
  "failed": 1,
  "completed": 1,
  "currency": "text",
  "totalAmount": 1,
  "completed_amount": 1,
  "ongoing_amount": 1,
  "failed_amount": 1,
  "result_file": "text",
  "resultGeneratedAt": "2026-02-03T06:35:22.059Z",
  "note": "text"
}

{
  "message": "Status updated successfully."
}