LogoLogo
Give FeedbackGovStack Home
23Q4
23Q4
  • Payments
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
    • 8.1 Government to Person (G2P) payments
    • 8.2 Voucher Management APIs
    • 8.3 Person-to-Government APIs (P2G) Bill Payments
  • 9 Internal Workflows
  • 10 Other Resources
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF
  1. 8 Service APIs

8.1 Government to Person (G2P) payments

Last updated 28 days ago

Was this helpful?

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.

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.

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.

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.

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.

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.

Register beneficiaries into the ID Mapper.

post
Authorizations
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
RequestIDstring · max: 12Optional
Responses
200
Successfully received request.
application/json
400
Bad request.
application/json
post
POST /identityAccountMapper/beneficiary HTTP/1.1
Host: 
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"
}

Notify the onboarding status of beneficiaries.

post
Body
requestIDstring · max: 12Required
registerRequestIDstring · max: 12Required
numberFailedCasesintegerRequired
Responses
200
Callback successfully received.
202
Callback acknowledged but not processed yet.
post
POST /callback HTTP/1.1
Host: 
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

Update the beneficiary payment modality or financial address.

put
Body
requestIDstring · max: 12Required
sourceBBIDstring · max: 12Required
Responses
200
Beneficiary update successfully received.
application/json
put
PUT /identityAccountMapper/beneficiary HTTP/1.1
Host: 
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"
}

Callback to notify beneficiary upload status.

post
Body
requestIDstring · max: 12Required
registerRequestIDstring · max: 12Required
numberFailedCasesintegerRequired
Responses
200
Callback successfully received.
application/json
post
POST /callback HTTP/1.1
Host: 
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.1 Collaboration with G2PConnect
  • 8.1.2 Beneficiary Onboarding - Account Mapper APIs
  • POSTRegister beneficiaries into the ID Mapper.
  • POSTNotify the onboarding status of beneficiaries.
  • 8.1.3 Update Beneficiary Details
  • PUTUpdate the beneficiary payment modality or financial address.
  • POSTCallback to notify beneficiary upload status.
  • 8.1.4 Bulk disbursement APIs
  • POSTHandover Batch of Credit Instructions.

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

Body
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
POST /batchtransactions?type=raw HTTP/1.1
Host: 
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"
}