> For the complete documentation index, see [llms.txt](https://specs.govstack.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://specs.govstack.global/payments/8-service-apis/8.1-government-to-person-g2p-payments.md). # 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. {% openapi src="/files/pQgTTIOazB0tHErEl1dk" path="/identityAccountMapper/beneficiary" method="post" %} [RegisterBeneficiaryRequest.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/gOQOi5qR9dGlEongJFQ4/RegisterBeneficiaryRequest.yml) {% endopenapi %} ### **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. {% openapi src="/files/IR9wBk0uXZReQpsRe2gC" path="/callback" method="post" %} [RegisterBeneficiaryResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/dKkeuiAlMllRx0RnwRTT/RegisterBeneficiaryResponse.yml) {% endopenapi %} ## 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. {% openapi src="/files/KxXP7eDXsTACnLoowhny" path="/identityAccountMapper/beneficiary" method="put" %} [UpdateBeneficiaryRequest.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/GHkucaN90SII85whcEoU/UpdateBeneficiaryRequest.yml) {% endopenapi %} ### **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. {% openapi src="/files/dOiF1JFQ7sBWRYJ2NixJ" path="/callback" method="post" %} [UpdateBeneficiaryResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/dV5sAXWgMpb38CftqWz3/UpdateBeneficiaryResponse.yml) {% endopenapi %} ## 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. {% openapi src="/files/qMr6hZRmoD6HnKhccrdL" path="/batchtransactions" method="post" %} [v1\_0\_1\_fixed\_BulkPayment.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/WueCT38BvOTBfgrknAba/v1_0_1_fixed_BulkPayment.yml) {% endopenapi %} ### **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. {% openapi src="/files/2BD7OA2O5G7KwbVJOHw6" path="/api/v1/batch" method="post" %} [v1\_0\_1\_fixed\_BulkPaymentStatusUpdate.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/zKIYd787Dj7qcPTH0K9L/v1_0_1_fixed_BulkPaymentStatusUpdate.yml) {% endopenapi %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://specs.govstack.global/payments/8-service-apis/8.1-government-to-person-g2p-payments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.