# Payments Building Block Specification
Version 3.0; December 2025
***First Developed by:***\
Vijay Mauree, Arnold Kibuuka, and Dr. P. S. Ramkumar ([ITU](https://itu.int)), Francesco Pasti ([GSMA](https://www.gsma.com/)), James Dailey, David Higgins ([MIFOS](https://mifos.org)), Oscar Correia ([Maarifa Education](https://www.maarifaeducation.com/)), Khuram Farooq ([World Bank](https://www.worldbank.org/)) and Elie Sawaya ([GIZ](https://giz.de/))
***
***Authors to this version:***\
Vijay Mauree, Arnold Kibuuka, David Higgins, and Oscar Correia
***Editor:***\
Ali González-García
Payments Building Block cover
# 1 Version History
The version history table describes the major changes to the specifications between published versions.
Version
Authors
Comment
0.9.2
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, Sanjay Jain, Luukas Ilves, Lesley-Ann Vaughan
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume
Reviewers:
Sasa Kovacevic, Aare Lapõnin, Anita Mitta, Amy Darling
Editors:
Wesley Brown, Steve Conrad, Valeria Tafoya
Feedback incorporated from Technical Advisory Committee review
Final edits to align content to specification template for GovStack 1.0 release
2.0.0 (previously known as 23Q1) October 2023
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume, and Elie Sawaya
Editors:
Wesley Brown, Steve Conrad, Valeria Tafoya
Introduced new terminology, enhanced P2G requirements, added Billers Table, updated multiple APIs (Onboarding, Bulk Disbursement, Voucher, new P2G APIs), and revised internal P2G workflows.
2.1.0 (previously known as 23Q1) July 2024
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume, and Elie Sawaya
Editors:
Wesley Brown, Steve Conrad, Valeria Tafoya
Addressed discrepancies found during sandbox implementation: modified scheduling services, made eligibility verification required, included recommended reporting requirements, and removed external scheduling.
3.0 December 2025
Vijay Mauree, Arnold Kibuuka, Oscar Correia, David Higgins, Dr. P. S. Ramkumar
Editor:
Ali González-García
Specification for In-Country Multicurrency Payment Systems for governments, persons and businesses.
# Release Notes
## Version 3
***
### **v3.0.0**
*Release date: December 2025*
#### **Release Overview:**
This update primarily expand the Payments Building Block with guidance to implement Multicurrency use cases, as well as extending the use of existing APIs, originally implemented for Government-to-Person (G2P) and Person-to-Government (P2G) transactions, to also support Government-to-Business (G2B) and Business-to-Government (B2G) use cases.
Detailed context on multicurrency payments can be viewed on [Payments BB: Multicurrency - GovStack - GovStack Wiki](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/1014693904/Payments+BB+Multicurrency?force_transition=f336d546-d52d-486b-8e52-b20a721d5890)).
Multicurrency is important because it enables seamless transactions across different currencies, enhancing efficiency, transparency, and access to financial services in diverse economic environments. Additionally, some countries have multiple currencies due to reasons such as economic instability, historical factors, or the presence of a significant informal economy. This multiplicity can facilitate trade and investment but may also complicate financial management and regulatory oversight.
#### **Multicurrency updates:**
* Description: The description was updated to include the multicurrency use cases
* Terminology: New terms have been added to better define multicurrency operations.
* Key Digital Functionalities: We have implemented support for multiple currencies.
* Crosscutting Requirements: We've incorporated additional requirements for the calculation of multicurrency payments, ensuring independent calculations and settlements in the same currency as the transaction. This update also includes the handling of multicurrency accounts for both payers and payees.
* Standards: Standards for currency and payment status codes have been integrated into the specification.
* Data Structures: Updates to the data structures, now include currency indication as a mandatory field for multicurrency transactions.
* Service APIs: The P2G APIs have been enhanced to include the currency functionality for multicurrency use cases. Additionally, updates have been made to the G2P bulk disbursement payment APIs and P2G responses to correct display errors.
* Internal Workflows: Adjustments have been made to display workflows that accommodate multicurrency transactions.
#### **G2B and B2G updates:**
* Updated [Description](/development-3/2-description) chapter to reference G2B additions
* Bulk Payments on section [4.15](https://payments.govstack.global/development-3/1-version-history/pages/5btM4AznD7kQwFbRf5C7#id-4.15-bulk-payment-service) now references G2B case
* Added service API guidance for [8.4 Government to Business](/development-3/8-service-apis) and [8.5 Business to Government](/development-3/8-service-apis/8.5-business-to-government-b2g-payments)
* Added [9.4 Government to Business](/development-3/9-internal-workflows/9.4-government-to-business-g2b) and [9.5 Business to Government](/development-3/9-internal-workflows/9.5-business-to-government-b2g) guidance
* Re-structuring of [chapter 9](/development-3/9-internal-workflows) to spread the content on sub-pages for readability
* Added 2 uses cases: [Government to Business](/development-3/use-cases/government-to-business-g2b-use-case) and [Business to Government](/development-3/use-cases/business-to-government-b2g-use-case) for guidance on how to use these features.
#### **Other changes in this release.**
* [4.10 Scheduling Services](https://payments.govstack.global/development-3/1-version-history/pages/5btM4AznD7kQwFbRf5C7#id-4.10-scheduling-services): The scheduling feature within the payments module has been refined to clearly define internal payments BB scheduling processes.
* [8. Service APIs](/development-3/8-service-apis): The issue with Section 8 not loading due to excessive swagger blocks has been identified and resolved, mirroring a similar fix implemented in the bb-emarketplace.
* The following optional cross-cutting requirements are changed to "recommended":
* Compliance Verification
* Calculation of Payments
* [5.3 Technical Requirements](https://payments.govstack.global/development-3/1-version-history/pages/wJ5tgdMYdre4XPqtYRex#id-5.3-payments-building-block-technical-requirements) tables are re-worked for legibility and requirement level terms homologated to match GovSpecs 2.0 requirement levels.
* [5.4 Standards](https://payments.govstack.global/development-3/1-version-history/pages/wJ5tgdMYdre4XPqtYRex#id-5.4-standards) section is added recommending [ISO 20022](https://www.iso.org/standard/57341.html) and [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) to enhance industry interoperability
#### **Documentation**
For more information regarding these updates, users are encouraged to consult the revised sections within the specification. Additionally, for details on multicurrency, please refer to the multicurrency use case document available here: [Specification for In-Country Multicurrency Payment Systems for governments, persons and businesses](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/1014693904/Payments+BB+Multicurrency?force_transition=f336d546-d52d-486b-8e52-b20a721d5890)
***
## Version 2
***
### **v2.1.0 (previously known as 23Q4)**
*Released date: July 2024*
#### Overview
Following the sandbox implementation of the payments BB in February 2024, discrepancies below were noted in the spec and subsequently updated in this version.
#### **Section 4: Key Digital Functionalities**
4.10 Changes: Modification of the scheduling services in the payments BB; i.e., to enable internal functionalities like bulk processing of payments.
#### **Section 5: Cross-cutting requirements**
5.1.8 Change of eligibility verification from recommended to required
5.2.3 Inclusion of the recommended requirements for reporting services into cross-cutting requirements:
* The data store will be write-only from the core service and should be read-only by external components (RECOMMENDED)
* The data model on the reporting data store can be different from the internal operational data models that the switch uses (RECOMMENDED)
* The component provided by the switch will translate internal events and internal data models to the external data store models. This component can be replaced (RECOMMENDED)
#### **Section 6: Functional requirements:**
6.10 Removal of the "Regular and repeat payments are scheduled (REQUIRED)" from Scheduling Services as this is done outside the payments BB.
### **v2.0.0 (previously 23Q4)**
*Release date: October 2023*
#### **Overview:**
These updates aim to refine the specifications necessary for executing payments from individuals to governments.
#### **Terminology Updates:**
New terminologies have been introduced in the document, including: "Billers," "Aggregators," "Payer," and "Payee."
#### **Functional Requirements:**
Enhancements have been made to the P2G (Person to Government) requirements, now encompassing the billers table, aggregator, and Payer Financial Institutions.
#### **Data Structures:**
A new addition in this section is the "Billers Table," curated for the essential fields pertinent to a biller's table used in the new P2G workflows.
#### **Service APIs:**
Multiple APIs have been revised and enhanced with additional endpoints. The updates encompass:
* **Onboarding to the Account Mapper:**
* Register\_Beneficiary\_Response
* Register\_Beneficiary
* Update\_BeneficiaryDetails
* Update\_BeneficiaryDetails\_Response
* **Bulk Disbursement:**
* PrePayment\_Validation
* PrePayment\_Validation\_Response
* BulkPayment
* **Voucher APIs:**
* VoucherPreActivation
* VoucherActivation
* VoucherStatus
* VoucherCancellation
* VoucherRedemption
* BatchVoucherActivation
Note: The Voucher Redemption API may operate synchronously to ensure the delivery of prompt and reliable responses to the initiating clients, whether users or systems.
* **New P2G APIs:**
* billInquiryBiller
* markBillPayment
* BillerRtpReq
* billerRtpResp
* rtpStatusUpdate
#### **Internal Workflows:**
Significant updates have been made to the internal workflows to accommodate P2G bill payment flows. The enhancements include:
* Workflows supporting biller onboarding – envisioned as a one-time activity on the Payments BB.
* The incorporation of workflows for linking the Payer Financial Institutions (PFI) with the Payments BB for bill payments.
* Implementation of workflows for Bill Inquiry & Bill Payment Updates via the Payment BB.
* Additional flows introduced are:
* Push Payment Flow integrated with Bill Inquiry Flow.
* Payer Financial Institution (PFI) – Customer Bill Payment Flow.
* P2G Bill Payment via Request to Pay (RTP) Flow.
* P2G Bill Payment with Voucher.
***
## Version 1
***
### **v1.0.0**
*Released date: May 2022*
#### Overview
Payments Building Block was first published in May 2022 by the Payments Working Work as reference specification for implementers.
# 2 Description
This section provides context for this Building Block.
The Payments Building Block enables digital financial payments to be tracked, evaluated, initiated, validated, processed, logged, compared and verified against budget. This Building Block also provides interoperability with connections to the various external applications that need payment services in order to trigger transitions in their own workflow. Payment services generally interface through gateways to regulated financial entities such as banks, credit facilities, and insurance companies. To help users easily complete payment transactions and learn if their transaction succeeded or failed, it converts heterogeneous interface protocols, formats, and user interfaces to a standard set of common interfaces and formats. It can also help in tracking the costs of commodity and equipment purchases to optimize budgets.
The Payments Building Block consists of components that enable multiple use cases in a generic manner. The use cases include Government to Person (G2P), Person to Government (P2G), Government to Business (G2B), and Business to Government (B2G). The existing commercial Payments schemes are heterogeneous across regions and countries, the Payments Building Block assumes that some components are optional when considering implementation. The Payments Building Block covers components that can be used to deliver the key functionalities and the connections to existing systems in the market, but does not contemplate building a new Payments scheme. The Payments Building Block supports multicurrency payments in countries where there is more than one currency used. Multicurrency payments are supported based on the independent multicurrency model, where there is no exchange rate conversion. For more information on the multicurrency payments refer to: [Specification for In-Country Multicurrency Payment Systems for governments, persons and businesses](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/1014693904/Payments+BB+Multicurrency?force_transition=f336d546-d52d-486b-8e52-b20a721d5890).
### Financial Inclusion, Banks, and Mobile Money Accounts
Financial inclusion strategies have largely been based on growing access to regulated accounts. These were traditionally understood to be bank accounts, in recent years Mobile Money (MoMo) accounts have greatly increased transactional account access. These MoMo accounts are often, but not always, treated as secondary to the banking system and lack interoperability.
[According to GSMA](https://www.gsma.com/mobilefordevelopment/wp-content/uploads/2021/03/GSMA_State-of-the-Industry-Report-on-Mobile-Money-2021_Summary.pdf), globally registered mobile money accounts stood at 1.2 billion in 2020, transacting an average of over $2 billion per day, mobile money has grown to become the leading payment platform in a growing number of emerging markets. Today, there are more mobile money accounts in Sub-Saharan Africa than there are bank accounts. Indeed, during the pandemic, demand for mobile money services increased among businesses, governments, and new services that previously relied on cash or other payment channels.
There are currently active discussions in many markets on the need for the integration of mobile money into existing national infrastructure. While the integration of mobile money into existing schemes and infrastructure has the potential to create value for all stakeholders in the ecosystem, many legacy payment systems may not be suitable for mobile money integration in their current state. As an example, many existing interbank switches do not support mobile money as a core feature because of legacy technical architecture. What is often missing is the essential capability of the switch to handle high-volume, low-value flows with the mobile number (Mobile Station Integrated Services Digital Network) as identifier for routing and address resolution hence the need for integration. Recent industry developments offer solutions designed to solve many of the issues around the switching of mobile money.
Mobile money providers, regulators, infrastructure providers, and other financial system players should seek to engage in any potential interoperability initiatives from an early stage to ensure optimal payment system design for all parties. Should existing infrastructure be used, a thorough assessment should be conducted, with input from all parties, to ensure appropriate governance, commercial, and technical standards are incorporated. Mandating interoperability within a short time frame removes opportunities for a thoughtful and holistic analysis of commercial sustainability. Requiring immediate interoperability can also delay or hamper the uptake of interoperable transactions, and mobile money services altogether. This is a particular risk in contexts where regulators or governments impose immediate connections to a centralized hub. Mobile money providers should be encouraged to connect when their service is ready. However alternative modalities of payment such as cash vouchers can also be considered in scenarios of low-resource regions that lack modern infrastructure and a volume of mobile phone users. Also, in countries where mobile money providers are not connected to a payment switch, aggregators can enable the flow of funds between multiple financial service providers including banks and non-banks. While aggregators may not be as efficient and scalable as switches, they can help solve interoperability issues in the short and medium term.
## Payments Building Block Capabilities
Generally, the Building Block is supportive of multiple types of payment use cases where the Government is one of the parties:
* **Government to people (G2P)**
* Payment where the payer is a government and the payee is an individual e.g. Social benefits disbursement, government salary payments, Conditional and [Unconditional Social Cash Transfers](https://solutions.dial.community/use-cases/unconditional-social-cash-transfer/use-case-steps/payment)).
* **People to Government (P2G)**
* Payment where the payer is an individual and the payee is a government. P2G payments can be government initiated, for instance, in the case of payments for registrations for government services. For bill payments and payments for government services directly by the person, the system should provide the person with the flexibility to choose which payment instrument to use (eg. mobile money, bank transfer or card payments). (e.g. payment of taxes, payment [Registration for Postpartum and Infant Care](https://govstack.gitbook.io/use-cases/ruc-23q4/use-cases/hltc-1-postpartum-and-infant-care#id-6-payment), payment of school fees, driving license, utility payments).
* **Government to Business (G2B)**
* G2B payments include tax refunds, goods and services purchases, subsidies, contract payments, benefits, and loans.
* **Business to Government (B2G)**
* B2G payments include paying taxes and fees.
* **Government to Government (G2G)**
* Payments between two government entities (i.e. between Ministries/Departments and public sector institutions).
Government to Government (G2G) are not covered in this specification and will be covered in a later phase.
## Government-to-Person Payment Principles
The implementation of the Payments Building Block should adhere to the following principles, particularly as it relates to Government-to-Person (G2P) payments:
### Beneficiary/Recipient-related Principles
* Beneficiaries can receive their payment through a fully functional account that allows them to save and make payments using an associated payment instrument with general acceptance.
* They can choose the payment service provider and payment instrument through which they receive their payments based on their informed choice; they can use the same account for multiple G2P payments, make Person-to-government (P2G) payments and easily switch if desired.
* On-boarding to their payment method is low cost and easy with account opening requirements that are available to recipients and with no opening fees; a payment instrument is provided to the recipient at no cost.
* The Integrated Financial Management Information System (IFMIS) is used to process government payments against budgetary allocations. It supports:
* the Treasury Single Account (TSA) that aggregates all incoming government receipts and disburses all government payments;
* budget management to ensure budget compliance, tracking, and reporting. The IFMIS provides the Ministry of Finance with a unified view of the government’s budget execution.
* The payment instrument is easy-to-use and generally accepted, and the overall costs for using it do not result in increased costs for the beneficiary in comparison to other forms of payment.
* Beneficiaries are well informed, their account/data is protected, and have access to redress. They know when, where, and how many payments will be made and understand how their payment method works, its costs, how to use their payment instrument, and how to access their payment. They can access and know how to access effective grievance redressal mechanisms, their funds are secured, and their data privacy is ensured.
* Beneficiaries can easily access their funds. They are able to cash out their funds at any time at a wide range of conveniently close financial access points. At a reasonable and clearly communicated withdrawal fee or at no cost.
* Beneficiaries are included regardless of gender, race, or other immutable characteristics, through at least one of the payment methods used; gender gaps are considered in the design.
### Infrastructure and Systems-related Principles
* The leveraged infrastructures and systems are shared across G2P programs and payment streams, as well as other use cases, avoiding the implementation of systems to exclusively deliver G2P payments. They are scalable and have cyber security arrangements in place.
* Common ID provides access to multiple programs; the national ID system has high coverage and quality; it allows government agencies and payment service providers to validate recipients’ identities; it enables data sharing across government agencies.
* Payment processing systems unlike social protection management information systems, pension, and payroll systems will not include gender-disaggregated data.
* The payment systems are interoperable to maximize the potential of the available infrastructure to recipients; interoperability arrangements exist for Integrated Financial Management Information System (IFMIS), Treasury Single Account (TSA), banks, and non-banks covering most channels and instruments.
* There is no manual intervention in the disbursement process and the entire payments flow is Straight-Through-Processing, including the reconciliation of payments. Payments are made without delays.
### Payment Services Provider-related Principles
* Payment service providers have a strong and long-term, predictable business case or incentives to deliver payments and provide choice.
* A large variety of bank and non-bank financial institutions operating in a competitive market are used to deliver G2P payments.
* Agents of bank and non-bank financial institutions are accessible to G2P payment recipients.
## Mapping Based on Level of Maturity
The following use cases can be mapped to the Payments Building Block capabilities as follows.
Capabilities
Payment Infrastructure Scenario
User journey
Use Cases
Destination Channel
G2P
Scenario 1-4 & 6
Payment - Unconditional Social Cash Transfer (direct payment based on family relationship)
Payment - registration of birth (Postpartum and Infant Care)
Mobile Money.
## Payment Infrastructure Deployment Scenarios
### Regional Switch vs Country Switch
A Payment Switch is the software and hardware system that provides routing between regulated entities in a Payments Scheme.
Domestic payment switches have specific economic characteristics and may not reach adequate economies of scale. Whilst costs can be passed onto customers, without sufficiently low charges, volumes may remain perennially low. Domestic switches facing this scenario thus remain under-utilized, costly, and under-capitalized. In recent years, the concept of Regional payment switches has gained some traction with new efforts realized or underway across the Southern African Development Community (SADC), West African Monetary and Economic Union (UEMOA), East African Community (EAC), and Economic and Monetary Community of Central Africa (CEMAC).
Regional switches (which may serve as a common resource for multiple countries) often rely on pre-existing arrangements between Central Banks, regional Commercial Banks, or a combination thereof. When multiple currencies are in play, a reference currency or a basket of currencies must be chosen for regional settlement accounts to be viable. Settlement arrangements are vital to the viability of a regional switch. A Regional switch may also integrate financial transactions from countries that already have domestic payment switches (like a switch of switches).
Regional switches may take on any and all use cases or may be restricted to specific use cases, for example, Large Value Transfer or B2B trade. Because regional trade drives economic activity, regional switches often go hand in hand with the portability of business and consumer credentials (i.e. relating to Customer Due Diligence), trade policy, and movement of labor.
### Payment infrastructure scenarios
The Payments Building Block sits between the government account systems (i.e. at the Ministry of Finance or Central Bank) and the public or private switching available in the market. As such the Payments Building Block is assumed in each, but not shown. The primary focus in describing these scenarios is on the relationship between payment schemes, banking institutions, and government institutions. This section describes what is available in-country.
| **Infrastructure Scenarios** | **Suggested Approach** |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
Payment Infrastructure Scenario 1 Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks in different countries in a region.
| Government should leverage the regional payments switch (scheme) to enable all use-cases. This may also imply important developments of a standardized Customer Due Diligence (CDD). Note that while a State owned bank is shown in the diagram below, the option exists for the Government to designate a specific Commercial bank, or to have the funds flow directly from the Ministry of Finance (Treasury) assuming such Treasury payment functionality can be supported by the Regional Switch. |
|
Payment Infrastructure Scenario 2 A payment switch connecting financial service providers such as banks to non-banks including mobile money providers is in place and actively working.
| Government should leverage the existing switch to enable payments use-cases to reach mobile money providers. There may be a State Owned Bank (2-A) or not (2-B). |
|
Payment Infrastructure Scenario 3 A payment switch is in place in the country or is in the process to be deployed but non-banks, including mobile providers are not connected to it.
|
Government should leverage third-party aggregators or bilateral integrations to enable payment use-cases to reach mobile money providers.
|
|
Payment Infrastructure Scenario 4 A payment switch is not place or in the process of being deployed
| Government should leverage third-party aggregators or bilateral connections to enable payment use-cases to reach mobile money providers |
|
Payment Infrastructure Scenario 5 Government makes G2P payments using Central Bank Digital Currency (CBDC) .
| The Central Bank distributes the funds for the CBDC accounts via regulated entities (e.g. Payment Service Providers). |
|
Payment Infrastructure Scenario 6 Citizens have CBDC accounts directly with the Central Bank or other accounts with other payment service providers
| The Central Bank sets up limited accounts for each person, providing a base level of access and functionality. Such accounts may be denominated in country currency (fiat) or CBDCs. This scenario places more responsibility on government structures and is not often considered (outside of Postal Banks and the like). |
Under each of these scenarios, there are different setups possible that relate the key roles played by the Programmatic Ministries (e.g. Ministry of Education or Pension Program), the Ministry of Finance, the Central Bank, and the existing Payment Switch.
The flow of funds and the flow of data are separate but equally important and they have a number of interactions.
#### Payment Infrastructure Scenario 1
Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks.
#### Payment Infrastructure Scenario 2-A
Scenario 2-A and Scenario 2-B cover the concept of separating flows of data from accounting flows.
The Central Bank receives the funds transfer advice from the Treasury and the data from the Ministry of Health and does the steps of breaking it into bulk, based on rules of capacity of source and destination systems. Payments are then routed “on-us” or to the external financial providers “off-us” via a payment switch or similar mechanism.
#### Payment Infrastructure Scenario 2-B
The Central Bank plays a key role as a participant in the Payment scheme and routes the payment details and funds via a shared service of the payment switch. The same logic of break-bulk applies and with all transactions effectively “off-us”.
#### Payment infrastructure scenario 3
Government should leverage third-party aggregators to enable payment use cases to reach mobile money providers
#### Payment Infrastructure Scenario 4
A payment switch is not in place or in the process of being deployed. Government should leverage third-party aggregators or bilateral connections to enable payment use cases to reach mobile money providers. In the bilateral connection scenario, each mobile money provider in the country would connect to the government portal through APIs, enabling a seamless transfer of funds to end users (in the case of G2P payments) or the receiving of funds from end users (in the case of P2G payments) and facilitate reporting, reconciliation and settlement processes.
%20\(1\)%20\(2\).png?alt=media)
#### Payment Infrastructure Scenario 5
The Central Bank mints digital currency and distributes funds via regulated entities (e.g. Payment Service Providers), and in the case of G2P sends funds to destination accounts known to the Ministry of Finance. Account information is unitary and unique for all beneficiaries (e.g. citizens) but the Central Bank does not “hold” account balances on an individual basis.
#### Payment Infrastructure Scenario 6
The Central Bank directly provides Digital Accounts for all people (Citizens) and Treasury routes funds to the relevant accounts (uniquely and unitarily held by people).
* For this payment use case, the most common scenarios currently in place are 1 to 4, scenario 5 and 6 could be envisaged later.
* In Scenario 2B it is assumed that the Payment Switch is run by the Central Bank.
* In Scenario 2A and 3, it is assumed that the Payment Switch is an independent part outside the Central Bank.
# 3 Terminology
Terminology used within this specification.
Several elements of the glossary are based on the terminology defined by the [level one project](https://www.leveloneproject.org/wp-content/uploads/2020/07/L1P_Guide_2019_Final.pdf) and [ITU DFS Glossary](https://www.itu.int/en/ITU-T/focusgroups/dfs/Documents/201701/ITU_FGDFS_DFS-Glossary.pdf)
### **Account Mapper or Account Lookup Directory Service**
A dynamic directory matching beneficiaries’ unique identifier and their account numbers enable multiple programs to direct payments to the same account and beneficiaries to switch payment service providers. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases.
### **Authentication**
The validation of user credentials for the purpose of system login and basic access.
### **Aggregators**
Act as payment facilitators for billers by onboarding multiple billers on their platform and are responsible for, connecting with PSPs and FSPs on behalf of Billers, often, also communicating specific Bill IDs to the consumers to collect amount through their respective platforms and settling the collected amount with the billers.
### **Authorization**
The permission given by the Payer or entity to make a Payment.
### **Base Currency Model**
A single currency to which all other currencies are converted for processing
### **Beneficiary**
A single currency to which all other currencies are converted for processing
### **Billers**
Entity responsible for: Generating Bills with Bill ID’s in PSP’s identifiable format, distributing Bills to the customer (either directly or via another service / channel), marking bill as paid upon confirmation from Payment service provider.
### **Bulk Payments**
A Payment from a single Payer to multiple Payees, for example, cash transfer programs from a government or non-governmental organization to a set of beneficiaries.
### **Currency Conversion**
The process of exchanging one currency for another based on current exchange rates.
### **End User**
The customer of a digital financial services provider. The customer may be a consumer, a merchant, a government, or another form of enterprise.
### **Financial Management Information System**
The budget management system of the government treasury which ensures that government (Ministries, Departments, Agencies) payments are processed within the approved budget and releases.
### **Financial Services Providers (FSPs)**
A financial services provider refers to one that is licensed by a regulatory authority to provide transaction accounts that hold customer funds and are used to make and receive payments. Digital Financial Services Providers (DFSPs) have relationships with consumers, merchants, and other enterprises, and provide digital financial services to End Users.
### **Independent Currency Model**
A system where each currency is processed and settled independently.
### **Interoperability**
The ability of DFSPs participating in a payment Scheme to exchange Transactions with each other. The term may also be used when two systems interconnect.
### **Mobile Money (MoMo)**
A mobile money service includes transferring money and making and receiving payments using a mobile phone. The service must be available to the unbanked, e.g. people who do not have access to a formal account at a financial institution. The service must offer a network of physical transactional points which can include agents, outside of bank branches and ATMs, that make the service widely accessible. Mobile banking or payment services (such as Apple Pay and Google Wallet) that offer the mobile phone as just another channel to access a traditional banking product are not included.
### **Mobile Money Services Provider**
A category of DFSPs that use mobile phones as the access method to provide transaction Accounts to End Users.
### **Payee**
The recipient of funds in a payment transaction.
### **Payer**
The person/organization whose account is debited in a payment transaction.
### **Payment**
Exchange of funds, credentials, and other necessary information to complete an obligation between End Users. A transfer is an example of a payment.
### **Payment Alias (also, Payment address)**
An alias may include phone numbers, email addresses, or other handles. They may include globally unique URIs and may be chosen by the user. These are increasingly seen in new payment systems. Within systems, the payment alias points to an underlying payment account address, specifically and uniquely located within a payment scheme. A payment address may be different from the underlying account address, depending on the payment scheme rules but is often the same thing.
### **Quick-Response (QR) Code**
A method of encoding and visualization of data, which are machine-readable. There are multiple QR models.
### **Routing**
The process by which a route to a payment address is determined. The mechanism of sending payment information across different systems. This is sometimes used interchangeably with addressing.
### **Settlement**
The process of transferring funds between parties to complete a financial transaction.
### **Switch**
A processing entity in a payments system that routes a Transaction from one DFSP to another DFSP. A system may operate its own Switch, or this function may be done by one or more third parties
See for reference:
An entity which receives transactions from one provider and routes those transactions on to another provider. A switch may be owned or hired by a scheme or be hired by individual providers. A switch will connect to a settlement system for inter-participant settlement.
See for reference:
### **Transaction**
A reference to the entirety of the exchange, including a Payment but may also include information between the Payer’s DFSP and the Payee’s DFSP.
### **Treasury Single Account**
A Treasury Single Account (TSA) is a unified structure of government bank accounts that gives a consolidated view of government cash resources. Based on the principle of unity of cash and the unity of treasury, a TSA is a bank account or a set of linked accounts through which the government transacts all its receipts and payments. The principle of unity follows from the fungibility of all cash irrespective of its end use. While it is necessary to distinguish individual cash transactions for control and reporting purposes, this purpose is achieved through the accounting system and not by holding/depositing cash in transaction-specific bank accounts. [This enables the treasury to delink management of cash from control at a transaction level](https://www.imf.org/external/pubs/ft/wp/2010/wp10143.pdf#%3A~%3Atext%3DA%20treasury%20single%20account%20%28TSA%29%20is%20an%20essential%2Cpriority%20in%20the%20public%20financial%20management%20reform%20agenda).
### **Uniform Resource Identifier (URI)**
A unique sequence of characters that identifies a logical or physical resource used by web technologies.
### **Voucher**
A token that entitles the holder to a discount or that may be exchanged for goods or services.
### **Voucher Group**
A voucher group is a characteristic of a voucher that restricts the function or use case that a voucher can be used for. It can also be used as a dimension for reporting on.
# 4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
The Payment Building Block will handle payments processing and orchestration, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions.
The Building Block will enable government programs to channel payments through a shared payments infrastructure to accounts at multiple providers, allowing citizens to choose their preferred Financial Services Provider and switch providers if their circumstances change or they discover a better service.
## 4.1 Payment Orchestration
Payments orchestration provides for end-to-end workflow across different sub-subsystems, enables asynchronous processing, and covers different payment types, use cases, account systems, and channels.
## 4.2 Voucher Management
The Payment Building Block will provide a voucher management system which is responsible for provisioning, storage, issuance, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
## 4.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
The account lookup directory service or mapper simplifies payment routing and is an important component to avoid storing the payment information of the user in the social registry system and preserve the privacy and confidentiality of sensitive information pertaining to the beneficiary.
## 4.4 Payment Request Initiation
The Payment Building Block must allow systems to initiate a payment request. This request could come from two sources: external or internal. An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll).
## 4.5 Payment Gateway
The Payments Building Block should provide a payment gateway which allows different (digital) Financial Service Providers (FSPs) to interoperate.
## 4.6 Payment Portal
The Payments Building Block should provide a Payment Portal which allows users to manage thje full lifecycle of sending and receiving payments
## 4.7 Event Management
The Payment Building block must support different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
## 4.8 Reconciliation
The Payments Building block must implement functionality that provides both internal and external reconciliation services.
## 4.9 Batch Processing
The Payments Building Block should provide batch processing services
## 4.10 Scheduling Services
The Payments Building Block should allow for scheduling services to perform tasks on a regular or repeated basis. This may be achieved through the Schedular BB or through internal timer functions.
## 4.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
## 4.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
## 4.13 Reporting Services
The Building Block should provide reporting services, which may consist of dashboards or analytics reports. These reports should be configurable based on user needs.
## 4.14 Security layer
The Payments Building Block must provide a security layer which protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication.
## 4.15 Bulk payment service
The Payments Building Block must provide bulk payment services. This bulk payment service is invoked in the case of G2P or G2B bulk disbursement.
## 4.16 Support for multicurrency payments
The payments BB supports a multicurrency system where each accepted currency is processed independently without conversion, allowing users to transact directly in their preferred currency. The source building block where the payment request is initiated (for eg in G2P payments this would be the Registry BB and for P2G payments this would be a Biller) will specify the currency for the payment. The treasury will maintain separate accounts and financial records for each currencies.
# 5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
## 5.1 Requirements
### 5.1.1 External Identification, Registration, and Enrollment Logic (REQUIRED)
The Payments Building Block assumes that all identification, registration, and enrollment logic is done externally and are compliant with regulated payments and banking systems within a jurisdiction.
### 5.1.2 Registration Requirements (RECOMMENDED)
The Payment System or Scheme in a country may require that participating payor or payee entities, whether health clinics, ministries, or individuals must have been registered with a regulated banking or non-banking entity prior to the use of the Payments Building Block.
### 5.1.3 Compliance Verification (RECOMMENDED)
In the context of Central Bank Digital Currency or Central Bank Accounts for individuals, the payment system block would assume that the regulatory conditions must have been verified for compliance and that payer and payee entities must have been properly registered according to the rules in that scheme.
### 5.1.4 Statutory and Operational Requirements (REQUIRED)
The Payments Building Block assumes that the statutory and operational requirements around accounts (i.e. know your customer/anti-money laundering/counter-terrorist financing) must have been completed by an outside system, which is capable of communicating that status in appropriate timeframes.
### 5.1.5 Real-time Response (RECOMMENDED)
The Payments Building Block assumes that the capabilities of the underlying infrastructure must enable transactions to meet a predefined limit to turn-around-time in real-time response.
### 5.1.6 Validation (REQUIRED)
The Payments Building Block should have the ability to validate against a set of external systems for the status of an account, account address and routing information, confirmation of payment, and various error conditions of accounts and specific payments.
### 5.1.7 Authorization (RECOMMENDED)
During operation in certain modes, the Payments Block would be validating against authorizations/releases or allotments provided by the treasury systems for the source of funds.
### 5.1.8 Eligibility Verification (RECOMMENDED)
Normally, verification of eligibility of beneficiaries for the service should be done in another Block.
### 5.1.9 Budget Availability (REQUIRED)
Budget availability must be checked before voucher creation is requested.
### 5.1.10 Calculation of Payments (RECOMMENDED)
Calculations of payments may depend on several attributes laid down by a specific program.
In an independent multicurrency model, systems must process transactions directly in the selected currency without converting to a base or alternate currency to maintain currency integrity during the transaction process and ensure transparency and reliability for users, reducing the need for cross-currency conversions and associated costs.
### 5.1.11 Payment Systems (REQUIRED)
Payment systems in the market, either provided by a public entity, a quasi-public entity, or a purely commercial player, are required for the functioning of this Building Block.
### 5.1.12 Settlement (REQUIRED)
Settlement (gross or net) must be handled externally to this Building Block.
In an independent multicurrency model, the system must support settlements in the same currency as the transaction, ensuring that the funds transferred match the original transaction currency.
### 5.1.13 Security (REQUIRED)
The Payments Building Block must meet the security requirements described in the Security Building Block.
### 5.1.14 API Mechanisms (REQUIRED)
The Payments Building Block should meet the mechanisms for consuming and publishing APIs as described in the Information Mediator Building Block.
### 5.1.15 Architecture (REQUIRED)
The Payments Building Block must meet the requirements described in the Architecture Building Block.
### 5.1.16 Multicurrency Accounts (RECOMMENDED)
The treasury will maintain separate accounts and financial records for each currency. The source building block where the payment request is initiated will specify the currency for the payment to the Payments building block.
The system must generate reports for payments made in each currency type.
## 5.2 Infrastructure Requirements
### 5.2.1 Mobile Money
Infrastructure Components:
* Account lookup - directory service.
* Payment portal.
* Payment gateway (only in selected scenarios).
* Payment request initiation.
* Notification service.
Mobile money is a destination account to distribute funds to end users (in the case of G2P) or an initiation account to enable users to initiate a payment for government services (P2G) which is facilitated by private commercial entities, typically Mobile Network Operators.
There are three ways that facilitate interoperability between a mobile money provider and a financial service institution (which could be the initiator of a payment - G2P or the receive - P2G): Through a Switch, through a third-party aggregator or through a bilateral integration. We expect one or multiple of these components to be in place to facilitate the use cases discussed in this document but these will remain out of the Payment Building Block.
### 5.2.2 Vouchers
Infrastructure Components:
* Voucher Management System.
* Merchant Ecosystem.
* Merchant Registry.
The Merchant Ecosystem and the Merchant Registry are both outside the scope of the Payments Building Block. The development of the Merchant Ecosystem will be driven by the relevant government institution. The Merchant Registry will be managed by another Building Block.
## 5.3 Payments Building Block Technical Requirements
### 5.3.1 General requirements
Requirement
Type
Secure API exposure: All APIs exposed via secure socket connections (HTTPS).
REQUIRED
Client application authorization tokens: Client applications must send authorization tokens in the authorization header of the request to authenticate users and the API Management Gateway will verify whether the token is valid.
REQUIRED
Transaction receipting: For each disbursement made by the system, a receipt should be issued to the recipient of the funds containing information about the transaction id, transaction date and time, reason for the payment, details of the payer, and the system should store all receipts issued for easy reference and reconciliation.
REQUIRED
Transaction status querying capability
REQUIRED
Display details of the transaction to the payer
REQUIRED
Transaction pre-approval: Prior to processing bulk payment and batch payment transactions, the transaction must be authorized and approved in the system.
REQUIRED
Pre-processing validation of data (well formed data and completeness checks) prior to disbursement.
REQUIRED
Ability to schedule bulk payments
REQUIRED
Support for batch payments
REQUIRED
Ability to lookup payment addresses
RECOMMENDED
Error handling and reconciliation
REQUIRED
Transaction status logging
REQUIRED
Triggering of payments
REQUIRED
### 5.3.2 Voucher Management
Requirement
Type
Batch generation of vouchers
REQUIRED
Voucher uniqueness and randomness: Voucher pin must be unique and unpredictable.
REQUIRED
Secure voucher data storage
REQUIRED
High availability of storage
REQUIRED
Expose APIs that can be invoked by voucher serial number for purposes of querying a voucher, suspending, or unsuspending a voucher.
REQUIRED
Support an API that can be invoked to redeem a voucher using the voucher number.
REQUIRED
Support an API that can invoke payment gateway
REQUIRED
### 5.3.3 Mobile Payments
Requirement
Type
Real time debiting/crediting of mobile money accounts
RECOMMENDED
Regular balance reconciliation with disbursement Agency
REQUIRED
Documented process for partners to dispute transaction records
REQUIRED
Target account identifier or lookup of payment address
REQUIRED
Ability to retrieve details of completed transactions in the batch
REQUIRED
### 5.3.4 Bulk Payments
Requirement
Type
Ability to securely receive bulk payment requests as a single HTTPS request containing data for multiple transactions. The transaction data (with payment instructions data) is passed format and will be compatible with ISO 20022.
REQUIRED
The number of transactions that can be included in a single batch is limited by the size of the file upload and the processing time. If the number of transactions in the file exceeds the file size and could impact the performance of the system, the batch should be split into multiple batch requests.
REQUIRED
Batch files should be verified for any errors and validated as per business rules and regulations before it is accepted as a valid bulk payment file.
REQUIRED
Batch files containing duplicate payments will not be processed and an error will be generated.
REQUIRED
The bulk payment process has to be explicitly triggered by an authorized user. All requests to the Bulk Payment Application API must be authorized and digitally signed by the person initiating the bulk payment request.
REQUIRED
The batch file for bulk payments should contain the beneficiary ID token, and the amount to be paid. The payment information is not included in the batch file for security and privacy but is resolved by the verification and validation component of the bulk payment service by invoking the Account Lookup Directory Service (ALDS/ALS).
REQUIRED
The Bulk Payment Application API shall inspect the batch disbursement file and split transactions into bank payments and non-bank payments (e.g. Mobile money) in separate payment files before initiating the call to the Payment Gateway.
REQUIRED
The status of the bulk payment transaction can be obtained from the event log. The payment status code indicates the status of a single payment transaction and will be according to ISO 20022 Payment status codes table.
REQUIRED
## 5.4 Standards
The following standards are applicable to data structures in the Payments Building Block:
[ISO 20022](https://www.iso.org/standard/57341.html): Universal financial industry message scheme
[ISO 4217](https://www.iso.org/iso-4217-currency-codes.html): Currency Codes
# 6 Functional Requirements
This section lists the technical capabilities of this Building Block.
## 6.1 Payment Orchestration
Payment orchestration is an overarching concern which relates different sub-components or microservices whereby it:
* Explicitly defines and models workflows that span multiple microservices (REQUIRED)
* Provides detailed visibility into how a workflow is performing and identifying where there are issues (REQUIRED)
* Ensure that within a defined workflow, all workflow instances are completed according to plan, even when there are issues along the way (REQUIRED)
Payments orchestration is used to configure the Payments Building Block functionalities to be exercised during a specific workflow and provides functionality such as:
* Sending receipts, notifications, and acknowledgement of receipts in a secure manner to payers and other external applications to receive confirmation of payment made and safekeeping of a record of the receipt that was sent (REQUIRED)
* Provides for auditability of the Payments Building Block to have its controls evaluated for effectiveness, efficiency, and security, including tracing transactions, identifying users who access the system, clearly defined system controls, and compliance with local regulations and global best practices (REQUIRED)
* Schedule and aggregate payments to individuals, allowing programs to stagger payments or combine them with other payments to the same groups of individuals (REQUIRED)
* Enable payment confirmation through secure receipts, notifications, and acknowledgement of receipts to payers and other external applications (REQUIRED)
* Store event logs and audit trails for all transactions processed and their outcomes for monitoring and audit purposes (REQUIRED)
* Validate data structures and content to ensure that it is not missing key pieces of information, including verifying the destination account and triggering a different process if the account is not in good status (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed with throttling to reduce the flow of payment initiated (REQUIRED)
* Coordinate or orchestrate the validation, verification, batching, and scheduling using a set of rules, including options for kicking back to the operator for review or resubmission in certain error cases (REQUIRED)
* Generate reconciliation of accounts based on the successful sending of funds into accounts and reports to show the additional status of systems and payment types and timings (REQUIRED)
* Manage fees in a centralized way and support the use of digital channels to/from end-users, regulated account systems with payment signalling, and notifications by the Financial Services Provider enablers (REQUIRED)
* Scale on transaction performance, transaction latency, reliability, resilience, and graceful service degradation (REQUIRED)
* Support digital tools for query management, including beneficiary queries and complaints about payment services (REQUIRED)
* Route bulk payments through the account holding the funds, either at the government Treasury or a commercial bank (REQUIRED)
* Release funds by the Ministry or payroll master after appropriate approvals (REQUIRED)
* Handle processing and orchestration of bulk payments, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions (REQUIRED)
* Validate data structures and content to ensure that key information is not missing (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed (REQUIRED)
* Generate reconciliation of accounts based on successful sending of funds into accounts (REQUIRED)
* Provision, issue, activate, and redeem vouchers to support G2P beneficiary payments (REQUIRED)
* Ensure that adequate funds have been allocated to the voucher during provisioning (REQUIRED)
* Allow issuance of vouchers but make them unusable until they are in the hands of the beneficiary (REQUIRED)
* Activate vouchers to make them usable for predefined use cases and for a certain period of time (REQUIRED)
* Handle redemption of vouchers so that beneficiaries receive appropriate benefits from third parties (REQUIRED)
* Generate reports that show the vouchers in their different states as well as the aggregate quantity "stock", which triggers requests for "re-stocking" of vouchers (REQUIRED)
* Authenticate beneficiaries at the point of redemption by checking the Digital Registries Building Block to authenticate the user (REQUIRED)
* Cater for the distribution of social service transfers electronically and cash safely to end users (in the case where the user does not want to use electronic payments it is recommended that vouchers are used) (REQUIRED)
* Creates eVouchers to disburse financial subsidies in a controlled and safe manner (REQUIRED)
* Responds to payers to provide information about the status of the payments (e.g. confirmation of payment, insufficient balance or a mismatch in credentials, transfer failure, etc.), based on the status in the backend applications (REQUIRED)
* Posts status of transactions with traceability information into transaction logs (REQUIRED)
* Tracks due payment and sent payment notifications through alerting mechanisms, along with associated information (REQUIRED)
* Receives triggers for payment collection, posts the amount with relevant disclaimers to the payer, and obtains payer approval (REQUIRED)
* Securely posts the approval, user ID, and associated payment information to the appropriate backend (e.g. mobile, debit/credit card, internet banking entities) of relevant financial applications from banks, employers, and insurance; awaits transfer confirmation from those applications (REQUIRED)
* Searches and provides a logged information-based query of other applications (REQUIRED)
* Able to handle operations in remote and inaccessible locations (REQUIRED)
## 6.2 Voucher Management
The voucher management system is responsible for prectivation, storage, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
### **6.2.1 Voucher Provisioning**
This process traditionally involves the generation of group vouchers against some authorized value (budget release or allotment).
* Each voucher should have a unique secret voucher number, a unique identification number (voucher serial number) indicating its position in an inventory of pre-activated vouchers, and is linked to a fixed amount of value in a particular currency (REQUIRED)\
\
Vouchers will also be associated with a voucher group during pre-activation. Voucher serial numbers will be unique across currencies should there be vouchers of multiple currencies.
* The vouchers should be created with an expiry date and MUST be stored securely (REQUIRED)\
\
All vouchers will be expected to have the same duration of expiry and this expiry period will be from the moment the voucher is activated.
* Alternative design options include dynamically pre-activating a voucher at transaction time and creating variable amounts, but this increases complexity and requires tighter operational controls (RECOMMENDED)
### **6.2.2 Voucher Issuance**
This process involves the Registration Building Block (or any other Building Block for that matter) requesting a voucher number from the voucher management system through an API.
* Once confirmation is received that the voucher has been released it flags the voucher as activated. Design decisions include making this step recommended. Having an additional step increases security by ensuring that the voucher is not used until it is in the hands of the beneficiary (RECOMMENDED)
* Presentation of the voucher. At a minimum, this presentation should have the voucher number as well as the voucher serial number (REQUIRED)\
\
Once a voucher has been issued by the calling Building Block (Registration Building Block) it will be presented to the beneficiary in a form that is determined by the calling Building Block (refer to voucher workflow). The format of the final voucher presentation will be determined by the function of the calling Building Block. It could include the details of the beneficiary, which when placed on the voucher presentation, will help the merchant authenticate the beneficiary at the point of redemption
### **6.2.3 Voucher Redemption**
* Extract and authenticate voucher data (REQUIRED)\
\
In the redemption process, the merchant will authenticate the beneficiary and use a predefined technology (Unstructured Supplementary Service Data, Mobile App, Web Browser) to extract the voucher number and call a redemption API through the relevant calling Building Block. The calling Building Block may also validate the beneficiary details if so required. The Building Block will also be able to validate the merchant and determine the voucher group to which the merchant belongs. Lastly, the calling Building Block will invoke the Payment Building Block Redeem API, through the Payments Building Block API Management gateway, to validate the voucher and if valid to redeem it
* Initiate payment in the merchant or agent wallet or bank account (REQUIRED)\
\
Once the voucher is validated, the Voucher Management System should invoke an API on the Payment Gateway to effect the payment in the merchant or agent wallet or bank account (depending on what was set up at merchant/agent registration). The payment gateway/switch will debit a pre-funded account/wallet and credit the merchant/agent account/wallet. The successful execution will result in the voucher being flagged as consumed/used (REQUIRED)
### 6.2.4 Voucher Management System (VMS) API interface
The details of the VMS APIs are described in the Service API section.
The VMS functionality can be accessed by four external APIs and includes the following functionalities:
* Preactivate a voucher (REQUIRED)\
\
An API call to pre-activate the voucher and get a voucher number, a voucher serial number, and an expiry date.
* Activate a voucher (REQUIRED)\
\
An API call to activate the vouchers by serial number.
* Verify validity of a voucher by serial number (REQUIRED)\
\
An API call to check the validity of a voucher by serial number, or by voucher number and group
* Redeem/consume voucher (REQUIRED)
### 6.2.5 Voucher Storage
The voucher management server shall have a storage subsystem to store the vouchers.
* Vouchers must be stored in secure but high-performance data storage (read access will marginally exceed write access) (REQUIRED)
* The storage of the voucher number will require encryption of data at rest and in motion (unless the channel is encrypted) (REQUIRED)
* Logs generated should NEVER contain the voucher numbers (REQUIRED)
* All access to the voucher database must be logged (REQUIRED)
* Segregation of duty must be done with respect to privileged access to the database and key management of the encryption of the voucher (the level of key management may need to be determined) (REQUIRED)
## 6.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
Account lookup directory service (REQUIRED)
* The account lookup directory service provides a directory that maps the beneficiary's unique identifier (which matches the record in the social registry system) to the transaction account where the beneficiary wishes to receive their G2P payment, allowing the government to address payments to a specific individual. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases. The information will be kept in a tokenised form in the account lookup directory service.
* In the case where there is a national payment switch, the account lookup directory service will be maintained by the FSPs, In the scenario, where there is no payment switch, the government would need to manage the account lookup directory service and provide a mechanism for linking it to the FSPs.
## 6.4 Payment Request Initiation
A request can come from either internal or external sources (REQUIRED)
* An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll). Either source must be appropriately authenticated and authorized to initiate the request.
The initiation can be synchronous (typically for a single payment) or asynchronous (typically for batch payments) (REQUIRED)
The request must contain at a minimum: the payer identifier, the payee identifier, the amount, the currency, the policy, and the initiating source’s unique transaction ID. In the case of the internal payment request, it should also contain an ID provided by the payment orchestration module (REQUIRED)
Certain processes in the transaction flow might require proof of intent from the user, for example, entering the PIN/Password or pressing an ’accept‘ key to initiate the payment process. Such events and their outcomes should be recorded for audit trail purposes. However, the PINs and passwords should not be stored in logs or if they have to, PINs and passwords should be hashed out (RECOMMENDED)
## 6.5 Payment Gateway
A payment gateway allows different (digital) Financial Service Providers (FSPs) to:
* Interconnect and exchange information (REQUIRED)
* Initiate and receive transactions (REQUIRED)
* Accept or reject transactions and debit or credit end-user accounts (REQUIRED)
## 6.6 Payment Portal
The payment portal will:
* Enable government payers (departments/ministries/public sector bodies) to make G2P payments through one or multiple FSP/payment service providers (REQUIRED)
* Focus on managing, sending, and reconciling payments (REQUIRED)
* Connect government agencies to sending and recipient institutions (REQUIRED)
* Coordinates sending/receiving of payment requests, and approvals (REQUIRED)
* Provide reports across G2P programs, FSPs, and beneficiaries (RECOMMENDED)
* Track payment status and payment history (REQUIRED)
* Register FSPs who are entitled to process payments for G2P payments (REQUIRED)
* Provide restricted access to authorized FSPs to connect to the portal, to process the payments for beneficiaries who are their customers (REQUIRED)
* Automate reconciliation (RECOMMENDED)
* Provide data analytics on payments processed and their status, whether successful or not (REQUIRED)
## 6.7 Event Management
Create logs and notifications for specific actions on any transaction (REQUIRED)
* This functionality supports different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
* All notification events shall have a timestamp associated with them and be kept as part of the audit log.
## 6.8 Reconciliation
This should happen at two levels: internally and externally.
* The internal reconciliation will occur between the different sub-blocks within the Payments Building Blocks. In order to achieve internal reconciliation the internal payment request initiator should issue a unique ID that will be referenced by subsequent Payments Building Blocks in all future calls related to the particular payment. This will allow end-to-end tracing of the transaction within the Payments Building Blocks (REQUIRED)
* The external reconciliation is more complex as it involves a calling Building Block which is outside the Payments Building Blocks (such as the Registration Building Block) and a third party (e.g. DFS). Ideally, there needs to be a sequence of IDs that can identify a transaction from start to finish (REQUIRED)
* The nodes that are under the control of the GovStack should be time synched (REQUIRED)
* IDs should be unique, if possible contain the timestamp, and should not roll over across short ranges (REQUIRED)
## 6.9 Batch Processing
* Prepares the batch breakdown on the basis of rulesets governing: which Financial Services Providers shall receive, which payments, and other considerations (REQUIRED)
* Combines payments with other payments to the same beneficiary (REQUIRED)
* Detects batch failure rates (REQUIRED)
Batch files go through a final check to be clean of defects and inconsistencies, to check with external systems as necessary:
* At high volumes, batches are queued for processing (REQUIRED)
* Low-level validation of data types and data completeness (REQUIRED)
* Verification of lookup of accounts to ensure that the account information matches the destination system expectation (REQUIRED)
* Check for inconsistencies (REQUIRED)
* Auto-correct items as possible - consistency logic can be applied to fill in missing formatting if required by recipient banks and telecoms (REQUIRED)
* Errors are kicked back to program level or to an internal data review process (REQUIRED)
## 6.10 Scheduling Services
The payments BB must be able to internally schedule tasks as needed using dependencies to be able to execute workflows (REQUIRED).
## 6.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
Application or event logs will capture events that each component performs and should contain at least the following information (REQUIRED):
* application/user ID
* event date and time
* terminal identity (name and/or IP address)
* event-related information (message or code)
* event success or failure
The components should also generate transaction logs that capture at least the following information (REQUIRED):
* transaction date and time
* transaction source
* transaction destination
* supplementary data
* transaction status (success, failed, in progress)
The event logs and the transaction logs should NOT capture any sensitive data such as voucher numbers, passwords, etc. (REQUIRED)
There should be an individual transaction record for every payment transaction. For example, if a batch payment process is executed there should be a transaction record for each individual transaction and a separate event log for the entire batch (RECOMMENDED)
## 6.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
* Must be automatically captured by the computer system whenever a payment request is created, modified, or deleted (REQUIRED)
* Must be stored in a secure manner and must not be editable by any user, including privileged users. A common approach is to copy/redirect logging to a separate logging server (REQUIRED)
* Each audit trail entry must be time-stamped according to a controlled clock which cannot be altered. The time should either be based on central server time or a local time, so long as it is clear in which time zone the entry was performed (REQUIRED)
* Each audit trail entry must be traceable, i.e. attributable to the individual responsible for the direct data input. Updates made to data records must not obscure previous values and where required by regulation the reason for changing the data must also be recorded (REQUIRED)
* The audit trail must be retained as long as the electronic record is legally required to be stored (REQUIRED)
* The audit trail must be available for internal review/audit (REQUIRED)
* The auditing system must be self-sufficient, i.e. for auditing/regulatory purposes the information stored by a BC must be enough (REQUIRED)
* Audit entries cannot be changed, i.e. the audit BC persisted store should be immutable, and should only support append and not changes or deletes (REQUIRED)
* Audit entries should have a pair of fields to store encrypted data and the encryption key id - these are provided by the submitting BCs (REQUIRED)
* Querying capabilities (REQUIRED):
* Auditor wants to see all activity in the last X days.
* Auditor wants to see all activity of action type Y, or from a certain BC.
* Auditor should be able to request the decryption of encrypted data to an operator.
* Access to the audit store must be securable, so whatever tech is chosen must implement access control mechanisms (ideally that can connect to our Identity and Access Management provider/connector) (REQUIRED)
## 6.13 Reporting Services
The data store will be write-only from the core service and should be read-only by external components (RECOMMENDED)
The data model on the reporting data store can be different from the internal operational data models that the switch uses (RECOMMENDED)
The component provided by the switch will be translating internal events and internal data models to the external data store models. This component can be replaced (RECOMMENDED)
## 6.14 Security layer
Protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication. The digital signatures are based on public key cryptography using X.509 digital certificates.
At the transport layer:
* All communication between building blocks must use secure protocols to protect the confidentiality and integrity of the data in transit (REQUIRED)
* Strong authentication for parties involved in the transactions should be supported (REQUIRED)
* Confidentiality of personal information related to the transaction – Information on account data, transaction data, payment credentials, and users’/payee’ personal profiles must never be disclosed to any unauthorized party (REQUIRED)
* Non-repudiation of transactions by parties involved (REQUIRED)
* Acknowledgement receipt: this will result in creating a trusted communication path for all transactions between each party, by the end users, telecommunication companies, merchants, or banks (REQUIRED)
* The messages concerning the payment transaction shall be authenticated (REQUIRED)
## 6.15 Data Protection
Use of a hardware security module (HSM) or equivalent to provide cryptographic keys for critical functions such as encryption, decryption, and authentication for the use of applications, identities, and databases (REQUIRED)
## 6.16 Bulk payment service
### 6.16.1 G2P bulk disbursement (RECOMMENDED)
The following are the prerequisites required before bulk payments can be initiated:
Funding requirements:
* The funding requirements must operate within the budget/ceiling.
* The number of funding accounts and the life cycle processes will vary depending on the payment infrastructure scenarios.
Bulk payments file:
* For the salary payments use case, this would be generated by the payroll system.
* For the unconditional social cash transfer use case, this would be generated by a process that would be triggered as per a pre-agreed frequency and the information about the payments to be made would be extracted from the registry (a database containing the information about beneficiaries for a particular government social cash transfer programme). The process of generating this payments file is outside the Payments Building Block.
There are three options for the disbursement:
* Manual process for Government/Department to send the retail payment details to each Financial Services Provider (FSP) (i.e. either by email or other means). This would be the case where there is a lack of interoperability among FSPs.
* Upload the batch disbursement file in the payment web portal for each FSP to retrieve in the case of a centralised Account Lookup Directory Service.
* Automate the disbursement process through the decentralised Account Lookup Directory Service and the payment gateway.
**Option 1**: Retail payment information is sent securely to each Payment Service Provider for disbursement
**Option 2**: Retail payments are accessed via a payment web portal by the Payment Service Provider. The advice/electronic fund transfer request, or paper-based check is issued from the Financial Management Information System to the Trusted Single Account (TSA) -holding Bank.\
Based on this advice, the Bank disburses funds from the TSA into the digital payments system of the FSP which transfers the corresponding funds to the recipient’s account. For the retail payment scrolls, where each agency is responsible for running the payment system - payroll, social welfare payments, etc. - the payment details are not stored in those systems. Instead, the beneficiary’s payment token is retrieved from the Centralised Account Lookup Directory Service and kept in the government payment portal. The payment lists are only shared with the program account holder institution/FSP, Payment Service Provider (PSP), via the government payment portal. The FSP/PSP can log in on the government web portal to access the directory for payments that the FSP needs to effect for each G2P Program.
**Option 3**: Similar to option 2 but the disbursement process to the beneficiary is routed automatically through the payment gateway using the payment token retrieved from the decentralised account lookup directory service.
Bulk payments require the functionality of a Payments Gateway and the functionality therein. It also assumes a separate mechanism by which the recipient account address is determined. In the figure below the “account lookup directory service” functionality maps the concept of identity to the payment alias and from there to the Financial Services Provider routing address. (i.e. wallet address or account address)
### **6.16.2 Interaction with Other Building Blocks (REQUIRED)**
The diagram below shows the interaction with the registries Building Blocks.
At a high level, the payment components used for bulk payments are shown in the figure below.
Figure: Key digital requirements of Bulk Payments expressed as a high-level block diagram. Dotted line for required components.
### 6.16.3 P2G Bill payments
The Billing ecosystem would consist of various actors performing core and secondary processes to complete the bill payment function. Some of the actors only play an auxiliary role to enable bill payment.
**Payments Building Block**
* Main payments facilitator enabling exchange of all financial and non-financial messages related to: Biller/Aggregator Registration o Bill discovery o Bill Payment Confirmation messages
* Biller Discovery through internally referring to the Billers Table updated by PBB Billing sub-Module
* Generation of transaction/ activity reports for registered Billers/ Aggregators
* Registration of Billers in the system
* Allocation of unique Biller IDs / Prefixes
**Billers Table**
* Database of all registered billers
* Internally referenced by the Payments BB each time a Bill Inquiry comes in
* Returns the endpoints for the registered biller/ aggregators
* Biller Details and Account Details from this table would be shared with the Payer FIs during Payments BB and Payer FSP linking for Bill Payments.
**Billers/ Aggregators**
* Getting registered at the PBB – Bill Payment Service
* Returning the correct Bill Details against the Bill Inquiries received from PBB
* Marking the Bills as “Paid” upon receiving Payment confirmation from PBB
* \[Out of Scope of PBB] Performing Bill validation and Bill discovery in their system
**Payer FIs**
* Sending Bill inquiry Requests
* Sending Bill Payment Confirmation
* \[Out of Scope of PBB] Customer validation and Payment debit
## 6.17 Payments Building Block Components
The following components are needed to achieve the technical functionalities of the Payments Building Block.
Many of the components outlined above are used to deliver the Functional Requirements for the Payments Building Block. Components which are not directly related to the delivery of these functions are described here:
### 6.17.1 API Management Gateway
The Payment Building Block provides an API Gateway to handle all the API messaging calls and API access control verification from other Building Blocks to the Payments Building Block and vice versa as well as within the Payments Building Block. All requests from other Building Blocks first go through the API gateway. The gateway then routes requests to the appropriate application/service.
The API Management gateway will:
* Use Identity and access management for authentication.
* Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats.
* Require authentication for all API users.
* Manage access quotas and throttling.
* Log all API calls.
* Allow API providers to limit the rate of consumption for all API users.
* Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.
# 7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
## 7.1 Account Mapper
### **7.1.1 Beneficiary on-boarding**
Field
Type
M/O
Description
requestID
String (12)
M
Globally unique ID
beneficiaries
Object
JSON Array
payeeIdentity
String (20)
M
The functional Id of the beneficiary.
paymentModality
String (2)
O
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
bankingInstitutionCode(BBIC)
String (11)
C
Beneficiary Bank Institution code that will receive the address. This is conditional as it will only be present in case of bank account, mobile money account and digital wallet ID
financialAddress
String (30)
O
Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
### **7.1.2 On-boarded beneficiary**
Field
Type
M/O
Description
requestID
String (12)
M
Globally unique ID
registerRequestID
String (12)
M
Referenced GUID of original request by Source BB to register a beneficiary.
rumberFailedCases
Number
M
The number of cases failed. 0 if none, otherwise integer value
failedCases
Object
O
JSON Array containing the list of FunctionalIDs and Payment Modalities that were not updated in the ID Mapper.
payeeIdentity
String (20)
M
The functional Id of the beneficiary.
bankingInstitutionCode
String (11)
C
Beneficiary Bank Institution Code (BBIC). The beneficiary bank institution code. This is conditional as it will only be present in case of bank account, mobile money account and digital wallet ID
paymentModality
String (2)
M
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
failureReason
String(100)
O
Description of why this particular record failed to add
The relevant bill details including biller ID, Name, Bank Institutional Code (BIC), Status, Amount with due date and after due date, *Currency (multicurrency use case)
billerId
String (10)
M
Biller Id
billerName
String (10)
M
Biller Name
billStatus
String (10)
M
Informs the status whether paid or unpaid
dueDate
Epoch
M
currency
string(3)
M
Needed in multicurrency operations
amountonDueDate
Integer
M
The amount at which the consumer needs to pay bill with due date.
amountAfterDueDate
Integer
M
Amount calculated after due date.
### **7.4.2 Billers table**
The Biller Table may need to include the following fields:
| Fields/ Records | Description | Provided/ Generated By |
| --------------- | -------------------------------------------------------------- | ---------------------------------------- |
| Unique ID | Prefix allocated to every entity directly registering with PBB | PBB Billing Module |
| Biller Details | Records Biller Details | Biller/ Aggregator |
| Biller FSP | Recorded Biller’s Bank Details | Biller/ Aggregator |
| Bill ID Details | Maximum number of Digits in Bill ID | Biller/ Aggregator |
| Biller Status | Active/ Inactive | PBB Billing Module |
| End-Points | Addresses to send requests | Biller/ Aggregator Technology Partner |
| Response Codes | Mapping of codes received and sent to Billers/ Agg. | PBB Billing Module + Biller Tech Partner |
# 8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionalities that should be provided by any implementation of this Building Block.
The [GovStack non-functional requirements document](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.
The tests for the Payments Building Block can be found in [this GitHub repository](https://github.com/GovStackWorkingGroup/bb-payments/tree/main/test/openAPI).
The following pages cover service API references for:
* [**8.1 Government to Person (G2P) payments**](/development-3/8-service-apis/8.1-government-to-person-g2p-payments)
* [**8.2 Voucher Management**](/development-3/8-service-apis/8.2-voucher-management-apis)
* [**8.3 Person-to-Government (P2G) payments**](/development-3/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments)
* [**8.4 Government-to-Business (B2G) payments**](/development-3/8-service-apis/8.4-government-to-business-g2b-payments)
* [**8.5 Business-to-Government (B2G) payments**](/development-3/8-service-apis/8.5-business-to-government-b2g-payments)
# 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://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FTnK8qOf3yC11xHxeDKhC%2FRegisterBeneficiaryRequest.yml?alt=media\&token=8abc5a67-a735-4ef2-8690-ae59221a696c)
{% 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://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FcDWj5GxXMsuMJ2SN319T%2FRegisterBeneficiaryResponse.yml?alt=media\&token=79d68870-31a1-4d0e-bb21-9360b805420b)
{% 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://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FmZiPKviLoDXrLhqNd821%2FUpdateBeneficiaryRequest.yml?alt=media\&token=92803fe0-28f2-4947-9ca6-fb695051208b)
{% 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://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FYT24jD2AfyDhSv1Y6Fo8%2FUpdateBeneficiaryResponse.yml?alt=media\&token=6657656c-4296-47f0-92b7-7087325eb077)
{% 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://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2Fq1WGkbZVsSrdLMdh5PEP%2Fv1_0_1_fixed_BulkPayment.yml?alt=media\&token=833f6d9a-65ba-46ee-adfd-17a6134f8869)
{% 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://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FlNVv6YAvTSJApCxFGb2g%2Fv1_0_1_fixed_BulkPaymentStatusUpdate.yml?alt=media\&token=5f3ea808-2ded-4013-a11e-d0d1aea0463e)
{% endopenapi %}
# 8.2 Voucher Management APIs
The first API in the section below is used to request for a voucher with a specific value, currency, and purpose. The server responds with a voucher number, serial number, and expiry date. The second call activates the pre-activated voucher. The third call processes voucher redemption, crediting the merchant if valid. The fourth APIs allow for voucher status checks.
### 8.2.1 VoucherPreActivation
#### a) VoucherPreActivation()
The VoucherPreActivation API is used by non-Payment Building Blocks in the GovStack Framework to request for a voucher to be used. This call reserves the voucher (for a period, which is to be implemented). This API requests a single voucher from the voucher server that can be used for a future redemption process. The caller sends an amount, a voucher group (depending on the use case), the currency, and the name of the calling GovStack Building Block. If the API call is successful, the Payment Building Block will respond with a voucher number, a voucher serial number, and an expiry date.
{% openapi src="/files/akKaWsoHkYroeiiaezPy" path="/vouchers" method="post" %}
[VoucherPreactivationRequest.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FPVYXaoR5YrkEumxXtwZP%2FVoucherPreactivationRequest.yml?alt=media\&token=61732443-9379-4085-8c87-3a490eb4fb3f)
{% endopenapi %}
**b) Create\_Vouchers\_Response()**
Description This is the API called by the Voucher Engine to return Voucher Details once vouchers have been created in the Voucher Engine.
{% openapi src="/files/kymL9dFqJRQwqj2ZbVnb" path="/voucher-details-return" method="post" %}
[VoucherCreationResponse.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FimpIi8P7vaaNErGddlz7%2FVoucherCreationResponse.yml?alt=media\&token=e26aede1-b371-41f9-957f-f73c4aa84246)
{% endopenapi %}
### 8.2.2 VoucherActivation
#### a) Voucher\_Activation()
The VoucherActivation API is used by non-Payments Building Blocks in the GovStack Framework to activate a pre-activated voucher. This second function call is intended to ensure that the voucher is only activated when it is disbursed. This API requests for the activation of a voucher when the caller sends the voucher number to be activated. If the API call is successful, the activation is confirmed, and the voucher can now be used by the beneficiary.
{% openapi src="/files/hNbVGyfbAq5Qp2treCMB" path="/vouchers" method="put" %}
[VoucherActivate.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2Fw94HLsH8YbyvGtd3nvJ9%2FVoucherActivate.yml?alt=media\&token=b20b8d5c-20a5-4d15-b5d8-f5f7390a672c)
{% endopenapi %}
For Batch voucher activation, the voucher activation APIS is used by calling Building Block to activate vouchers in bulk. This may be used for bulk social cash transfers where the recipients receive benefits by vouchers. The calling Building Block is responsible for generating the beneficiary file as well as dispensing the vouchers. The Payments Building Block is responsible for generating and redeeming the voucher codes. Both BBs will have had to have exchanged encryption keys during the implementation phase.
The file provided by the calling Building Block will typically contain a unique identifier, the amount of the voucher required, the currency of the voucher, and the voucher group. While the file format may vary, the recommended file format is an encrypted JSON file.
If the file is properly formatted, the Payments Building Block will respond with a file that contains the unique ID that was sent, the status, the voucher number, the voucher serial number, and the expiry date of the voucher. The response file will also be an encrypted file to ensure the appropriate security of the voucher number.
The calling building block will dispense the vouchers as needed using an appropriate delivery mechanism. The calling Building Block will also be responsible for any verification of the beneficiary during the redemption process. The description of the dispensing of the vouchers once the calling block has received it is outside the scope of the Payments Building Block.
**b) Voucher\_Activate\_Response()**
Description This is the response API called by the Voucher Engine to confirm the status of batch activation back to the calling BB.
{% openapi src="/files/gTJTFvsyMuUlN5puMwsg" path="/callback-url" method="post" %}
[VoucherActivateResponse.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FfR1MyBOXot5jFgUGzbBM%2FVoucherActivateResponse.yml?alt=media\&token=a3599f01-5254-425b-8368-ade429ae2d93)
{% endopenapi %}
### 8.2.3 VoucherRedemption
The VoucherRedemption API is used by non-Payment Building Blocks in the GovStack Framework to redeem a voucher. The calling Building Block will capture the voucher number and the voucher serial number from the merchant point. The external Building Block will also acquire the merchant name and payment details from the merchant registry. The calling Building Block will then send the voucher number, the voucher serial number, the merchant’s name, and payment details. The Payment Building Block will verify that the voucher has been activated and has not been used or blocked or canceled. If so, the Payment Building Block will then send a payment request to the funding agency/Financial Services Provider. The Payment Gateway of the Payments Building Block will facilitate the debit of the funding account, and the credit of the merchant as well as handle any intermediary fees. Once the payment has been successfully done the Payment Building Block will mark the voucher as consumed and notify the merchant (and beneficiary if possible).
{% openapi src="/files/GUlYJ2URXiIPyTpg7MNa" path="/vouchers" method="post" %}
[VoucherRedemption.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2Fvj6mssnSdNFf72YyAwYF%2FVoucherRedemption.yml?alt=media\&token=f4d0ead0-339a-4bbb-8faa-38d9501a4837)
{% endopenapi %}
### 8.2.4 VoucherStatus
The VoucherStatus API is used by non-Payment Building Blocks in the GovStack Framework to check the status of a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to determine the status of a voucher. The Payments Building Block will respond with one of the statuses of Pre-Activated, Activated, Suspended, Blocked, or Not Existing.
{% openapi src="/files/0B9qQSLnxFgYZKwvlVfd" path="/vouchers/{serialNumber}" method="get" %}
[VoucherStatus.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2Fy0H6q4J0gF9LbDAqEFau%2FVoucherStatus.yml?alt=media\&token=5a801bba-5d7d-4570-8766-9fa3d99adfed)
{% endopenapi %}
### 8.2.5 VoucherCancellation
**Voucher\_Cancellation()**
Description This API will be called by the Source-BB to update the status of the voucher(s), in the case of cancellation, the status code 03 is sent to the relevant field of the instruction array.
The VoucherCancellation API is used by non-Payments Building Blocks in the GovStack Framework to cancel a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to cancel the voucher.
{% openapi src="/files/IUXMve3eLkypdGI3B2vz" path="/vouchers" method="post" %}
[VoucherCancellation.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FZIPdimahkqYinq9JIJaw%2FVoucherCancellation.yml?alt=media\&token=d77452c8-3f2b-40a2-ac82-bccdb6e311a7)
{% endopenapi %}
***
**Voucher\_ Cancellation\_Response()**
Description Response API called by the Voucher Engine to confirm the cancellation of the voucher. The Payments Building Block will respond with a status of Cancelled, Already Cancelled, or Not Existing. The Voucher Cancellation will override the Blocked status and render the voucher permanently unusable.
{% openapi src="/files/eUVlXuWlhJvRaWpK2Spg" path="/vouchers/cancellation/confirmation" method="post" %}
[VoucherCancellationResponse.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2Fb5Z5kN7aMNIXyEW9FyK3%2FVoucherCancellationResponse.yml?alt=media\&token=44d4d7ed-68c1-4161-ad0d-b8ad935eac5e)
{% endopenapi %}
# 8.3 Person-to-Government APIs (P2G) Bill Payments
The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money and vouchers.
#### **8.3.1 billInquiryBiller**
This API is called to inquire about bill details from a Bill Aggregator or Govt Entity.
{% openapi src="/files/PansJNWk0m2kneSdMloT" path="/bills/{billId}" method="get" %}
[billInquiryRequest.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FHThmGT4XMNYj7MN6Cv53%2FbillInquiryRequest.yml?alt=media\&token=eac85daa-8867-4a0e-95c3-1526a53f6de3)
{% endopenapi %}
#### **8.3.2 billrInquiryResponse**
The Payment BB updates the Bill Aggregator or government entity on the status of the Request to Pay.
{% openapi src="/files/wggw2fLjtpKLIbbjdKgw" path="/bills/{billId}" method="post" %}
[v1\_0\_1\_billInquiryResponse.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FJJi09TflhpW1872JUud5%2Fv1_0_1_billInquiryResponse.yml?alt=media\&token=6d910561-2505-4cee-8fb3-0eec0ab1d476)
{% endopenapi %}
#### **8.3.3 markBillPayment**
This API marks a bill as paid.
{% openapi src="/files/d9p4i8OugFALHuGESq2t" path="/billTransferRequests" method="post" %}
[markBillPpaymentRequest.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2F8JjtkUNHqWKLo590jO88%2FmarkBillPpaymentRequest.yml?alt=media\&token=c39f731e-8c0b-4523-8671-144096a86326)
{% endopenapi %}
#### **8.3.4 billerRtpReq**
The Bill Aggregator or Govt Entity initiates a “Request to Pay” (RTP) through this API.
{% openapi src="/files/i2cjhDNnY6iHRVGsHAVW" path="/billTransferRequests" method="post" %}
[markBillPpaymentResponse.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FAul5dY3h24hmfFZpjMi4%2FmarkBillPpaymentResponse.yml?alt=media\&token=db54ebcb-a9ba-443e-a883-789cc4e8e79f)
{% endopenapi %}
#### **8.3.5 billerRtpReq**
{% openapi src="/files/Ijrsl5MigugoM6A2XV4N" path="/rtpUpdate" method="post" %}
[billerRtpResponse.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FvaT1sPyqcOvRWDD8Rg99%2FbillerRtpResponse.yml?alt=media\&token=855348ef-bff6-4653-9fbc-32672e5afee4)
{% endopenapi %}
#### **8.3.6 rtpStatusUpdate**
This API allows the Biller or Aggregator to inquire about the status of its RTP.
{% openapi src="/files/P4TVnG2YVqyBlcRwRqtW" path="/transferRequests/{transferRequestId}" method="get" %}
[rtpStatusUpdateRequest.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2FYWLiiGKDTAnkp300T42D%2FrtpStatusUpdateRequest.yml?alt=media\&token=3d10cc1b-6c6c-4df3-afae-762b2c49909c)
{% endopenapi %}
#### **8.3.7 rtpStatusUpdateResponse**
This API allows the Biller or Aggregator to receive the status of its RTP.
{% openapi src="/files/8vhgVuPX4Gnr4jkD75Dm" path="/transferRequests/{transferRequestId}" method="post" %}
[rtpStatusUpdateResponse.yml](https://1216505995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fewl3vYAk59R7g4crEkvq%2Fuploads%2Fr0FMAQBixWGdgBd0eWW1%2FrtpStatusUpdateResponse.yml?alt=media\&token=b30b22a8-4df1-4c3b-902e-2e5b114116ba)
{% endopenapi %}
# 8.4 Government to Business (G2B) payments
For Government to Business (G2B) transactions the following existing APIs would need to be used:
* Register Beneficiary - The existing Register Beneficiary API detailed in [G2P payments ](/development-3/8-service-apis/8.1-government-to-person-g2p-payments)would be able to be used to register a business payment details in the ID Account Mapper, assuming a functional ID for a business can be allocated by the ID BB.
* Update Beneficiary - The existing Update Beneficiary API detailed in [G2P payments](/development-3/8-service-apis/8.1-government-to-person-g2p-payments) would be able to be used to update a registered Business payment details in the ID Account Mapper.
* Bulk Disbursement - The existing Bulk disbursement APIs detailed in [G2P payments](/development-3/8-service-apis/8.1-government-to-person-g2p-payments) would be able to be used to send a batch of credit instructions for businesses
# 8.5 Business to Government (B2G) payments
For Business to Government (B2G) transactions the following existing APIs would need to be used:
For Invoice Payments
* [billInquiryBiller](https://payments.govstack.global/development-3/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.1-billinquirybiller) - The existing API to retrieve invoice details detailed in the [P2G payments](/development-3/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used to get bill details from the Bill Aggregator or Govt Entity.
* [markBillPayment](https://payments.govstack.global/development-3/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.3-markbillpayment) - The existing API to bill payment detailed in the [P2G payments](/development-3/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used to mark the invoice as paid.
For RTP Payments
* [billerRtpReq](https://payments.govstack.global/development-3/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.4-billerrtpreq) - The existing API for to initiate a "Request to Pay" (RTP) as detailed in the [P2G Payments](/development-3/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used try the Bill Aggregator or Govt Entity to initiate the RTP.
* [markBillPayment](https://payments.govstack.global/development-3/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.3-markbillpayment) - The existing API to bill payment detailed in the [P2G payments](/development-3/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used to mark the invoice as paid.
# 9 Internal Workflows
This section provides a detailed view of how the Payments Building Block will interact with other Building Blocks to support payments.
This section discusses the various processes involved in G2P disbursement, such as beneficiary onboarding into the Account Mapper, bulk disbursements to pre-registered financial addresses, and account pre-validation prior to bulk disbursement. This section includes considerations for a Multiple Independent Currency model.
The following sub-pages cover:
* **9.1** [**G2P Bulk Payment**](/development-3/9-internal-workflows/9.1-g2p-bulk-payment)
* **9.2** [**Voucher Payments**](/development-3/9-internal-workflows/9.2-voucher-payments)
* **9.3** [**P2G Bill Payments**](/development-3/9-internal-workflows/9.3-p2g-bill-payments)
* **9.4** [**G2B Bulk Payments**](/development-3/9-internal-workflows/9.4-government-to-business-g2b)
* **9.5** [**B2G Bill Payments**](/development-3/9-internal-workflows/9.5-business-to-government-b2g)
# 9.1 G2P Bulk Payment
This section discusses the various processes involved in G2P disbursement, such as beneficiary onboarding into the Account Mapper, bulk disbursements to pre-registered financial addresses, and account pre-validation prior to bulk disbursement. This section includes considerations for a Multiple Independent Currency model.
### 9.1.1 Beneficiary onboarding in Account Mapper
The workflow represents the process of onboarding beneficiaries in the ID Mapper as a prerequisite step before any payment processing can occur. This use case is triggered when a new G2P beneficiary has been onboarded by a G2P program, assigned a Functional ID, and verified as eligible for the social benefit program.
In the Multicurrency case the G2P program which is associated with a payment account in a currency must match the currency of the account the individual receives the payment in. Therefore Steps 1-3 in the below workflow are indicative of steps needed in the **Registration Building Block** to ensure this
```mermaid
sequenceDiagram
note left of RBB: Functional ID is issued to Beneficiary, Request parameters can be json array for bulk onboarding
note left of RBB: Ascertain currency offered, decide Program ID based on currency and use it for onboarding
RBB -->> IM: Register_Beneficiary (Request ID, Source BB ID, Array of Beneficiaries)
IM -->> PBB: Register_Beneficiary (Request ID, Source BB ID, Array of Beneficiaries)
note left of PBB: Validate parameters, Authenticate source Building Block exists
PBB -->> AM: Register_Beneficiary (Request ID, Source BB ID, Array of Beneficiaries)
note left of AM: For each Payee Functional ID, Duplicate Check, Register in mapper
AM -->> PBB: Register_Beneficiary_Response(Request_ID, Response Code, Array of Failed cases)
PBB -->> IM: Register_Beneficiary_Response(Request_ID, Response Code, Array of Failed cases)
IM -->> RBB: Register_Beneficiary_Response(Request_ID, Response Code, Array of Failed cases)
```
1. *(Step needed for Multiple Independent Currencies Approach)* The requesting Building Block, ascertains the currency of the beneficiary from those offered by the government.
2. *(Step needed for Multiple Independent Currencies Approach)* The requesting Building Block decides the correct program ID based on the offered currency and the currency to be paid to the beneficiary (they must match)
3. *(Step needed for Multiple Independent Currencies Approach)* The requesting Building Block uses this program ID as the basis for following steps 4-11.
4. The requesting Building Block (RBB) sends a "Register\_Beneficiary" request to the Information Mediator (IM), containing the Request ID, Source Building Block (SBB) ID, and an array of beneficiaries with their Functional ID, Payment Modality, and Financial Address (if available).
5. IM forwards the "Register\_Beneficiary" request to the Payments Building Block (PBB) with the same parameters.
6. PBB validates the API parameters and checks if the Source Building Block is configured in the Payments BB as an acceptable source of the API call.
7. If the parameters are valid, PBB sends the "Register\_Beneficiary" request to the Account Mapper (AM) with the same parameters.
8. Account Mapper checks for duplicate Functional IDs registered by the same Source Building Block and registers the beneficiaries in the mapper if they are not already registered.
9. Account Mapper sends a "Register\_Beneficiary\_Response" to PBB, which contains the Request ID, response code, and an array of failed cases (if any) with descriptions.
10. PBB forwards the "Register\_Beneficiary\_Response" to IM, with the same parameters.
11. Finally, IM sends the "Register\_Beneficiary\_Response" to RBB, providing the final response code and the list of any failed cases with descriptions.
The workflow supports the addition of beneficiaries in the mapper in bulk. The source building block can use the same APIs for individual or bulk onboarding.
### 9.1.2 Pre-validation of accounts prior to bulk disbursement
This flow represents the pre-validation process of accounts in a bulk disbursement scenario. The process involves a Source BB (SBB), the Payments BB (PBB), a Payer Bank (PrBank), and Payee Bank (PyBank). To support multicurrency use cases, the currency parameter must be passed.
```mermaid
sequenceDiagram
title Pre-validation of Accounts
note right of SBB: Prepare bulk disbursement instructions containing 1. Functional ID 2. Amount 3. Currency 4. Description/Narration 4. Instruction ID
SBB -> PBB: Prepayment_Validation(Batch_ID, Payment Instructions)
note left of PBB: 1. Debulking 2. Check each Payee Functional ID in mapper 3. Record Failed Instructions
loop Send Payee Bank wise sub-batches
PBB -> PrBank: Bulk_ValidateAccount (Batch_ID, Destination_BIC, Payment Instructions)
PrBank -> PyBank: Account Validation Request as per Incumbent Scheme Norm
note left of PyBank: 1. Validate A/C exists 2. Validate it can receive Credit 3. Validate Credit limit won't exhaust
PyBank -> PrBank: Account Validation Response as per Incumbent Scheme Norm
PrBank -> PBB: BulkValidateAccount_Response (Batch_ID, Array of Failed Instructions)
end
PBB -> SBB: Prepayment_Validation_Response(Batch_ID, Array of Failed Instructions)
```
1. The process begins with the Source BB (SBB) preparing bulk disbursement instructions containing key information such as the Functional ID, amount, currency (for multicurrency), narration, and instruction ID.
2. SBB sends these instructions as a pre-payment validation request (Prepayment\_Validation) to Payments BB (PBB).
3. Upon receiving the request, PBB performs several actions, including debulking the instructions, checking each payee's Functional ID in the mapper, and recording any failed instructions.
4. PBB then sends payee bank-wise sub-batches for validation in a loop. For each sub-batch, PBB sends a bulk validate account request (Bulk\_ValidateAccount) to the Payer Bank (PrBank), including the batch ID, destination BIC, and payment instructions.
5. PrBank forwards the account validation request to the Payee Bank (PyBank) as per the incumbent scheme norm.
6. PyBank performs several validation checks, such as confirming the account exists, verifying that it can receive credit, and ensuring that the credit limit won't be exhausted.
7. PyBank sends an account validation response back to PrBank, adhering to the incumbent scheme norm.
8. PrBank then sends a bulk validate account response (BulkValidateAccount\_Response) to PBB, containing the batch ID and an array of any failed instructions.
9. Finally, PBB sends a prepayment validation response (Prepayment\_Validation\_Response) to SBB, including the batch ID and an array of any failed instructions.
This flow ensures that the accounts involved in a bulk disbursement transaction are valid and capable of receiving the specified credits before processing payments, reducing the risk of failed transactions and improving overall efficiency.
### **9.1.3** Bulk Disbursement into a Financial Address pre-registered in the Account Mapper
The workflow depicted below illustrates the process of bulk disbursement into financial addresses, such as bank accounts or mobile wallets, that are pre-registered in the [Account Mapper](/development-3/3-terminology#account-mapper-or-account-lookup-directory-service). This use case is triggered when the Source BB submits a batch for processing of payments to the Payments BB.
Pre-conditions: Functional IDs intended to be recipients of funds must be pre-registered in the Account Mapper. All the financial addresses must be validated before a payment is disbursed.
Data Inputs: Source BB provides relevant confirmation to the Payments BB to begin credit transfer for successfully pre-validated accounts.
```mermaid
sequenceDiagram
title Bulk Disbursement into an online Financial Address
SBB ->> PBB: BulkPayment(Batch_ID, Payment Instructions)
PBB ->> PrBank: getAuthorization()
PrBank ->> PBB: getAuthorization_Response()
loop Send Payee Bank wise Sub-Batches
PBB ->> PrBank: BulkPayment_ReceiverFI(Batch_ID, Destination_BIC, Payment Instructions)
end
note over PrBank: Payer Bank processes each Receiving FI Batch and processes instructions as batch or single instructions, depending on available transaction rails.
PrBank ->> PBB: BulkPayment_StatusPush(BatchID, Credit Instructions)
```
1. The process starts with Source Building Block (SBB) sending a BulkPayment request containing a Batch\_ID and a set of payment instructions to the Payment Building Block (PBB).
2. PBB checks if liquidity was provisioned before this batch is executed and if sufficient liquidity was provisioned. If this is the case, PBB proceeds to de-bulk crediting batches by the receiving institution.
3. PBB then requests authorization from the PrBank by sending a getAuthorization() message.
4. PrBank responds with a getAuthorization\_Response() message, granting the required authorization to PBB.
5. PBB begins sending payee bank-wise sub-batches to PrBank in a loop. For each sub-batch, PBB sends a BulkPayment\_ReceiverFI message containing the Batch\_ID, Destination\_BIC, and payment instructions.
6. The Payer Bank (PrBank) executes these batches through existing rails.
Exceptions: Some accounts might have been pre-validated or part of the crediting batch but cannot be credited by the payee bank for some reason. For such accounts, funds must be returned to the payer bank and credited back into the Source BB's Settlement Account through a separate process.
In order to facilitate the transfer of funds from the disbursement organisation (the payer) to the mobile money provider, the mobile money provider would need to be connected to the payment gateway/switch. Should this connection not be in place, the disbursement could be facilitated by a third-party aggregator or there would need to be a bilateral connection between the payer’s Financial Service Provider and the Mobile Money Provider.
# 9.2 Voucher Payments
The Voucher Management System supports three workflows for voucher payments:
1. administration (voucher provisioning and merchant registration),
2. voucher issuing (pre-activation and activation),
3. redemption use cases as shown in the diagram below.
These use cases and the relationship between each one of them are shown and further described below.
The use cases are described in the diagram below:
```mermaid
graph TD
Voucher_provisioning --> Voucher_Printing --> Merchant_Redemption
Voucher_Printing --> Agent_Cashout
Merchant_Registration --> Merchant_Redemption
```
### **9.2.1 Voucher administration**
These processes are usually done prior to the issuance of the voucher to ensure a smooth flow at the point of issuance.
The Admin processes for the Voucher Management Server cover the lifecycle of the vouchers and are typically performed by a privileged user (this may be done through User Interface or an API). These processes include but are not limited to creating voucher groups, provisioning vouchers, suspending vouchers, un-suspending vouchers, validating vouchers, key management, and purging of used vouchers.
#### Voucher Provisioning
This function will be done by an administrator (privileged user). It will typically be triggered by the deposit of funds in a funding account, thus the source account. Voucher provisioning creates a conditional right to funds and an inventory of issued vouchers. Other processes related to this are voucher inventory management, voucher suspension, and voucher purging.
#### Merchant Registration
In order for efficient redemption of vouchers merchants MUST be registered in advance to create a network of trusted providers. This registration is assumed to be managed by the Registration Building Block, The account verification of the merchant can be done at registration or during redemption subject to a configuration.\
\
During the registration process, merchants MAY also be assigned to different voucher groups depending on the required function that has been implemented. For example, there may be a voucher group for schools. This implies that vouchers of this type can only be redeemed at schools. This also requires that the user flow system at which the voucher is issued is aware of these voucher groups and is able to send the appropriate request to the Voucher Management System.
#### Agent Registration
In markets where cashouts are being used, it is expected that the Registration Building Block will register agents in a similar way.
#### Voucher Groups
Depending on the requirement it should also be possible to set up multiple voucher groups. Vouchers in the same voucher group will have similar characteristics and are labeled with a specific voucher group name. During voucher provisioning, a voucher can be created and attached to a single voucher group. When a voucher is requested (using the pre-activation API) it is expected that the voucher group will be one of the parameters set.
#### Voucher Issuing
Voucher issuing is triggered by the Registration Building Block which will determine whether the conditions of issuance have been met. The calling Block will determine the denomination and voucher group of the voucher to be issued. The voucher number and the voucher serial number that is issued can be presented to the beneficiary in multiple ways including but not restricted to encoding in the form of QR codes, bar codes, printed vouchers, or even SMS. This is outside the scope of the Payments Building Block. It is expected that Building Blocks through which the voucher is redeemed will also be able to decode the voucher.
### **9.2.2 Voucher Activation workflow**
The voucher activation flow is shown in the diagram below.
```mermaid
sequenceDiagram
title Voucher Activation v3
Source BB->Payment BB: Activate voucher
Payment BB-->Source BB: Voucher successfully activated
alt Error 400
Payment BB-->Source BB: Invalid request
end
alt Error 456
Payment BB-->>Source BB: Invalid voucher serial number
end
alt Error 460
Payment BB-->Source BB: GovStack Building Block does not exist
end
alt Error 455
Payment BB-->Source BB: Voucher group exhausted
end
alt Error 500
Payment BB-->Source BB: Internal Server Error
end
alt Error 503
Payment BB-->Source BB: Service Unavailable
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end
```
#### Flow Description:
* An external Building Block may invoke the Payments Building Block API gateway to pre-activate API on the Voucher Management Server with the amount of the voucher, the voucher currency, and the voucher group. The calling Building Block may optionally send a comment. The comment will be stored by the voucher server. The voucher group will indicate that it is looking for a voucher from a specific voucher group. This API call will be made through the Payments orchestrator.
* The voucher group is typically used for conditional social transfer (e.g. for school fee payment). If any voucher can be used for any purpose, then all vouchers should be created with a generic voucher group (e.g. “GENERAL-PURPOSE”).
* The API returns to get a voucher number, the voucher serial number, and its expiry date. At this point, the voucher will be flagged as Pre-Activated.
* The calling Building Block may render the voucher as a QR code, as a barcode, or even as an SMS text. It is recommended that the voucher should include supplementary data of the recipient. It is also recommended that this data should also be printed in human-readable form so that the recipient can verify the data on the voucher. This data can also be verified at the point of redemption.
* Once the calling API successfully prints/issues the QR code, the voucher can then be activated using the activation API. It is assumed that there will not be a substantial delay between pre-activation and activation to necessitate the need for multiple expiry periods.
#### Alternative:
The voucher could be activated immediately on being requested. This could be controlled at the Payments Orchestrator.
#### Preconditions:
* The calling registration block will determine that all the necessary preconditions are met.
* The most critical precondition is the prefunding which will be done manually at the voucher provisioning stage. Other options that could be prefunding triggered by activation or at redemption are not considered because they are considerably more complex and create additional failure points in the activation of the vouchers.
#### Assumptions/Queries
* It is assumed that only one currency will be used.
* A zero-trust architecture.
* The transaction is not reversible.
#### Post-Condition
The calling Building Block may invoke another payment Building Block API, e.g. initiating an incentive payment for the agent.
### **9.2.3 Voucher redemption workflow**
The voucher redemption process is shown in the diagram below.
```mermaid
sequenceDiagram
title Voucher Redemption
Source BB (Merchant Interface) ->> Merchant registry: Submit voucher details
Merchant registry -->> Source BB (Merchant Interface): Merchant name and payment details
Source BB (Merchant Interface) ->> Payment BB: Submit voucher and merchant details
alt Error 400
Payment BB-->>Source BB (Merchant Interface): Invalid request
end
Payment BB ->> Payment BB: Check Voucher
alt Error 458
Payment BB-->>Source BB (Merchant Interface): Voucher number already used
end
alt Error 461
Payment BB-->>Source BB (Merchant Interface): Invalid voucher number
end
Payment BB->>FSP: Debit request
alt Error 599
Payment BB-->>Source BB (Merchant Interface): Network connection error
end
FSP->Funding A/c: Debit request
Funding A/c -->> FSP: Debit successful
alt Error 462
FSP -->> Payment BB: Insufficient funds
Payment BB -->> Source BB (Merchant Interface): Insufficient funds
end
FSP->Merchant A/c: Credit Request
Merchant A/c -->> FSP: Credit Request successful
alt Error 463
FSP -->> Payment BB: Cannot credit merchant
Payment BB -->> Source BB (Merchant Interface): Cannot credit merchant
end
Payment BB ->> Payment BB: Consume Voucher
Payment BB ->> Source BB (Merchant Interface): Amount credited to merchant account and voucher is consumed
```
#### Flow Description:
* At redemption, the beneficiary shows the voucher to the merchant or agent.
* The merchant/agent will scan and interpret the medium in which the voucher is presented (this could be a QR code or a barcode or an SMS or even a printed number).
* Voucher redemption Validation: The details presented MAY allow the merchant/agent to authenticate/validate the owner of the voucher.
* The agent will then initiate the redemption process which will call the Payment Building Block API Management Gateway.
* The API Management Gateway will validate the voucher and initiate the payment through the payment gateway.
* If specific voucher groups have been set up, voucher usage may be restricted to specific merchants. An override parameter should also be provided that will allow a Voucher of any voucher group to be redeemed at any merchant.
* Once the payment to the merchant/agent is successful the Payment gateway will inform the API Management Gateway.
* The API Management Gateway will then instruct the VMS API to flag the voucher as consumed.
#### Alternatives:
* Payments could be made through a switch in which case there would be no need for prefunding accounts in each financial institution.
#### Preconditions:
* The merchant must have been registered possibly by the Registration Building Block with their preferred payment method.
* The merchant must have a mechanism (e.g. a mobile APP, USSD app, or SMS option) to verify the beneficiary prior to redemption.
#### Assumptions:
* The app for reading the QR code and redemption is not part of the scope of the Payment Building Block.
* The entire voucher amount is consumed. Partial redemption will not be allowed.
* The amount that is paid to the merchant or agent is debited from a prefunded account.
#### Sample Redemption:
.png?alt=media)
{% hint style="info" %}
In the case of a physical voucher, the voucher number or the secret number is hidden behind some material that must be scratched away to see the number. The voucher number is also commonly known as the PIN.
{% endhint %}
### **9.2.4 Voucher cancellation workflow**
The voucher cancellation flow is shown in the diagram below.
```mermaid
sequenceDiagram
title Voucher Cancellation
Source BB -> Payment BB: Cancel Voucher
Payment BB-->Source BB: Voucher Cancelled
alt Error 499
Payment BB-->Source BB: Invalid Request
end
alt Error 463
Payment BB-->Source BB: Invalid Voucher
end
alt Error 464
Payment BB-->Source BB: Voucher is already cancelled
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end
```
#### Flow Description:
* The calling Building Block will request the API Management Gateway to cancel a Voucher.
* The API Management Gateway will invoke the VMS API to cancel the Voucher.
* The Vaucher Management System (VMS) API interface will check if the Voucher is valid and then cancel the Voucher.
* The VMS API interface will confirm that the Voucher has been canceled.
#### Alternatives:
* If the Voucher does not exist, the VMS API will respond that the Voucher does not exist.
* If the Voucher is already consumed, the VMS API will respond that the Voucher is already consumed.
* If the Voucher is already canceled the VMS API will respond that the Voucher is already canceled.
* If the Voucher is suspended the VMS API will respond that the Voucher is suspended.
* All calls from external parties (e.g. Registration Building Block) to the voucher management system will be initiated through the API management gateway.
* The payment orchestration module may direct transitions between the various functions.
* The discovery service could be called by other building blocks to determine where bank accounts/wallets sit.
* The only function that speaks to the DFS is the payment gateway. Any function that needs to speak to the DFS goes through the Payment gateway.
* The Payment gateway may need to speak to a Number Portability provider.
* Audit trails (transaction logs) capture each event as it happens and are to be used for queries, analysis, and reconciliation.
* Event logs will capture specific events that happen at each node.
# 9.3 P2G Bill Payments
The following types of P2G payments are considered.
* Bill payments such as utilities
* Payments for government services (for example application for a birth certificate)
The following is assumed for bill payment with the Payments BB
* The Bill ID generation or distribution scenario of a jurisdiction is already decided and in place.
* Depending upon the applicable scenario all relevant billers, aggregators or bill payment systems responsible for distributing the Bill IDs to consumers, are also registered with the Payments BB.
* The Settlement of bill amounts is carried out by the relevant payers and payee FSPs.
* The Payments BB will generate a report or allow a data extract that would contain the log of transactions that would be used for settlement of the transactions between the Payer FSP and the Billers or Aggregators FSPs
In order to support multicurrency payments, currency is an important consideration to ensure that bills are paid in the currency raised, as such currency would need to be indicated on bills and payments as indicated in the diagram in section 9.3.3.
The following processes are involved in government bill payments:
### **9.3.1 Biller onboarding**
The biller onboarding would be a one–time prerequisite activity required to be carried out before consumers could pay bills to them.
The main function of Payment BB in this case is allocating unique IDs to the registering entity and ensuring that all Bill Payment related queries are routed to these registered entities.
The relationship between billers and aggregators and how they identify specific bills from the consumers numbers is their responsibility, and is out-of-scope for Payments BB.
Biller/Aggregator Onboarding
#### Pre-conditions:
* The structure of the unique ID is defined including, the length of the unique ID and whether the ID is simply a sequential number or if each digit of the ID identifies any unique entity/actions.
The incoming biller/ aggregator has the required infra to support continuous requests and updates.
#### Flow description:
* Onboarding Request: This step could be a manual process where a representative gathers all the required information from the billers and aggregators and enters it into the system via a UI-based form/ table. (This process may go through the make checker process)
* Unique IDs and Prefixes are generated by the system for each direct biller or aggregator (depending upon the billing ecosystem model). The entire information is saved in the system in the ‘Billers Table’.
* The billers and aggregators are returned a unique ID and prefix allocated to them.
* The billers and aggregators concatenate the unique ID and prefix before the Bill IDs that they generate and share with their consumers.
### **9.3.2 Payer Financial Institution – PBB Linking for Bill Payments**
The Payer FI – PBB linking is a one–time prerequisite activity required before consumers can request bill payment over the Payments BB. Setting up of the front end, UI to take the requests from the consumers would fall under the responsibility of the Payer FI only and would be out of the scope of payments BB
#### Pre-conditions:
* The Payer FSP is enabled for Interbank Funds Transfer (for settlement) – Out of Scope of PBB
* The Payer FSP is equipped with the right infrastructure to communicate with the PBB
#### Flow description:
Payer FSP – PBB Linking would be an offline process comprising formal agreements and the following activities to ensure proper functioning:
* PBB shares the list of Billers and the unique IDs allotted to them with the Payer FSP
* PBB shares its endpoints and required API contracts that need to be setup at the FSP;
* PBB shares the *required* Bank and Account Details of each registered Biller with the FSP for carrying out financial transactions and settlement activities. The biller details could be either manually configured by the Payer FSP at their end or Payments BB could prepare a file and keep it at a central location for Payer FSP to download/ upload it (as decided).
#### Post-conditions:
Once the Payer FSP is setup with PBB for Bill Payment Services then it is expected that it:
* Would be able to accept from its customers Bill IDs of different Billers.
* Would be able to differentiate at its end the exact biller/ aggregator for which the customer has entered the Bill ID.
* Would be able to credit the respective account of the biller based on the account information shared by PBB at the time of linking.
* Would duly notify the PBB of the final status of the Bill Payment Request (successful debit/ Failed debit)
### **9**.3.3 Bill Inquiry & Bill Payment Update via Payment BB
After the completion of the prerequisite setups, the Payment BB is ready to accept requests from the Payer FSPs and retrieve information from and communicate with the Billers, Aggregators, and Government Entities.
#### Main responsibilities of Payment BB in the flow:
1. The PBB would receive the Bill Inquiry as a result of Pay Bill request at a Payer FI – Payer end.
2. PBB would validate the sender of request and send it on to the respective Biller or Govt. Entity to fetch bill.
3. The Payer FSP would then either perform payment confirmation or abort the transaction – in either case it would notify the PBB of the Payment Status
4. Receiving the Payment Status Update the PBB would forward the Payment confirmation to Biller or Govt. Entity
5. PBB sends Mark Bill Paid Advice to the Biller or Govt Entity until a response is received from that site.
6. Upon receiving a response from the Biller or Aggregator, the PBB would notify the Payer FSP of the response.
7. The Government Agency sends an invoice to the payer, detailing the amount owed.
8. The Government Agency also sends a copy of the invoice to the designated Bill Aggregator.
9. The Bill Aggregator then sends the invoice reference number to the Payments Building Block .
10. The payer, upon receiving the invoice, provides the invoice reference number to their preferred Collection Financial Service Provider (Collection Financial Services Provider).
11. The Collection Financial Services Provider (FSP) requests transaction details, including the amount to be paid, currency (for multicurrency) from the Payments Building Block using the invoice reference number.
12. The Payments Building Block, in turn, requests the transaction details from the Bill Aggregator.
13. The Bill Aggregator provides the requested transaction details to the Payments Building Block.
14. The Payments Building Block forwards the transaction details to the Collection FSP.
15. The Collection FSP executes the payment based on the transaction details provided.
16. After completing the payment, the Collection FSP sends the payment reference to the Payments Building Block.
17. The Payments Building Block forwards the payment reference to the Bill Aggregator.
18. Finally, the Bill Aggregator sends the payment reference to the Government Agency, confirming the completion of the payment.
```mermaid
sequenceDiagram
title Push Payment Flow with Bill Inquiry
title P2G Bill Payment via RTP
participant "Payer FI" as PayerFI
participant PaymentsBB
participant ALS
participant "Bill Aggregator GovtEntity" as BillAggregator
BillAggregator->>PaymentsBB: 1. billerRtpReq (txnID, rtpId, billId, requestType, aliasID (C))
PaymentsBB-->>BillAggregator: billerRtpReq (Ack)
alt RTP Type = 00
note over PaymentsBB: Jump to "SEND RTP TO PAYER FI" Step
else RTP Type = 01
PaymentsBB->>* ALS: Bill ID is routed to lookup service.
ALS->>PaymentsBB: Returns back with Payer FI details.
note over PaymentsBB: Jump to "SEND RTP TO PAYER FI" Step
end
note over PaymentsBB, PayerFI: SEND RTP TO PAYER FI
PaymentsBB->>PayerFI: 2. payerRtpReq (txnId, billId, [Bill Details])
PayerFI-->>PaymentsBB: payerRtpResp (Ack)
note over PayerFI: Initiate "RTP Notification Sequence - Customer<->FSP"
PayerFI->>PaymentsBB: 3. payerRtpResp(txnId, referenceId)
PaymentsBB-->>PayerFI: payerRtpResp (Ack)
PaymentsBB->>BillAggregator: 4. billerRtpResp (txnId, paymentStatus, referenceId)
BillAggregator-->>PaymentsBB: billerRtpResp (Ack)
opt If BillAggregator requires status update
BillAggregator->>PaymentsBB: rtpStatusUpdate (txnId, rtpID)_Req
PaymentsBB-->>BillAggregator: rtpStatusUpdate (Status Code)_Resp
end
note over PayerFI, BillAggregator: BILL PAYMENT STATUS STAGE
note over PayerFI: Initiate "LEG2:PayBill Sequence - Customer/FSP"
PayerFI->>PaymentsBB: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Req
PaymentsBB-->>PayerFI: paymentStatusUpdate(Ack)
note over PaymentsBB, BillAggregator: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB->>BillAggregator: markBillPaid(Bill ID, ReceiptNum, PaymentStatus)_Req
note right of PaymentsBB: Payments BB keeps sending Bill Payment Advice to BillAggregator until Response received from BillAggregator
end
BillAggregator-->>PaymentsBB: markBillPaid (Ack)
BillAggregator->>PaymentsBB: markBillPaid(MarkStatus, RespCode(C))_Resp
PaymentsBB->>PayerFI: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Resp
PayerFI-->>PaymentsBB: paymentStatusUpdate(Ack)
```
#### 1. Bill inquiry stage
* **Payer FI** initiates the process by querying bill details.
* **Payer FI** requests bill inquiry using `billInq(Txn ID, Bill ID)_Req`.
* **PaymentsBB** validates the request, performing security checks and registration status verification.
* If validations fail, **PaymentsBB** sends an error response to **Payer FI**.
* If validations succeed, **PaymentsBB** identifies the biller and moves to the next step.
#### 2. Biller discovery
* **PaymentsBB** identifies the biller by querying the **Billers Table** using `IdentifyBiller(Prefix)`.
* **Billers Table** provides **PaymentsBB** with the Biller's endpoint information.
* **PaymentsBB** then proceeds to fetch the bill from the **Bill Aggregator/Government Entity**.
#### 3. Fetch Bill
* **PaymentsBB** requests bill details from **Bill Aggregator or Government Entity** using `billInqBiller(Bill ID)`.
* **Bill Aggregator or Government Entity** performs internal checks (e.g., payment status, expiry) and responds with bill details.
* **PaymentsBB** forwards bill details to **Payer FI** for review.
#### 4. Bill Payment Status
* **Payer FI** reviews the bill details and initiates the payment sequence.
* **Payer FI** updates the payment status using `paymentStatusUpdate(Payment Status, Txn ID, RespCode)`.
* **PaymentsBB** acknowledges the update and marks the bill as "PAID" in the request sequence.
* **PaymentsBB** sends payment advice to **Bill Aggregator or Government Entity** until a response is received.
* Once confirmed, **Bill Aggregator or Government Entity** acknowledges the payment and updates the status.
* Finally, **PaymentsBB** notifies **Payer FI** of the successful payment update
### 9.3.4 Payer FI – Customer Bill Payment Flow
```mermaid
sequenceDiagram
title PayBill Sequence - Customer/FSP
participant Payer as Payer
participant PayerFI as Payer FI
note over Payer, PayerFI: LEG 1: BILL PAYMENT REQUEST
Payer->>PayerFI: Pay_Bill_Req (Bill ID)
note right of PayerFI: Forwards billInquiry (Bill ID)_Req to PBB
note left of PayerFI: Receives billInquiry_Resp from PBB
PayerFI->>Payer: Pay_Bill_Resp (Biller Name, Due Date Amount, Currency, Bill Status )
note over Payer, PayerFI: LEG 2: BILL PAYMENT CONFIRMATION
Payer-->>PayerFI: Confirms Bill Payment
PayerFI->>PayerFI: Performs Account Validations Identifies the Biller Account
note over PayerFI: Logs Txn_Success_Ref ID OR Txn_Fail_Ref ID
alt If Validations OK
PayerFI->>PayerFI: Debits Payer's Account
PayerFI->>Payer: Sends Payment Receipt (Txn_Success_Ref ID)
PayerFI->>Payer: Account/Wallet Debited - Bill Paid (Txn_Success_Ref ID)
Note right of PayerFI: Initiates: "(PBB) BILL PAYMENT STATUS STAGE" Calls PAYER BB API -> paymentStatusUpdate
else If Validations KO
PayerFI->>PayerFI: No Debit
PayerFI->>Payer: Sends Txn Failure Message (Txn_Fail_Ref ID)
note right of PayerFI: Bill Paid Status (Txn_Fail_Ref ID)
end
```
### 9.3.5 P2G bill payment via request to pay flow
```mermaid
sequenceDiagram
title P2G Bill Payment via RTP
participant PayerFI as Payer FI
participant PaymentsBB as PaymentsBB
participant ALS as ALS
participant BillAggregator as Bill Aggregator GovtEntity
BillAggregator->>PaymentsBB: 1. billerRtpReq (txnID, rtpId, billId, requestType, aliasID (C))
PaymentsBB-->>BillAggregator: billerRtpReq (Ack)
alt RTP Type = 00
PaymentsBB->>PayerFI: Jump to "SEND RTP TO PAYER FI" Step
else RTP Type = 01
PaymentsBB->>+ALS: Bill ID is routed to lookup service.
ALS->>PaymentsBB: Returns back with Payer FI details.
PaymentsBB->>PayerFI: Jump to "SEND RTP TO PAYER FI" Step
end
Note over PaymentsBB, PayerFI: SEND RTP TO PAYER FI
PaymentsBB->>PayerFI: 2. payerRtpReq (txnId, billId, [Bill Details])
PayerFI-->>PaymentsBB: payerRtpResp (Ack)
Note over PayerFI: Initiate "RTP Notification Sequence - Customer<->FSP"
PayerFI->>PaymentsBB: 3. payerRtpResp (txnId, referenceId)
PaymentsBB-->>PayerFI: payerRtpResp (Ack)
PaymentsBB->>BillAggregator: 4.billerRtpResp (txnId, paymentStatus, referenceId)
BillAggregator-->>PaymentsBB: billerRtpResp (Ack)
opt If BillAggregator requires status update
BillAggregator->>PaymentsBB: rtpStatusUpdate (txnId, rtpID)_Req
PaymentsBB-->>BillAggregator: rtpStatusUpdate (Status Code)_Resp
end
Note over PayerFI, BillAggregator: BILL PAYMENT STATUS STAGE
Note over PayerFI: Initiate "LEG2:PayBill Sequence - Customer FSP"
PayerFI->>PaymentsBB: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Req
PaymentsBB-->>PayerFI: paymentStatusUpdate(Ack)
Note over PaymentsBB, BillAggregator: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB->>BillAggregator: markBillPaid(Bill ID, ReceiptNum, PaymentStatus)_Req
BillAggregator-->>PaymentsBB: markBillPaid (ack)
end
BillAggregator->>PaymentsBB: markBillPaid(MarkStatus, RespCode(C))_Resp
PaymentsBB->>PayerFI: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Resp
PayerFI-->>PaymentsBB: paymentStatusUpdate(Ack)
```
### 9.3.6 P2G bill payment with voucher
```mermaid
sequenceDiagram
title Payment By Voucher
participant Payer FI as PR
participant PaymentsBB as PBB
participant Voucher Engine as V
participant Biller as Biller
note over PR: Bill Inquiry is Done - For Bill Payment "Voucher" is chosen as option
note over Payer FI, Biller: BILL PAYMENT STATUS STAGE
PR ->> PBB: voucherRedemptionforBillPayment (BillInquiryCorrelationID, Bill Details, Voucher Secret Code)
note over PBB: PBB receives API Call with Voucher as well as Bill Details.
PBB ->> V: VOUCHER REDEMPTION
note over PBB,V: PAYBB checks that Voucher is valid, Voucher Amount and Bill Amount are same
PBB ->> V: VoucherInquiry(Secret Code)
V -->> PBB: VoucherInquiry_Response
note over PBB: Check Voucher Value, Bill Value, Check Compatibility. If Okay, Redeem. Else, Cancel
PBB ->> V: redemptionWithoutAuthentication_Request
V -->> PBB: redemptionWithoutAuthentication_Response
PBB --x V: destroy V
PBB -->> PR: voucherRedemptionforBillPayment(Status)_Resp
note over PBB, Biller: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB ->> Biller: markBillPaid(Bill ID, ReceiptNum, PaymentStatus)_Req
note right of PaymentsBB: Payments BB keeps sending Bill Payment Advice to Biller until Response received from Biller
end
Biller -->> PaymentsBB: markBillPaid(ack)
Biller -->> PaymentsBB: markBillPaid(MarkStatus, RespCode(C))_Resp
PaymentsBB ->> PR: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Resp
Payer FI -->> PaymentsBB: paymentStatusUpdate(ack)
```
# 9.4 Government to Business (G2B)
### 9.4.1 Generic G2B Workflow for Registration and Payment
The following diagram shows a happy path generic workflow for Registration and Payments for a G2B scheme:
#### **Assumptions:**
* That the Government Registration Program is a BB such as the [Registration](https://registration.govstack.global/) BB
* KYC - “Know your Customer” is inclusive of KYB “Know your Business”
* All interactions with the Payment BB will go via the [Information Mediator](https://mediator.govstack.global/) BB as per GovStack specification even where not shown for clarity in the workflow
* [Messaging](https://messaging.govstack.global/) or [Scheduler](https://scheduler.govstack.global/) BB’s could be used when defined for notifications
#### **Workflow covers:**
* Registration Flow and storing of Payment Details
* Payment flows
#### **Workflow excludes:**
* Audit
* Unhappy path flows
#### **Key callouts:**
* There may need to be 2 ID’s verified, that of the Business and that of the Individual acting on behalf of the business (TO BE EXPLORED).
* [Identity](https://identity.govstack.global/) BB currently only considered individual ID therefore this has an impact on the current [Identity](https://identity.govstack.global/) BB specification
* Currently in the workflow existing Pay-BB API definitions can be used
### 9.4.2 Example workflow for **Government to Business loan**
In this example the government has a scheme where they provide loans to small businesses on preferential terms to encourage small business development. This example could also apply to small business loans needed for disaster recovery (The UK offered such loans during Covid19).
#### **Assumptions:**
* That the loan scheme is not part of the Payments BB (could be an independent system or BB that is yet to be defined)
* KYC - “Know your Customer” is inclusive of KYB “Know your Business”
* This is giving an example loan scheme but is not inclusive of all steps within that as we are not defining the loan-scheme in this BB
* This example covers a normal Business type loan, it is not intended for guarantee loans where the Government is not the loan provider
* All interactions with the Payment BB will go via the [Information Mediator](https://mediator.govstack.global/) BB as per GovStack specification even where not shown for clarity in the workflow
* [Messaging](https://messaging.govstack.global/) or [Scheduler](https://scheduler.govstack.global/) BB’s could be used when defined for notifications and loan schedules
#### **Workflow covers:**
* Loan Setup and Payment
#### **Workflow excludes:**
* Loan Repayment flows these would be a B2G flow
* Audit
* Unhappy path flows
* Detail of Loan system internal flows
#### **Key Callouts:**
* There may need to be 2 ID’s verified, that of the Business and that of the Individual acting on behalf of the business (TO BE EXPLORED).
* [Identity](https://identity.govstack.global/) BB currently only considered individual ID therefore this has an impact on the current identity BB specification
* Currently in the workflow existing Payments BB API definitions can be used (needs to continue to be assessed with any changes)
# 9.5 Business to Government (B2G)
### 9.5.1 Example workflow of a business paying for government services and refuse collection
In this example the local Government provides a refuse collection service to local businesses this consists of both regular collections and the ability to request additional collections. These services are chargeable by the local Government to the local businesses.
If we look at the existing Person to Government (P2G) payment use-case we see that within this the flows are agnostic of if the Payer is an individual or a business and the ID of the Payer is not within the flows or APIs resolving the concerns that arise in G2B payments that need changes to cater for business scenarios.
[Final Versions of Key Documents | P2G v16Oct23](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/490962995/Final+Versions+of+Key+Documents#P2G-v16Oct23)
Hence we can conclude the following flows would be used:
For the regular bills these would follow the Bill Generation and Bill Inquiry workflows with Bills being sent from the Billing Entity to the Payer who would pay with the reference supplied enabling the Payment BB to reconcile the payments to the Billing table.
For the one off charges this would follow a one-time Request to Pay workflow from the Billing entity to the Payer.
The use of a billing aggregator could also be supported for G2B payments without any adjustments foreseen.
\
# 10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
### 10.1 Key Decision Log
[A historical log of key decisions regarding this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183435345/Key+Decision+Log+Payments).
### 10.2 Future Considerations
[A list of topics that may be relevant to future versions of this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183402524/Future+Considerations+Payments).
### 10.3 Out-of-Scope Assumptions
[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/6ERMn830).
# Government to Business (G2B) Use Case
#### Overview:
The broad definition of this scenario is payments made to a business from a Government, these are assumed to be single currency. These can be narrowed down to a set of high-level areas:
* Loans – Where the Government makes a payment to a business with an expectation of repayment in whole or in parts with or without interest.
* Allowances- Where the Government makes a conditional payment to a business. E.g. Agriculture allowance.
* Unconditional Payments- Where the Government makes an unconditional payment to a business. E.g. disaster relief.
* Rebates and Repayments – Where the Government makes a payment based on payments previously having been received, e.g. tax refunds.
* Payments for Services - Where the Government pays a business for a service or work done.
* Financial Aid to NGOs - Where the Government pays an NGO financial aid
* Subsidies - This could be considered similar to Allowances but may bring in a dimension of being ringfenced in what it can be spent on or which merchants it can be spent with. This may bring in an element of Vouchers for consideration.
#### Example 1: Agriculture Subsidies
In a country the government wants to encourage responsible farming and water management practices to produce a sustainable agricutural industry in the country. As such Farmer may register for a Subsidie (Grant) payable to help them with the costs of this transformation. This grant is paid out monthly for registered farmers.
When the farmer applies to the grant program they do so through the Government Registration Portal which captures key information such as name of farm, address of farm, size of farm to establish the payments are valid.
At the end of the registration process the Registration portal working with the ID BB creates a functional ID for the farmer and captures the payments details which are passed and stored in the Payments BB ID account Mapper.
{% hint style="warning" %}
Note currently the ID BB only covers Individual Identities rather than legal entity identities, this functionality is on the ID BB roadmap
{% endhint %}
At the end of the month the Government Agriculture Subsidy program sends a bulk file to the payments building block with the Functional ID of each farmer to be paid and the amount to be paid.
The Payments building block process's this bulk disbursement in a similar fashion to a G2P bulk disbursement. Using the ID Account Mapper to look up the relevant financial details for each Functional ID, validating sufficient funds exist in the government account and then sending financial transaction instructions to the Government Bank Core Banking System in appropriate sized batches. The status of each transaction is returned to the Payments Building Block which can then be investigated by the Government systems if needed to understand the status of batches, sub-batches and individual transactions.
#### Key Points:
The existing Payments Building Block Functional requirements for G2P can be used for a G2B use case along with associated APIs
# Business to Government (B2G) Use Case
#### Overview:
The broad definition of this scenario is payments made from a business to a Government. These can be narrowed down to a set of high-level areas:
* Loan Repayments – Where the Business makes a repayment to a Government either in whole or in parts with or without interest.
* Taxation – Where the Business makes a payment to the Government to cover a taxation obligation either one off or regular.
* Services - Where the Business makes a payment to the Government for a service either one off or regular such as refuse collection.
* Fines - Where the Business makes a payment to the Government to cover a fine
* Customs Duties - Where a Business needs to pay customs duties (this scenario really opens up consideration of cross border and forex)
It may be important to consider cross-border/multi-currency payments depending on if the business is in the same country/region as the government.
#### Example 1: Business Tax Payments
In a country the government has an online tax program where business's complete their tax returns digitally.
Once the tax submission has been made by the business it calculates the Tax due and offers the business 2 ways to pay.
1. Pay in a Single Installment online
2. Pay in multiple instalments over a period of time.
For option 1. the Government tax system invokes the payment Building Block with and RTP (Request to Pay) instruction. The Payments BB then allows for immediate payment via the Businesses FSP (Financial Service Provider) and reconciles the payment with the Government Tax system
For option 2. the Goverment tax system splits the payment due into a number of payments and issues a number of bills with a unique reference number consisting of the biller identifier and a unique ID, using the Bill Generation workflow. As each payment is made by the business the Business FSP makes these payments by using the Bill Inquiry and payment workflows
The Payments building block process's these Bill Payments works in a similar fashion to a P2G functionality.
#### Key Points:
The existing Payments Building Block Functional requirements for P2G can be used for a B2G use case along with associated APIs
# Payments
Developed by Vijay Mauree (ITU), Arnold Kibuuka (ITU), Francesco Pasti (GSMA), James Dailey (MIFOS), Oscar Correia (Maarifa Education), Dr. P. S. Ramkumar (ITU), Khuram Farooq (World Bank), Elie Sawaya (GIZ)
# 1 Version History
The version history table describes the major changes to the specifications between published versions.
| Version | Authors | Comment |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 0.9.2 |
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, Sanjay Jain, Luukas Ilves, Lesley-Ann Vaughan
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume
Reviewers: Wesley Brown, Steve Conrad, Valeria Tafoya
| Final edits to align content to specification template for GovStack 1.0 release |
# 2 Description
This section provides context for this Building Block.
The Payments Building Block enables digital financial payments to be tracked, evaluated, initiated, validated, processed, logged, compared and verified against budget. This Building Block also provides interoperability with connections to the various external applications that need payment services in order to trigger transitions in their own workflow. Payment services generally interface through gateways to regulated financial entities such as banks, credit facilities, and insurance companies. To help users easily complete payment transactions and learn if their transaction succeeded or failed, it converts heterogeneous interface protocols, formats, and user interfaces to a standard set of common interfaces and formats. It can also help in tracking the costs of commodity and equipment purchases to optimize budgets.
The Payments Building Block consists of components that enable multiple use cases in a generic manner. The use cases include Government to Person (G2P), Person to Government (P2G), Government to Business (G2B), and Business to Government (B2G). The existing commercial Payments schemes are heterogeneous across regions and countries, the Payments Building Block assumes that some components are optional when considering implementation. The Payments Building Block covers components that can be used to deliver the key functionalities and the connections to existing systems in the market but does not contemplate building a new Payments scheme.
### Financial Inclusion, Banks, and Mobile Money Accounts
Financial inclusion strategies have largely been based on growing access to regulated accounts. These were traditionally understood to be bank accounts, in recent years Mobile Money (MoMo) accounts have greatly increased transactional account access. These MoMo accounts are often, but not always, treated as secondary to the banking system and lack interoperability.
That said, today, with over 1.2 billion global accounts, transacting an average of over $2 billion per day, mobile money has grown to become the leading payment platform in a growing number of emerging markets. Today, there are more mobile money accounts in Sub-Saharan Africa than there are bank accounts. Indeed, during the pandemic, demand for mobile money services increased among businesses, governments, and new services that previously relied on cash or other payment channels.
There are currently active discussions in many markets that need the integration of mobile money into existing national infrastructure. While the integration of mobile money into existing schemes and infrastructure has the potential to create value for all stakeholders in the ecosystem, many legacy payment systems may not be suitable for mobile money integration in their current state. As an example, many existing interbank switches do not support mobile money as a core feature because of legacy technical architecture. What is often missing is the essential capability of the switch to handle high-volume, low-value flows with the mobile number (Mobile Station Integrated Services Digital Network) as identifier for routing and address resolution hence the need for integration. Recent industry developments offer solutions designed to solve many of the issues around the switching of mobile money.
Mobile money providers, regulators, infrastructure providers, and other financial system players should seek to engage in any potential interoperability initiatives from an early stage to ensure optimal payment system design for all parties. Should existing infrastructure be used, a thorough assessment should be conducted, with input from all parties, to ensure appropriate governance, commercial, and technical standards are incorporated. Mandating interoperability within a short time frame removes opportunities for a thoughtful and holistic analysis of commercial sustainability. Requiring immediate interoperability can also delay or hamper the uptake of interoperable transactions, and mobile money services altogether. This is a particular risk in contexts where regulators or governments impose immediate connections to a centralized hub. Mobile money providers should be encouraged to connect when their service is ready. However alternative modalities of payment such as cash vouchers can also be considered in scenarios of low-resource regions that lack modern infrastructure and a volume of mobile phone users. Also, in countries where mobile money providers are not connected to a payment switch, aggregators can enable the flow of funds between multiple financial service providers including banks and non-banks. While aggregators may not be as efficient and scalable as switches, they can help solve interoperability issues in the short and medium term.
## Payments Building Block Capabilities
Generally, the Building Block is supportive of multiple types of payment use cases where the Government is one of the parties:
* **Government to people (G2P)**
* Payment where the payer is a government and the payee is an individual e.g. Social benefits disbursement, government salary payments, Conditional and [Unconditional Social Cash Transfers](https://solutions.dial.community/use_cases/unconditional_social_cash_transf/use_case_steps/outreach_communications)).
* **People to Government (P2G)**
* Payment where the payer is an individual and the payee is a government. P2G payments can be government initiated, for instance, in the case of payments for registrations for government services. For bill payments and payments for government services directly by the person, the system should provide the person with the flexibility to choose which payment instrument to use (eg. mobile money, bank transfer or card payments). (e.g. payment of taxes, payment[ Registration for Postpartum and Infant Care](https://github.com/GovStackWorkingGroup/BuildingBlockAPI/issues/1), payment of school fees, driving license, utility payments).
* **Government to Business (G2B)**
* G2B payments include tax refunds, goods and services purchases, subsidies, contract payments, benefits, and loans.
* **Business to Government (B2G)**
* B2G payments include paying taxes and fees.
* **Government to Government (G2G)**
* Payments between two government entities (i.e. between Ministries/Departments and public sector institutions).
Government to Business payments (G2B) and Government to Government (G2G) are not covered in this specification and will be covered in the second phase.
## Government-to-Person Payment Principles
The implementation of the Payments Building Block should adhere to the following principles, particularly as it relates to Government-to-Person (G2P) payments:
### Beneficiary/Recipient-related Principles
* Beneficiaries can receive their payment through a fully functional account that allows them to save and make payments using an associated payment instrument with general acceptance.
* They can choose the payment service provider and payment instrument through which they receive their payments based on their informed choice; they can use the same account for multiple G2P payments, make Person-to-government (P2G) payments and easily switch if desired.
* Onboarding to their payment method is low cost and easy with account opening requirements that are available to recipients and with no opening fees; a payment instrument is provided to the recipient at no cost.
* The Integrated Financial Management Information System (IFMIS) is used to process government payments against budgetary allocations. It supports:
* the Treasury Single Account (TSA) that aggregates all incoming government receipts and disburses all government payments;
* budget management to ensure budget compliance, tracking, and reporting. The IFMIS provides the Ministry of Finance with a unified view of the government’s budget execution.
* The payment instrument is easy-to-use and generally accepted, and the overall costs for using it do not result in increased costs for the beneficiary in comparison to other forms of payment.
* Beneficiaries are well informed, their account/data is protected, and have access to redress. They know when, where, and how many payments will be made and understand how their payment method works, its costs, how to use their payment instrument, and how to access their payment. They can access and know how to access effective grievance redressal mechanisms, their funds are secured, and their data privacy is ensured.
* Beneficiaries can easily access their funds. They are able to cash out their funds at any time at a wide range of conveniently close financial access points. At a reasonable and clearly communicated withdrawal fee or at no cost.
* Beneficiaries are included regardless of gender, race, or other immutable characteristics, through at least one of the payment methods used; gender gaps are considered in the design.
### Infrastructure and Systems-related Principles
* The leveraged infrastructures and systems are shared across G2P programs and payment streams, as well as other use cases, avoiding the implementation of systems to exclusively deliver G2P payments. They are scalable and have cyber security arrangements in place.
* Common ID provides access to multiple programs; the national ID system has high coverage and quality; it allows government agencies and payment service providers to validate recipients’ identities; it enables data sharing across government agencies.
* Payment processing systems unlike social protection management information systems, pension, and payroll systems will not include gender-disaggregated data.
* The payment systems are interoperable to maximize the potential of the available infrastructure to recipients; interoperability arrangements exist for Integrated Financial Management Information System (IFMIS), Treasury Single Account (TSA), banks, and non-banks covering most channels and instruments.
* There is no manual intervention in the disbursement process and the entire payments flow is Straight-Through-Processing, including the reconciliation of payments. Payments are made without delays.
### Payment Services Provider-related Principles
* Payment service providers have a strong and long-term, predictable business case or incentives to deliver payments and provide choice.
* A large variety of bank and non-bank financial institutions operating in a competitive market are used to deliver G2P payments.
* Agents of bank and non-bank financial institutions are accessible to G2P payment recipients.
## Mapping Based on Level of Maturity
The [DIAL use cases](https://exchange.dial.global/use_cases) can be mapped to the Payments Building Block capabilities as follows.
| **Capabilities** | **Payment Infrastructure Scenario** | **DIAL User journey** | **Use Cases** | Destination Channel |
| ---------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| G2P | Scenario 1-4 & 6 |
Payment - Unconditional Social Cash Transfer (direct payment based on family relationship)
Payment - Unconditional Social Cash Transfer (non-electronic/cash payments)
|
a). Beneficiary payment, Incentive payment to mother.
b) Government Salary payment
c) Unconditional cash transfer
| Voucher payment, Mobile Money, direct bank transfer |
| P2G | Scenario 1-4 & 6 | [Postpartum care](https://solutions.dial.community/use_cases/postpartum_and_infant_care) | Payment - registration of birth (Postpartum and Infant Care) | Mobile Money. |
## Payment Infrastructure Deployment Scenarios
### Regional Switch vs Country Switch
Domestic payment switches have specific economic characteristics and may not reach adequate economies of scale. Whilst costs can be passed onto customers, without sufficiently low charges, volumes may remain perennially low. Domestic switches facing this scenario thus remain under-utilized, costly, and under-capitalized. In recent years, the concept of Regional payment switches has gained some traction with new efforts realized or underway across the Southern African Development Community (SADC), West African Monetary and Economic Union (UEMOA), East African Community (EAC), and Economic and Monetary Community of Central Africa (CEMAC).
Regional switches (which may serve as a common resource for multiple countries) often rely on pre-existing arrangements between Central Banks, regional Commercial Banks, or a combination thereof. When multiple currencies are in play, a reference currency or a basket of currencies must be chosen for regional settlement accounts to be viable. Settlement arrangements are vital to the viability of a regional switch. A Regional switch may also integrate financial transactions from countries that already have domestic payment switches (like a switch of switches).
Regional switches may take on any and all use cases or may be restricted to specific use cases, for example, Large Value Transfer or B2B trade. Because regional trade drives economic activity, regional switches often go hand in hand with the portability of business and consumer credentials (i.e. relating to Customer Due Diligence), trade policy, and movement of labor.
### Payment infrastructure scenarios
The Payments Building Block sits between the government account systems (i.e. at the Ministry of Finance or Central Bank) and the public or private switching available in the market. As such the Payments Building Block is assumed in each, but not shown. The primary focus in describing these scenarios is on the relationship between payment schemes, banking institutions, and government institutions. This section describes what is available in-country.
| **Infrastructure Scenarios** | **Suggested Approach** |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
Payment Infrastructure Scenario 1 Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks in different countries in a region.
| Government should leverage the regional payments switch (scheme) to enable all use-cases. This may also imply important developments of a standardized Customer Due Diligence (CDD). Note that while a State owned bank is shown in the diagram below, the option exists for the Government to designate a specific Commercial bank, or to have the funds flow directly from the Ministry of Finance (Treasury) assuming such Treasury payment functionality can be supported by the Regional Switch. |
|
Payment Infrastructure Scenario 2 A payment switch connecting financial service providers such as banks to non-banks including mobile money providers is in place and actively working.
| Government should leverage the existing switch to enable payments use-cases to reach mobile money providers. There may be a State Owned Bank (2-A) or not (2-B). |
|
Payment Infrastructure Scenario 3 A payment switch is in place in the country or is in the process to be deployed but non-banks, including mobile providers are not connected to it.
|
Government should leverage third-party aggregators or bilateral integrations to enable payment use-cases to reach mobile money providers.
|
|
Payment Infrastructure Scenario 4 A payment switch is not place or in the process of being deployed
| Government should leverage third-party aggregators or bilateral connections to enable payment use-cases to reach mobile money providers |
|
Payment Infrastructure Scenario 5 Government makes G2P payments using Central Bank Digital Currency (CBDC) .
| The Central Bank distributes the funds for the CBDC accounts via regulated entities (e.g. Payment Service Providers). |
|
Payment Infrastructure Scenario 6 Citizens have CBDC accounts directly with the Central Bank or other accounts with other payment service providers
| The Central Bank sets up limited accounts for each person, providing a base level of access and functionality. Such accounts may be denominated in country currency (fiat) or CBDCs. This scenario places more responsibility on government structures and is not often considered (outside of Postal Banks and the like). |
Under each of these scenarios, there are different setups possible that relate the key roles played by the Programmatic Ministries (e.g. Ministry of Education or Pension Program), the Ministry of Finance, the Central Bank, and the existing Payment Switch.
The flow of funds and the flow of data are separate but equally important and they have a number of interactions.
#### Payment Infrastructure Scenario 1
Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks.
#### Payment Infrastructure Scenario 2-A
Scenario 2-A and Scenario 2-B cover the concept of separating flows of data from accounting flows.
The Central Bank receives the funds transfer advice from the Treasury and the data from the Ministry of Health and does the steps of breaking it into bulk, based on rules of capacity of source and destination systems. Payments are then routed “on-us” or to the external financial providers “off-us” via a payment switch or similar mechanism.
#### Payment Infrastructure Scenario 2-B
The Central Bank plays a key role as a participant in the Payment scheme and routes the payment details and funds via a shared service of the payment switch. The same logic of break-bulk applies and with all transactions effectively “off-us”.
#### Payment infrastructure scenario 3
Government should leverage third-party aggregators to enable payment use cases to reach mobile money providers
#### Payment Infrastructure Scenario 4
A payment switch is not in place or in the process of being deployed. Government should leverage third-party aggregators or bilateral connections to enable payment use cases to reach mobile money providers. In the bilateral connection scenario, each mobile money provider in the country would connect to the government portal through APIs, enabling a seamless transfer of funds to end users (in the case of G2P payments) or the receiving of funds from end users (in the case of P2G payments) and facilitate reporting, reconciliation and settlement processes.
%20\(1\)%20\(2\).png?alt=media)
#### Payment Infrastructure Scenario 5
The Central Bank mints digital currency and distributes funds via regulated entities (e.g. Payment Service Providers), and in the case of G2P sends funds to destination accounts known to the Ministry of Finance. Account information is unitary and unique for all beneficiaries (e.g. citizens) but the Central Bank does not “hold” account balances on an individual basis.
#### Payment Infrastructure Scenario 6
The Central Bank directly provides Digital Accounts for all people (Citizens) and Treasury routes funds to the relevant accounts (uniquely and unitarily held by people).
* For this payment use case, the most common scenarios currently in place are 1 to 4, scenario 5 and 6 could be envisaged later.
* In Scenario 2B it is assumed that the Payment Switch is run by the Central Bank.
* In Scenario 2A and 3, it is assumed that the Payment Switch is an independent part outside the Central Bank.
# 3 Terminology
Terminology used within this specification.
Several elements of the glossary are based on the terminology defined by the [level one project](https://www.leveloneproject.org/wp-content/uploads/2020/07/L1P_Guide_2019_Final.pdf) and [ITU DFS Glossary](https://www.itu.int/en/ITU-T/focusgroups/dfs/Documents/201701/ITU_FGDFS_DFS-Glossary.pdf)
| Term | Description |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication** | The validation of user credentials for the purpose of system login and basic access. |
| **Authorization** | The permission given by the Payer or entity to make a Payment. |
| **Beneficiary** | Non referring to a payee of a program. |
| **Bulk Payments** | A Payment from a single Payer to multiple Payees, for example, cash transfer programs from a government or non-governmental organization to a set of beneficiaries. |
| **End User** | The customer of a digital financial services provider. The customer may be a consumer, a merchant, a government, or another form of enterprise. |
| **Financial Management Information System** | The budget management system of the government treasury which ensures that government (Ministries, Departments, Agencies) payments are processed within the approved budget and releases. |
| **Financial Services Providers (FSPs)** | A financial services provider refers to one that is licensed by a regulatory authority to provide transaction accounts that hold customer funds and are used to make and receive payments. Digital Financial Services Providers (DFSPs) have relationships with consumers, merchants, and other enterprises, and provide digital financial services to End Users. |
| **Interoperability** | The ability of DFSPs participating in a payment Scheme to exchange Transactions with each other. The term may also be used when two systems interconnect. |
| **Account Mapper or Account Lookup Directory Service** | A dynamic directory matching beneficiaries’ unique identifier and their account numbers enable multiple programs to direct payments to the same account and beneficiaries to switch payment service providers. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases. |
| **Mobile Money (MoMo)** | A mobile money service includes transferring money and making and receiving payments using a mobile phone. The service must be available to the unbanked, e.g. people who do not have access to a formal account at a financial institution. The service must offer a network of physical transactional points which can include agents, outside of bank branches and ATMs, that make the service widely accessible. Mobile banking or payment services (such as Apple Pay and Google Wallet) that offer the mobile phone as just another channel to access a traditional banking product are not included. |
| **Mobile Money Services Provider** | A category of DFSPs that use mobile phones as the access method to provide transaction Accounts to End Users. |
| **Payee** | The recipient of funds in a payment transaction. |
| **Payer** | The person/organization whose account is debited in a payment transaction. |
| **Payment** | Exchange of funds, credentials, and other necessary information to complete an obligation between End Users. A transfer is an example of a payment. |
| **Payment Alias/Payment address** | An alias may include phone numbers, email addresses, or other handles. They may include globally unique URIs and may be chosen by the user. These are increasingly seen in new payment systems. Within systems, the payment alias points to an underlying payment account address, specifically and uniquely located within a payment scheme. A payment address may be different from the underlying account address, depending on the payment scheme rules but is often the same thing. |
| **Quick-Response (QR) Code** | A method of encoding and visualization of data, which are machine-readable. There are multiple QR models. |
| **Routing** | The process by which a route to a payment address is determined. The mechanism of sending payment information across different systems. This is sometimes used interchangeably with addressing. |
| **Transaction** | A reference to the entirety of the exchange, including a Payment but may also include information between the Payer’s DFSP and the Payee’s DFSP. |
| **Treasury Single Account** | A Treasury Single Account (TSA) is a unified structure of government bank accounts that gives a consolidated view of government cash resources. Based on the principle of unity of cash and the unity of treasury, a TSA is a bank account or a set of linked accounts through which the government transacts all its receipts and payments. The principle of unity follows from the fungibility of all cash irrespective of its end use. While it is necessary to distinguish individual cash transactions for control and reporting purposes, this purpose is achieved through the accounting system and not by holding/depositing cash in transaction-specific bank accounts. [This enables the treasury to delink management of cash from control at a transaction level](https://www.imf.org/external/pubs/ft/wp/2010/wp10143.pdf#%3A~%3Atext%3DA%20treasury%20single%20account%20%28TSA%29%20is%20an%20essential%2Cpriority%20in%20the%20public%20financial%20management%20reform%20agenda). |
| **Uniform Resource Identifier (URI)** | A unique sequence of characters that identifies a logical or physical resource used by web technologies. |
| **Voucher** | A token that entitles the holder to a discount or that may be exchanged for goods or services. |
| **Voucher Group** | A voucher group is a characteristic of a voucher that restricts the function or use case that a voucher can be used for. It can also be used as a dimension for reporting on. |
# 4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
The Payment Building Block will handle payments processing and orchestration, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions.
The Building Block will enable government programs to channel payments through a shared payments infrastructure to accounts at multiple providers, allowing citizens to choose their preferred Financial Services Provider and switch providers if their circumstances change or they discover a better service.
### 4.1 Payment Orchestration
Payments orchestration provides for end-to-end workflow across different sub-subsystems, enables asynchronous processing, and covers different payment types, use cases, account systems, and channels.
### 4.2 Voucher Management
The Payment Building Block will provide a voucher management system which is responsible for provisioning, storage, issuance, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
### 4.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
The account lookup directory service or mapper simplifies payment routing and is an important component to avoid storing the payment information of the user in the social registry system and preserve the privacy and confidentiality of sensitive information pertaining to the beneficiary.
### 4.4 Payment Request Initiation
The Payment Building Block must allow systems to initiate a payment request. This request could come from two sources: external or internal. An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll).
### 4.5 Payment Gateway
The Payments Building Block should provide a payment gateway which allows different (digital) Financial Service Providers (FSPs) to interoperate.
### 4.6 Payment Portal
The Payments Building Block should provide a Payment Portal which allows users to manage thje full lifecycle of sending and receiving payments
### 4.7 Event Management
The Payment Building block must support different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
### 4.8 Reconciliation
The Payments Building block must implement functionality that provides both internal and external reconciliation services.
### 4.9 Batch Processing
The Payments Building Block should provide batch processing services
### 4.10 Scheduling Services
The Payments Building Block should provide scheduling services to perform tasks on a regular or repeated basis
### 4.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
### 4.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
### 4.13 Reporting Services
The Building Block should provide reporting services, which may consist of dashboards or analytics reports. These reports should be configurable based on user needs.
### 4.14 Security layer
The Payments Building Block must provide a security layer which protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication.
### 4.15 Bulk payment service
The Payments Building Block must provide bulk payment services. This bulk payment service is invoked in the case of G2P bulk disbursement.
# 5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
## 5.1 External Identification, Registration, and Enrollment Logic (REQUIRED)
The Payments Building Block assumes that all identification, registration, and enrollment logic is done externally and are compliant with regulated payments and banking systems within a jurisdiction.
## 5.2 Registration Requirements (RECOMMENDED)
The Payment System or Scheme in a country may require that participating payor or payee entities, whether health clinics, ministries, or individuals must have been registered with a regulated banking or non-banking entity prior to the use of the Payments Building Block.
## 5.3 Compliance Verification (OPTIONAL)
In the context of Central Bank Digital Currency or Central Bank Accounts for individuals, the payment system block would assume that the regulatory conditions must have been verified for compliance and that payor and payee entities must have been properly registered according to the rules in that scheme.
## 5.4 Statutory and Operational Requirements (REQUIRED)
The Payments Building Block assumes that the statutory and operational requirements around accounts (i.e. know your customer/anti-money laundering/counter-terrorist financing) must have been completed by an outside system, which is capable of communicating that status in appropriate timeframes.
## 5.5 Real-time Response (RECOMMENDED)
The Payments Building Block assumes that the capabilities of the underlying infrastructure must enable transactions to meet a predefined limit to turn-around-time in real-time response.
## 5.6 Validation (REQUIRED)
The Payments Building Block should have the ability to validate against a set of external systems for the status of an account, account address and routing information, confirmation of payment, and various error conditions of accounts and specific payments.
## 5.7 Authorization (RECOMMENDED)
During operation in certain modes, the Payments Block would be validating against authorizations/releases or allotments provided by the treasury systems for the source of funds.
## 5.8 Eligibility Verification (RECOMMENDED)
Normally, verification of eligibility of beneficiaries for the service should be done in another Block.
## 5.9 Budget Availability (REQUIRED)
Budget availability must be checked before voucher creation is requested.
## 5.10 Calculation of Payments (OPTIONAL)
Calculations of payments may depend on several attributes laid down by a specific program.
## 5.11 Payment Systems (REQUIRED)
Payment systems in the market, either provided by a public entity, a quasi-public entity, or a purely commercial player, are required for the functioning of this Building Block.
## 5.12 Settlement (REQUIRED)
Settlement (gross or net) must be handled externally to this Building Block.
## 5.13 Security (REQUIRED)
The Payments Building Block must meet the security requirements described in the Security Building Block.
## 5.14 API Mechanisms (REQUIRED)
The Payments Building Block should meet the mechanisms for consuming and publishing APIs as described in the Information Mediator Building Block.
## 5.15 Architecture (REQUIRED)
The Payments Building Block must meet the requirements described in the Architecture Building Block.
### Infrastructure Requirements
#### 5.16 Mobile Money
Infrastructure Components:
* Account lookup - directory service.
* Payment portal.
* Payment gateway (only in selected scenarios).
* Payment request initiation.
* Notification service.
Mobile money is a destination account to distribute funds to end users (in the case of G2P) or an initiation account to enable users to initiate a payment for government services (P2G) which is facilitated by private commercial entities, typically Mobile Network Operators.
There are three ways that facilitate interoperability between a mobile money provider and a financial service institution (which could be the initiator of a payment - G2P or the receive - P2G): Through a Switch, through a third-party aggregator or through a bilateral integration. We expect one or multiple of these components to be in place to facilitate the use cases discussed in this document but these will remain out of the Payment Building Block.
#### 5.17 Vouchers
Infrastructure Components:
* Voucher Management System.
* Merchant Ecosystem.
* Merchant Registry.
The Merchant Ecosystem and the Merchant Registry are both outside the scope of the Payments Building Block. The development of the Merchant Ecosystem will be driven by the relevant government institution. The Merchant Registry will be managed by another Building Block.
## Payments Building Block Technical Requirements
| **Requirement** | **Type (Must/Should/May)** |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| Secure API exposure: All APIs exposed via secure socket connections (HTTPS). | MUST |
| Client application authorization tokens: Client applications must send authorization tokens in the authorization header of the request to authenticate users and the API Management Gateway will verify whether the token is valid. | MUST |
| Transaction receipting: For each disbursement made by the system, a receipt should be issued to the recipient of the funds containing information about the transaction id, transaction date and time, reason for the payment, details of the payor, and the system should store all receipts issued for easy reference and reconciliation. | MUST |
| Transaction status querying capability | MUST |
| Display details of the transaction to the payer | MUST |
| Transaction pre approval: Prior to processing bulk payment and batch payment transactions, the transaction must be authorized and approved in the system. | MUST |
| Pre-processing validation of data (well formed data and completeness checks) prior to disbursement. | MUST |
| Ability to schedule bulk payments | MUST |
| Support for batch payments | MUST |
| Ability to lookup payment addresses | SHOULD |
| Error handling and reconciliation | MUST |
| Transaction status logging | MUST |
| Triggering of payments | MUST |
| Voucher Management | |
| Batch generation of vouchers | MUST |
| Voucher uniqueness and randomness: Voucher pin must be unique and unpredictable. | MUST |
| Secure voucher data storage | MUST |
| High availability of storage | MUST |
| Expose APIs that can be invoked by voucher serial number for purposes of querying a voucher, suspending, or unsuspending a voucher. | MUST |
| Support an API that can be invoked to redeem a voucher using the voucher number. | MUST |
| Support an API that can invoke payment gateway | MUST |
| Mobile Payments | |
| Real time debiting/crediting of mobile money accounts | SHOULD |
| Regular balance reconciliation with disbursement Agency | MUST |
| Documented process for partners to dispute transaction records | MUST |
| Target account identifier or lookup of payment address | MUST |
| Ability to retrieve details of completed transactions in the batch | MUST |
| Bulk Payments | |
| Ability to securely receive bulk payment requests as a single HTTPS request containing data for multiple transactions. The transaction data (with payment instructions data) is passed format and will be compatible with ISO 20022. | MUST |
| The number of transactions that can be included in a single batch is limited by the size of the file upload and the processing time. If the number of transactions in the file exceeds the file size and could impact the performance of the system, the batch should be split into multiple batch requests. | MUST |
| Batch files should be verified for any errors and validated as per business rules and regulations before it is accepted as a valid bulk payment file. | MUST |
| Batch files containing duplicate payments will not be processed and an error will be generated. | MUST |
| The bulk payment process has to be explicitly triggered by an authorized user. All requests to the Bulk Payment Application API must be authorized and digitally signed by the person initiating the bulk payment request. | MUST |
| The batch file for bulk payments should contain the beneficiary ID token, and the amount to be paid. The payment information is not included in the batch file for security and privacy but is resolved by the verification and validation component of the bulk payment service by invoking the Account Lookup Directory Service (ALDS/ALS). | MUST |
| The Bulk Payment Application API shall inspect the batch disbursement file and split transactions into bank payments and non-bank payments (e.g. Mobile money) in separate payment files before initiating the call to the Payment Gateway. | MUST |
| The status of the bulk payment transaction can be obtained from the event log. The payment status code indicates the status of a single payment transaction and will be according to ISO 20022 Payment status codes table. | MUST |
# 6 Functional Requirements
This section lists the technical capabilities of this Building Block.
## 6.1 Payment Orchestration
Payment orchestration is an overarching concern which relates different sub-components or microservices whereby it:
* Explicitly defines and models workflows that span multiple microservices (REQUIRED)
* Provides detailed visibility into how a workflow is performing and identifying where there are issues (REQUIRED)
* Ensure that within a defined workflow, all workflow instances are completed according to plan, even when there are issues along the way (REQUIRED)
Payments orchestration is used to configure the Payments Building Block functionalities to be exercised during a specific workflow and provides functionality such as:
* Sending receipts, notifications, and acknowledgement of receipts in a secure manner to payers and other external applications to receive confirmation of payment made and safekeeping of a record of the receipt that was sent (REQUIRED)
* Provides for auditability of the Payments Building Block to have its controls evaluated for effectiveness, efficiency, and security, including tracing transactions, identifying users who access the system, clearly defined system controls, and compliance with local regulations and global best practices (REQUIRED)
* Schedule and aggregate payments to individuals, allowing programs to stagger payments or combine them with other payments to the same groups of individuals (REQUIRED)
* Enable payment confirmation through secure receipts, notifications, and acknowledgement of receipts to payers and other external applications (REQUIRED)
* Store event logs and audit trails for all transactions processed and their outcomes for monitoring and audit purposes (REQUIRED)
* Validate data structures and content to ensure that it is not missing key pieces of information, including verifying the destination account and triggering a different process if the account is not in good status (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed with throttling to reduce the flow of payment initiated (REQUIRED)
* Coordinate or orchestrate the validation, verification, batching, and scheduling using a set of rules, including options for kicking back to the operator for review or resubmission in certain error cases (REQUIRED)
* Generate reconciliation of accounts based on the successful sending of funds into accounts and reports to show the additional status of systems and payment types and timings (REQUIRED)
* Manage fees in a centralized way and support the use of digital channels to/from end-users, regulated account systems with payment signalling, and notifications by the Financial Services Provider enablers (REQUIRED)
* Scale on transaction performance, transaction latency, reliability, resilience, and graceful service degradation (REQUIRED)
* Support digital tools for query management, including beneficiary queries and complaints about payment services (REQUIRED)
* Route bulk payments through the account holding the funds, either at the government Treasury or a commercial bank (REQUIRED)
* Release funds by the Ministry or payroll master after appropriate approvals (REQUIRED)
* Handle processing and orchestration of bulk payments, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions (REQUIRED)
* Validate data structures and content to ensure that key information is not missing (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed (REQUIRED)
* Generate reconciliation of accounts based on successful sending of funds into accounts (REQUIRED)
* Provision, issue, activate, and redeem vouchers to support G2P beneficiary payments (REQUIRED)
* Ensure that adequate funds have been allocated to the voucher during provisioning (REQUIRED)
* Allow issuance of vouchers but make them unusable until they are in the hands of the beneficiary (REQUIRED)
* Activate vouchers to make them usable for predefined use cases and for a certain period of time (REQUIRED)
* Handle redemption of vouchers so that beneficiaries receive appropriate benefits from third parties (REQUIRED)
* Generate reports that show the vouchers in their different states as well as the aggregate quantity "stock", which triggers requests for "re-stocking" of vouchers (REQUIRED)
* Authenticate beneficiaries at the point of redemption by checking the Digital Registries Building Block to authenticate the user (REQUIRED)
* Cater for the distribution of social service transfers electronically and cash safely to end users (in the case where the user does not want to use electronic payments it is recommended that vouchers are used) (REQUIRED)
* Creates eVouchers to disburse financial subsidies in a controlled and safe manner (REQUIRED)
* Responds to payers to provide information about the status of the payments (e.g. confirmation of payment, insufficient balance or a mismatch in credentials, transfer failure, etc.), based on the status in the backend applications (REQUIRED)
* Posts status of transactions with traceability information into transaction logs (REQUIRED)
* Tracks due payment and sent payment notifications through alerting mechanisms, along with associated information (REQUIRED)
* Receives triggers for payment collection, posts the amount with relevant disclaimers to the payer, and obtains payer approval (REQUIRED)
* Securely posts the approval, user ID, and associated payment information to the appropriate backend (e.g. mobile, debit/credit card, internet banking entities) of relevant financial applications from banks, employers, and insurance; awaits transfer confirmation from those applications (REQUIRED)
* Searches and provides a logged information-based query of other applications (REQUIRED)
* Able to handle operations in remote and inaccessible locations (REQUIRED)
## 6.2 Voucher Management
The voucher management system is responsible for prectivation, storage, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
### **6.2.1 Voucher Provisioning**
This process traditionally involves the generation of group vouchers against some authorized value (budget release or allotment).
* Each voucher should have a unique secret voucher number, a unique identification number (voucher serial number) indicating its position in an inventory of pre-activated ~~issued~~ vouchers, and is linked to a fixed amount of value in a particular currency. Vouchers will also be associated with a voucher group during ~~provisioning~~ pre-activation. Voucher serial numbers will be unique across currencies should there be vouchers of multiple currencies.
* The vouchers should be created with an expiry date and MUST be stored securely. All vouchers will be expected to have the same duration of expiry and this expiry period will be from the moment the voucher is activated.
* Alternative design options include dynamically pre-activating a voucher at transaction time and creating variable amounts, but this increases complexity and requires tighter operational controls.
### **6.2.2 Voucher Issuance**
This process involves the Registration Building Block (or any other Building Block for that matter) requesting a voucher number from the voucher management system through an API.
* Once confirmation is received that the voucher has been released it flags the voucher as activated. Design decisions include making this step optional. Having an additional step increases security by ensuring that the voucher is not used until it is in the hands of the beneficiary (RECOMMENDED)
* Once a voucher has been issued by the calling Building Block (Registration Building Block) it will be presented to the beneficiary in a form that is determined by the calling Building Block (refer to voucher workflow). The format of the final voucher presentation will be determined by the function of the calling Building Block. At a minimum, this presentation should have the voucher number as well as the voucher serial number. it could also have the details of the beneficiary, which when placed on the voucher presentation, will help the merchant authenticate the beneficiary at the point of redemption (REQUIRED)
### **6.2.3 Voucher Redemption**
* In the redemption process, the merchant will authenticate the beneficiary and use a predefined technology (Unstructured Supplementary Service Data, Mobile App, Web Browser) to extract the voucher number and call a redemption API through the relevant calling Building Block. The calling Building Block may also validate the beneficiary details if so required. The Building Block will also be able to validate the merchant and determine the voucher group to which the merchant belongs. Lastly, the calling Building Block will invoke the Payment Building Block Redeem API, through the Payments Building Block API Management gateway, to validate the voucher and if valid to redeem it (REQUIRED)
* Once the voucher is validated, the Voucher Management System should invoke an API on the Payment Gateway to effect the payment in the merchant or agent wallet or bank account (depending on what was set up at merchant/agent registration). The payment gateway/switch will debit a pre-funded account/wallet and credit the merchant/agent account/wallet. The successful execution will result in the voucher being flagged as consumed/used (REQUIRED)
### 6.2.4 Voucher Management System (VMS) API interface
The details of the VMS APIs are described in the Service API section.
The VMS functionality can be accessed by four external APIs:
* **Voucher preactivate**: An API call to pre-activate the voucher and get a voucher number, a voucher serial number, and an expiry date.
* **Voucher activate**: An API call to activate the vouchers by serial number.
* **Voucher validity**: An API call to check the validity of a voucher by serial number.
* **Voucher redeem**: An API to redeem the voucher by voucher number.
The API interface should provide a minimum of five internal API calls.
* Voucher preactivation: An API to pre-activate the voucher and get a voucher number, a voucher serial number, and an expiry date.
* Voucher activation: A call to activate the voucher, by serial number.
* Voucher validity:
* A call to check the validity of the voucher by serial number.
* A call to check the validity of the voucher by voucher number and group.
* Voucher consumption: A call to consume the voucher by voucher number.
### 6.2.5 Voucher Storage
The voucher management server shall have a storage subsystem to store the vouchers.
* Vouchers must be stored in secure but high-performance data storage (read access will marginally exceed write access) (REQUIRED)
* The storage of the voucher number will require encryption of data at rest and in motion (unless the channel is encrypted) (REQUIRED)
* Logs generated should NEVER contain the voucher numbers (REQUIRED)
* All access to the voucher database must be logged (REQUIRED)
* Segregation of duty must be done with respect to privileged access to the database and key management of the encryption of the voucher (the level of key management may need to be determined) (REQUIRED)
## 6.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
The account lookup directory service provides a directory that maps the beneficiary's unique identifier (which matches the record in the social registry system) to the transaction account where the beneficiary wishes to receive their G2P payment, allowing the government to address payments to a specific individual. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases. The information will be kept in a tokenised form in the account lookup directory service.
In the case where there is a national payment switch, the account lookup directory service will be maintained by the FSPs, In the scenario, where there is no payment switch, the government would need to manage the account lookup directory service and provide a mechanism for linking it to the FSPs.
## 6.4 Payment Request Initiation
* A request can come from either internal or external sources (REQUIRED)
* An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll). Either source must be appropriately authenticated and authorized to initiate the request.
* The initiation can be synchronous (typically for a single payment) or asynchronous (typically for batch payments) (REQUIRED)
* The request must contain at a minimum: the payer identifier, the payee identifier, the amount, the currency, the policy, and the initiating source’s unique transaction ID. In the case of the internal payment request, it should also contain an ID provided by the payment orchestration module (REQUIRED)
* Certain processes in the transaction flow might require proof of intent from the user, for example, entering the PIN/Password or pressing an ’accept‘ key to initiate the payment process. Such events and their outcomes should be recorded for audit trail purposes. However, the PINs and passwords should not be stored in logs or if they have to, PINs and passwords should be hashed out (RECOMMENDED)
## 6.5 Payment Gateway
A payment gateway allows different (digital) Financial Service Providers (FSPs) to:
* Interconnect and exchange information (REQUIRED)
* Initiate and receive transactions (REQUIRED)
* Accept or reject transactions and debit or credit end-user accounts (REQUIRED)
## 6.6 Payment Portal (RECOMMENDED)
The payment portal will:
* Enable government payers (departments/ministries/public sector bodies) to make G2P payments through one or multiple FSP/payment service providers (REQUIRED)
* Focus on managing, sending, and reconciling payments (REQUIRED)
* Connect government agencies to sending and recipient institutions (REQUIRED)
* Coordinates sending/receiving of payment requests, and approvals (REQUIRED)
* Provide reports across G2P programs, FSPs, and beneficiaries (RECOMMENDED)
* Track payment status and payment history (REQUIRED)
* Register FSPs who are entitled to process payments for G2P payments (REQUIRED)
* Provide restricted access to authorized FSPs to connect to the portal, to process the payments for beneficiaries who are their customers (REQUIRED)
* Automate reconciliation (RECOMMENDED)
* Provide data analytics on payments processed and their status, whether successful or not (REQUIRED)
## 6.7 Event Management
This functionality supports different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
All notification events shall have a timestamp associated with them and be kept as part of the audit log.
## 6.8 Reconciliation (RECOMMENDED)
This should happen at two levels: internally and externally.
* The internal reconciliation will occur between the different sub-blocks within the Payments Building Blocks. In order to achieve internal reconciliation the internal payment request initiator should issue a unique ID that will be referenced by subsequent Payments Building Blocks in all future calls related to the particular payment. This will allow end-to-end tracing of the transaction within the Payments Building Blocks (REQUIRED)
* The external reconciliation is more complex as it involves a calling Building Block which is outside the Payments Building Blocks (such as the Registration Building Block) and a third party (e.g. DFS). Ideally, there needs to be a sequence of IDs that can identify a transaction from start to finish (REQUIRED)
* Cross-cutting Prerequisites for reconciliation:
* The nodes that are under the control of the GovStack should be time synched (REQUIRED)
* IDs should be unique, if possible contain the timestamp, and should not roll over across short ranges (REQUIRED)
* Transactions are expected to be irrevocable. Transaction reversals are subject to local regulations. In some countries, a transaction is revoked/clawed back if the beneficiary has not withdrawn the payment within a certain time period. Good practice, from a financial inclusion perspective, is to not claw back. The beneficiary could use this money as savings when needed. The system should allow both configurations (REQUIRED)
## 6.9 Batch Processing (RECOMMENDED)
* Prepares the batch breakdown on the basis of rulesets governing: which Financial Services Providers shall receive, which payments, and other considerations (REQUIRED)
* Combines payments with other payments to the same beneficiary (REQUIRED)
* Detects batch failure rates (REQUIRED)
Batch files go through a final check to be clean of defects and inconsistencies, to check with external systems as necessary:
* At high volumes, batches are queued for processing (REQUIRED)
* Low-level validation of data types and data completeness (REQUIRED)
* Verification of lookup of accounts to ensure that the account information matches the destination system expectation (REQUIRED)
* Check for inconsistencies (REQUIRED)
* Auto-correct items as possible - consistency logic can be applied to fill in missing formatting if required by recipient banks and telecoms (REQUIRED)
* Errors are kicked back to program level or to an internal data review process (REQUIRED)
## 6.10 Scheduling Services
* In relation to batch logic, payments are scheduled against the availability of systems, throughput limitations, and rules set by programs (REQUIRED)
* Regular and repeat payments are scheduled (REQUIRED)
* Batches may be given prioritization in the queue (REQUIRED)
* Essential control logic may be included here, specific to the individual batch sending and resending (REQUIRED)
* Availability of funds in different budget accounts may be incorporated into this process (REQUIRED)
* Additional workflow checks as required, including the resending of failed transactions (REQUIRED)
## 6.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
* Application or event logs will capture events that each component performs and should contain at least the following information (REQUIRED):
* application/user ID
* event date and time
* terminal identity (name and/or IP address)
* event-related information (message or code)
* event success or failure
* The components should also generate transaction logs that capture at least the following information (REQUIRED):
* transaction date and time
* transaction source
* transaction destination
* supplementary data
* transaction status (success, failed, in progress)
* The event logs and the transaction logs should NOT capture any sensitive data such as voucher numbers, passwords, etc. (REQUIRED)
* There should be an individual transaction record for every payment transaction. For example, if a batch payment process is executed there should be a transaction record for each individual transaction and a separate event log for the entire batch (RECOMMENDED)
### 6.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
* Must be automatically captured by the computer system whenever a payment request is created, modified, or deleted (REQUIRED)
* Must be stored in a secure manner and must not be editable by any user, including privileged users. A common approach is to copy/redirect logging to a separate logging server (REQUIRED)
* Each audit trail entry must be time-stamped according to a controlled clock which cannot be altered. The time should either be based on central server time or a local time, so long as it is clear in which time zone the entry was performed (REQUIRED)
* Each audit trail entry must be traceable, i.e. attributable to the individual responsible for the direct data input. Updates made to data records must not obscure previous values and where required by regulation the reason for changing the data must also be recorded (REQUIRED)
* The audit trail must be retained as long as the electronic record is legally required to be stored (REQUIRED)
* The audit trail must be available for internal review/audit (REQUIRED)
* The auditing system must be self-sufficient, i.e. for auditing/regulatory purposes the information stored by a BC must be enough (REQUIRED)
* Audit entries cannot be changed, i.e. the audit BC persisted store should be immutable, and should only support append and not changes or deletes (REQUIRED)
* Audit entries should have a pair of fields to store encrypted data and the encryption key id - these are provided by the submitting BCs (REQUIRED)
* Querying capabilities (REQUIRED):
* Auditor wants to see all activity in the last X days.
* Auditor wants to see all activity of action type Y, or from a certain BC.
* Auditor should be able to request the decryption of encrypted data to an operator.
* Access to the audit store must be securable, so whatever tech is chosen must implement access control mechanisms (ideally that can connect to our Identity and Access Management provider/connector) (REQUIRED)
### 6.13 Reporting Services
* The data store will be write-only from the core service and should be read-only by external components (RECOMMENDED)
* The data model on the reporting data store can be different from the internal operational data models that the switch uses (RECOMMENDED)
* The component provided by the switch will be translating internal events and internal data models to the external data store models. This component can be replaced (RECOMMENDED)
### 6.14 Security layer
Protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication. The digital signatures are based on public key cryptography using X.509 digital certificates.
At the transport layer:
* All communication between building blocks must use secure protocols to protect the confidentiality and integrity of the data in transit (REQUIRED)
* Strong authentication for parties involved in the transactions should be supported (REQUIRED)
* Confidentiality of personal information related to the transaction – Information on account data, transaction data, payment credentials, and users’/payee’ personal profiles must never be disclosed to any unauthorized party (REQUIRED)
* Non-repudiation of transactions by parties involved (REQUIRED)
* Acknowledgement receipt: this will result in creating a trusted communication path for all transactions between each party, by the end users, telecommunication companies, merchants, or banks (REQUIRED)
* The messages concerning the payment transaction shall be authenticated (REQUIRED)
### Data Protection
Use of a hardware security module (HSM) or equivalent to provide cryptographic keys for critical functions such as encryption, decryption, and authentication for the use of applications, identities, and databases.
### 6.15 Bulk payment service (RECOMMENDED)
The bulk payment service is invoked in the case of G2P bulk disbursement and should provide the following functionality:
#### 6.15.1 G2P Bulk disbursement (REQUIRED)
The following are the prerequisites required before bulk payments can be initiated:
A) Funding requirements
* The funding requirements must operate within the budget/ceiling.
* The number of funding accounts and the life cycle processes will vary depending on the payment infrastructure scenarios.
B) Bulk payments file
* For the salary payments use case, this would be generated by the payroll system.
* For the unconditional social cash transfer use case, this would be generated by a process that would be triggered as per a pre-agreed frequency and the information about the payments to be made would be extracted from the registry (a database containing the information about beneficiaries for a particular government social cash transfer programme). The process of generating this payments file is outside the Payments Building Block.
There are three options for the disbursement:
* Manual process for Government/Department to send the retail payment details to each Financial Services Provider (FSP) (i.e. either by email or other means). This would be the case where there is a lack of interoperability among FSPs.
* Upload the batch disbursement file in the payment web portal for each FSP to retrieve in the case of a centralised Account Lookup Directory Service.
* Automate the disbursement process through the decentralised Account Lookup Directory Service and the payment gateway.
**Option 1**: Retail payment information is sent securely to each Payment Service Provider for disbursement
**Option 2**: Retail payments are accessed via a payment web portal by the Payment Service Provider. The advice/electronic fund transfer request, or paper-based check is issued from the Financial Management Information System to the Trusted Single Account (TSA) -holding Bank.\
Based on this advice, the Bank disburses funds from the TSA into the digital payments system of the FSP which transfers the corresponding funds to the recipient’s account. For the retail payment scrolls, where each agency is responsible for running the payment system - payroll, social welfare payments, etc. - the payment details are not stored in those systems. Instead, the beneficiary’s payment token is retrieved from the Centralised Account Lookup Directory Service and kept in the government payment portal. The payment lists are only shared with the program account holder institution/FSP, Payment Service Provider (PSP), via the government payment portal. The FSP/PSP can log in on the government web portal to access the directory for payments that the FSP needs to effect for each G2P Program.
**Option 3**: Similar to option 2 but the disbursement process to the beneficiary is routed automatically through the payment gateway using the payment token retrieved from the decentralised account lookup directory service.
Bulk payments require the functionality of a Payments Gateway and the functionality therein. It also assumes a separate mechanism by which the recipient account address is determined. In the figure below the “account lookup directory service” functionality maps the concept of identity to the payment alias and from there to the Financial Services Provider routing address. (i.e. wallet address or account address)
**6.15.2 Interaction with Other Building Blocks (REQUIRED)**
The diagram below shows the interaction with the registries Building Blocks.
At a high level, the payment components used for bulk payments are shown in the figure below.
Figure: Key digital requirements of Bulk Payments expressed as a high-level block diagram. Dotted line for required components.
###
## Payments Building Block Components
The following components are needed to achieve the technical functionalities of the Payments Building Block.
Many of the components outlined above are used to deliver the Functional Requirements for the Payments Building Block. Components which are not directly related to the delivery of these functions are described here:
### API Management Gateway
The Payment Building Block provides an API Gateway to handle all the API messaging calls and API access control verification from other Building Blocks to the Payments Building Block and vice versa as well as within the Payments Building Block. All requests from other Building Blocks first go through the API gateway. The gateway then routes requests to the appropriate application/service.
The API Management gateway will:
* Use Identity and access management for authentication.
* Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats.
* Require authentication for all API users.
* Manage access quotas and throttling.
* Log all API calls.
* Allow API providers to limit the rate of consumption for all API users.
* Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.
# 7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
## 7.1 Resource Model
## 7.2 Data Structures
### 7.2.1 Voucher provisioning
**Fields:**
Name
Type
description
notes
required
standard
Name
Type
Description
Notes
voucher_amount
Integer
Denomination of the voucher required
Input
Y
voucher_currency
String
The currency of the voucher (ISO 4217 Standard)
Input
Y
voucher_group
String
The group of the voucher
Input
Y
voucher_number
Integer: 64-bit
The voucher number (PIN). This is the secret number of the voucher.
Output
Y
voucher_serial_number
Integer: 64-bit
The voucher serial number
Output
Y
expiry_date
String: date-time
The expiry date of the voucher
Output
Y
status
String
The status of the process: SUCCESSFUL or FAILED
Output
Y
Merchant_group
String
The group of the merchant is captured in the registry
Input
Y
Gov_Stack_BB
String
Calling GOV Stack Building Block
Input
Y
merchant_bank_details
String
Merchant/agent payment details
Input
Y
merchant_name
String
Merchant name
Input
Y
Override
Boolean
Override
Input
Y
Result_Status
String
Result of the process
Output
Y
### 7.2.2 Register Beneficiary
**Fields:**
| **Name** | **Type** | **Description** | **Notes** |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| RequestID | String | Globally unique ID | |
| SourceBBID | String | To identify the origination of the request. | |
| Beneficiaries | Object | JSON Array | |
| PayeeFunctionalID | String | The functional Id of the beneficiary. | |
| PaymentModality | String |
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
| |
| FinancialAddress | String | Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc. | |
### 7.2.3 Update Beneficiary details
**Fields:**
Name
Type
Description
Required
Name
Type
Description
Notes
RequestID
String
Globally unique ID
Y
SourceBBID
String
To identify the origination of the request.
Y
Beneficiaries
Object
JSON Array
PayeeFunctionalID
String
The functional Id of the beneficiary.
Y
PaymentModality
String
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
FinancialAddress
String
Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
### 7.2.4 Prepayment validation
**Fields:**
Name
Type
Description
Required
Name
Type
Description
Notes
RequestID
String
Globally unique ID
Y
SourceBBID
String
To identify the origination of the request.
Y
BatchID
String
BatchID for batch that is submitted by the Source Building Block.
Y
CreditInstructions
Object
JSON Array
InstructionID
String
Individual ID for each instruction in the Credit Batch
Y
PayeeFunctionalID
String
The functional Id of the beneficiary.
Y
Amount
Float
Amount to be Credited
Y
Currency
String
Transaction Currency Code
Y
Narration
String
Description of Payment
### 7.2.5 Bulk payment
**Fields:**
Name
Type
Description
Notes
Required
Name
Type
Description
Notes
RequestID
String
Globally unique ID
Y
SourceBBID
String
To identify the origination of the request.
Y
BatchID
String
BatchID for batch that is submitted by the Source Building Block.
Y
CreditInstructions
Object
JSON Array
InstructionID
String
Individual ID for each instruction in the Credit Batch.
Y
PayeeFunctionalID
String
The functional Id of the beneficiary.
Y
Amount
Float
Amount to be Credited.
Y
Currency
String
Transaction Currency Code.
Y
Narration
String
Description of Payment.
### 7.2.6 Minimum Required Data
**Fields:**
Name
Type
Description
Notes
Name
Type
Description
Notes
Required
Vouchers ID
Int64
Unique voucher identifier
yes
Voucher_Number
Varchar
Secret voucher number
Yes
Voucher_serial_no
Varchar
Unique voucher identifier for external parties
Yes
Currency
Varchar
Voucher currency
Yes
Create_date
Date
Date when the voucher was created
Yes
Activate_date
Date
Date when the voucher was activated
Yes
Expiry_date
Date
Date when voucher will expire
Yes
Voucher_group
Varchar
Voucher group
Yes
Status
Varchar
Status of the voucher (e.g. ACTIVATED, SUSPENDED, CONSUMED, etc.)
Unique reference for the transaction. This is returned in the response by Financial Service Provider.
→ NA ← M
requestingOrganisationTransactionReference
string
A reference provided by the requesting organisation that is to be associated with the transaction.
→ O ← O
originalTransactionReference
string
For reversals and refunds, this field indicates the transaction which is the subject of the reversal.
→ O ← O
creditParty
array
A series of key/value pairs that enable the credit party to be identified. Keys include Mobile Station Integrated Services Digital Network (MSISDN) and Wallet Identifier.
→ C ← C
debitParty
array
A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier.
→ C ← C
type
string
The harmonised Transaction Type (not required if passed in the URL)
→ M ← M
subType
string
A non-harmonised sub-classification of the type of transaction. Values are not fixed, and usage will vary according to Provider.
→ O ← O
transactionStatus
string
Indicates the status of the transaction as stored by the API provider.
→ NA ← M
amount
string
The transaction amount.
→ M ← M
currency
string
Currency of the transaction amount.
→ M ← M
descriptionText
string
Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on a notification SMS and on an account statement.
→ O ← O
fees
array
Allows the passing and/or returning of all fees pertaining to the transaction.
→ O ← O
geoCode
string
Indicates the geographic location from where the transaction was initiated.
→ O ← O
oneTimeCode
string
A one-time code that can be supplied in the request or can be generated in the response depending upon the use case. An authorisation code can be supplied in this field for requests that have been pre-authorised.
→ O ← O
requestingOrganisation
object
The originating organisation of the request.
→ O ← O
servicingIdentity
string
The field is used to identify the servicing identity for transactions, e.g. till, Point of Service (POS) ID, assistant ID.
→ O ← O
transactionReceipt
string
Transaction receipt number as notified to the parties. This may differ from the Transaction Reference.
→ NA ← O
creationDate
date-time
Date and time when the transaction was created by the API Provider.
→ NA ← O
modificationDate
date-time
Date and time when the transaction was modified by the API Provider.
→ NA ← O
requestDate
date-time
The creation date and time of the transaction as supplied by the client.
→ O ← O
customData
string
A collection of key/value pairs that can be used for provider specific fields.
→ O ← O
metadata
array
A collection of key/value pairs. These can be used to populate additional transaction fields.
→ O ← O
# 8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
The [GovStack non-functional requirements document](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.
The tests for the Payments Building Block can be found in [this GitHub repository](https://github.com/GovStackWorkingGroup/bb-payments/tree/main/test/openAPI).
## 8.1 Payment Orchestration
The payments BB APIs are listed below
| 1 |
| Returns success code along with payments history or else returns failure status with error code. |
| 4 | register\_beneficiary(payee\_functionalID, Modality, fsp\_id, account\_info) | Returns success code after creating entry along with mapperID. |
| 5 | update\_beneficiary(payee\_functionalID, Modality, fsp\_id, account\_info) | Returns success code after updating entry along with new mapperID. |
| 6 | get\_paymentaccount\_info(payee\_functionalID) | Returns success code along with mapperID in tokenised format. |
| 7 | VoucherPreactivation (InstructionID, amount, Group\_Code, currency, Expiry\_DTTM, FunctionalID, Description) | Returns success code with voucher number, voucher serial number and expiry date. |
| 8 | VoucherActivation(voucher\_number) | Returns success code. After this point the voucher may be redeemed. |
| 9 | VoucherRedemption(voucher\_number, voucher\_serial\_number,\[OC1] ) | Returns success code and payment reference from the payment gateway. After this point the voucher CANNOT be used again as the system will fail it. |
| 10 | VoucherStatusCheck(serial\_number) | Returns success code with the status of the voucher which may be either of Pre-Activated, Activated, Suspended, Blocked or Not Existing |
| 11 | VoucherCancellation(voucher\_serial\_number) | Returns a success code if the voucher has been successfully cancelled. |
## 8.1 Person-to-Government APIs (P2G)
The implementation will be such that a “Request to Pay” API is exposed and the Government Ministry (entity) is treated as a type of Biller.
### 8.1.1 Government Initiated P2G payment
This API is designed for the government entity to initiate a request to the Financial Service Provider (FSP) and will be credited when the payer approves the request.
### 8.1.2 P2G Bill Payments
The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money.
## 8.2 Government to Person 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.
### Collaboration with G2PConnect on G2P Payments
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. This approach gives countries agency, allowing them to constantly improve their solutions according to evolving needs.
### 8.2.1 Beneficiary Onboarding API
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.
#### Request Parameters
| Field | Type | Required | Description |
| ----------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| RequestID | String (12) | Yes | Globally unique ID |
| SourceBBID | String (12) | Yes | To identify the origination of the request. |
| Beneficiaries | Object | Yes | JSON Array |
| PayeeFunctionalID | String (20) | Yes | The functional ID of the beneficiary. |
| PaymentModality | String (2) | No | 00 for Bank Account, 01 for Mobile Money, 02 for Voucher, 03 for Digital Wallet, 04 for Proxy |
| FinancialAddress | String (30) | No | Destination Account Number, ideally an IBAN if available, otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc. |
{% openapi src="/files/gAX8Hr12r3KPCTDaoFVq" path="/register-beneficiary" method="post" %}
[Registerbeneficiary.yaml](https://421627467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuJEXiAICNFsZ8S17X5KP%2Fuploads%2Fgit-blob-c4a6bce5e4700b1c3706bb6169716859c9974a53%2FRegisterbeneficiary.yaml?alt=media)
{% endopenapi %}
#### Response Parameters
| Field | Type | Required | Description |
| ------------------- | ------------ | -------- | -------------------------- |
| ResponseCode | String (2) | Yes | 00 – Success, 01 – Failure |
| ResponseDescription | String (200) | Yes | |
| RequestID | String (12) | Yes | Echoed from Request |
### 8.2.2 Update Beneficiary Details API
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.
#### Request Parameters
| Field | Type | Required | Description |
| ----------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| RequestID | String (12) | Yes | Globally unique ID |
| SourceBBID | String (12) | Yes | To identify the origination of the request. |
| Beneficiaries | Object | Yes | JSON Array |
| PayeeFunctionalID | String (20) | Yes | The functional ID of the beneficiary. |
| PaymentModality | String (2) | No | 00 for Bank Account, 01 for Mobile Money, 02 for Voucher, 03 for Digital Wallet, 04 for Proxy |
| FinancialAddress | String (30) | No | Destination Account Number, ideally an IBAN if available, otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc. |
{% openapi src="" path="/update-beneficiary-details" method="post" %}
{% endopenapi %}
#### Response Parameters
| Field | Type | Required | Description |
| ------------------- | ------------ | -------- | -------------------------- |
| ResponseCode | String (2) | Yes | 00 – Success, 01 – Failure |
| ResponseDescription | String (200) | Yes | |
| RequestID | String (12) | Yes | Echoed from Request |
### 8.2.2 Pre Payment Validation API
This API is to be exposed by the Payments BB; the prepayment validation API, called by Source BB, retrieves eligible Functional IDs from the account mapper for credit transfers.
#### Request Parameters
| Field | Type | Required | Description |
| ------------------ | ----------- | -------- | ------------------------------------------------------ |
| RequestID | String (12) | Yes | Globally unique ID |
| SourceBBID | String (12) | Yes | To identify the origination of the request. |
| BatchID | String (12) | Yes | BatchID for batch submitted by the Source BB. |
| CreditInstructions | Object | Yes | JSON Array |
| InstructionID | String (16) | Yes | Individual ID for each instruction in the Credit Batch |
| PayeeFunctionalID | String (20) | Yes | The functional ID of the beneficiary. |
| Amount | Float | Yes | Amount to be Credited |
| Currency | String (3) | Yes | Transaction Currency Code |
| Narration | String (50) | No | Description of Payment |
{% openapi src="/files/s8k2M8aVNYLF0HipHTSf" path="/prepayment-validation" method="post" %}
[Prepaymentvalidation.yaml](https://421627467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuJEXiAICNFsZ8S17X5KP%2Fuploads%2Fgit-blob-44c623e9a7f421508324c95e0a3e751251d9ffb0%2FPrepaymentvalidation.yaml?alt=media)
{% endopenapi %}
| Field | Type | Required | Description |
| ------------------- | ------------ | -------- | -------------------------- |
| ResponseCode | String (2) | Yes | 00 – Success, 01 – Failure |
| ResponseDescription | String (200) | Yes | |
| RequestID | String (12) | Yes | Echoed from Request |
### 8.2.2 Bulk disbursement APIs
This API is to be exposed by the Payments BB; it will be called by the Source BB to handover a batch of credit instructions to be processed.
#### Request Parameters
| Field | Type | Required | Description |
| ------------------ | ----------- | -------- | ------------------------------------------------------ |
| RequestID | String (12) | Yes | Globally unique ID |
| SourceBBID | String (12) | Yes | To identify the origination of the request. |
| BatchID | String (12) | Yes | BatchID for batch submitted by the Source BB. |
| CreditInstructions | Object | Yes | JSON Array |
| InstructionID | String (16) | Yes | Individual ID for each instruction in the Credit Batch |
| PayeeFunctionalID | String (20) | Yes | The functional ID of the beneficiary. |
| Amount | Float | Yes | Amount to be Credited |
| Currency | String (3) | Yes | Transaction Currency Code |
| Narration | String (50) | No | Description of Payment |
{% openapi src="/files/rM2iiMNeakLltR6gyigk" path="/bulk-payment" method="post" %}
[bulkpayment.yaml](https://421627467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuJEXiAICNFsZ8S17X5KP%2Fuploads%2Fgit-blob-2401e007202bfb1ab83e35c3e54d697a46df0dd1%2Fbulkpayment.yaml?alt=media)
{% endopenapi %}
#### Response Parameters
| Field | Type | Required | Description |
| ------------------- | ------------ | -------- | -------------------------- |
| ResponseCode | String (2) | Yes | 00 – Success, 01 – Failure |
| ResponseDescription | String (200) | Yes | |
| RequestID | String (12) | Yes | Echoed from Request |
## 8.6 Voucher APIs/Voucher Management
The first API in the section below is used to request for a voucher with a specific value, currency, and purpose. The server responds with a voucher number, serial number, and expiry date. The second call activates the pre-activated voucher. The third call processes voucher redemption, crediting the merchant if valid. A fourth API enables batch voucher activation through encrypted files. Additional APIs allow for voucher status checks and cancellations.
### 8.6.1 VoucherPreActivation API
The VoucherPreActivation API is used by non-Payment Building Blocks in the GovStack Framework to request for a voucher to be used. This call reserves the voucher (for a period, which is to be implemented). This API requests a single voucher from the voucher server that can be used for a future redemption process. The caller sends an amount, a voucher group (depending on the use case), the currency, and the name of the calling GovStack Building Block. If the API call is successful, the Payment Building Block will respond with a voucher number, a voucher serial number, and an expiry date.
{% openapi src="/files/JcuamNqlGkWZ4ERkDpzr" path="/vouchers/voucher\_preactivation" method="post" %}
[VMS-API2-VMS-API2-GS\_P\_VMS\_API-1.0.2-1.0.3-resolved\_asynch (1) (1).json](https://421627467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuJEXiAICNFsZ8S17X5KP%2Fuploads%2Fgit-blob-d41ef2d30ac5fa7793ba7f460ef34fb7cb747b96%2FVMS-API2-VMS-API2-GS_P_VMS_API-1.0.2-1.0.3-resolved_asynch%20\(1\)%20\(1\).json?alt=media)
{% endopenapi %}
### 8.6.2 VoucherActivation API
The VoucherActivation API is used by non-Payments Building Blocks in the GovStack Framework to activate a pre-activated voucher. This second function call is intended to ensure that the voucher is only activated when it is disbursed. This API requests for the activation of a voucher when the caller sends the voucher number to be activated. If the API call is successful, the activation is confirmed, and the voucher can now be used by the beneficiary.
{% openapi src="/files/JcuamNqlGkWZ4ERkDpzr" path="/vouchers/voucher\_activation" method="patch" %}
[VMS-API2-VMS-API2-GS\_P\_VMS\_API-1.0.2-1.0.3-resolved\_asynch (1) (1).json](https://421627467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuJEXiAICNFsZ8S17X5KP%2Fuploads%2Fgit-blob-d41ef2d30ac5fa7793ba7f460ef34fb7cb747b96%2FVMS-API2-VMS-API2-GS_P_VMS_API-1.0.2-1.0.3-resolved_asynch%20\(1\)%20\(1\).json?alt=media)
{% endopenapi %}
### 8.6.3 BatchVoucherActivation API
The BatchVoucherActivation API is used by a calling Building Block to activate vouchers in bulk. This may be used for bulk social cash transfers where the recipients receive benefits by vouchers. The calling Building Block is responsible for generating the beneficiary file as well as dispensing the vouchers. The Payments Building Block is responsible for generating and redeeming the voucher codes. Both BBs will have had to have exchanged encryption keys during the implementation phase.
The file provided by the calling Building Block (typically the Scheduler Building Block) will typically contain a unique identifier, the amount of the voucher required, the currency of the voucher, and the voucher group. While the file format may vary, the recommended file format is an encrypted JSON file.
If the file is properly formatted, the Payments Building Block will respond with a file that contains the unique ID that was sent, the status, the voucher number, the voucher serial number, and the expiry date of the voucher. The response file will also be an encrypted file to ensure the appropriate security of the voucher number.
The calling building block will dispense the vouchers as needed using an appropriate delivery mechanism. The calling Building Block will also be responsible for any verification of the beneficiary during the redemption process. The description of the dispensing of the vouchers once the calling block has received it is outside the scope of the Payments Building Block.
### 8.6.4 VoucherRedemption
The VoucherRedemption API is used by non-Payment Building Blocks in the GovStack Framework to redeem a voucher. The calling Building Block will capture the voucher number and the voucher serial number from the merchant point. The external Building Block will also acquire the merchant name and payment details from the merchant registry. The calling Building Block will then send the voucher number, the voucher serial number, the merchant’s name, and payment details. The Payment Building Block will verify that the voucher has been activated and has not been used or blocked or canceled. If so, the Payment Building Block will then send a payment request to the funding agency/Financial Services Provider. The Payment Gateway of the Payments Building Block will facilitate the debit of the funding account, and the credit of the merchant as well as handle any intermediary fees. Once the payment has been successfully done the Payment Building Block will mark the voucher as consumed and notify the merchant (and beneficiary if possible).
{% openapi src="/files/JcuamNqlGkWZ4ERkDpzr" path="/vouchers/voucher\_redeemption" method="post" %}
[VMS-API2-VMS-API2-GS\_P\_VMS\_API-1.0.2-1.0.3-resolved\_asynch (1) (1).json](https://421627467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuJEXiAICNFsZ8S17X5KP%2Fuploads%2Fgit-blob-d41ef2d30ac5fa7793ba7f460ef34fb7cb747b96%2FVMS-API2-VMS-API2-GS_P_VMS_API-1.0.2-1.0.3-resolved_asynch%20\(1\)%20\(1\).json?alt=media)
{% endopenapi %}
### 8.6.5 VoucherStatus API
The VoucherStatus API is used by non-Payment Building Blocks in the GovStack Framework to check the status of a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to determine the status of a voucher. The Payments Building Block will respond with one of the statuses of Pre-Activated, Activated, Suspended, Blocked, or Not Existing.
{% openapi src="/files/JcuamNqlGkWZ4ERkDpzr" path="/vouchers/voucherstatuscheck/{voucherserialnumber}" method="get" %}
[VMS-API2-VMS-API2-GS\_P\_VMS\_API-1.0.2-1.0.3-resolved\_asynch (1) (1).json](https://421627467-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuJEXiAICNFsZ8S17X5KP%2Fuploads%2Fgit-blob-d41ef2d30ac5fa7793ba7f460ef34fb7cb747b96%2FVMS-API2-VMS-API2-GS_P_VMS_API-1.0.2-1.0.3-resolved_asynch%20\(1\)%20\(1\).json?alt=media)
{% endopenapi %}
### 8.6.6 VoucherCancellation API
The VoucherCancellation API is used by non-Payments Building Blocks in the GovStack Framework to cancel a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to cancel the voucher. The Payments Building Block will respond with a status of Cancelled, Already Cancelled, or Not existing. The Voucher Cancellation will override the Blocked status and render the voucher permanently unusable.
***
# 9 Internal Workflows
This section provides a detailed view of how the Payments Building Block will interact with other Building Blocks to support payments.
## 9.1 G2P Bulk Payment Workflows
This section discusses the various processes involved in G2P disbursement, such as beneficiary onboarding into the Account Mapper, bulk disbursements to pre-registered financial addresses, and account pre-validation prior to bulk disbursement.
### 9.1.1 Beneficiary Onboarding in Account Mapper
The workflow represents the process of onboarding beneficiaries in the ID Mapper as a prerequisite step before any payment processing can occur. This use case is triggered when a new G2P beneficiary has been onboarded by a G2P program, assigned a Functional ID, and verified as eligible for the social benefit program.
{% @mermaid/diagram content="sequenceDiagram
note left of RBB: Functional ID is issued to Beneficiary, Request parameters can be json array for bulk onboarding
RBB -->> IM: Register\_Beneficiary (Request ID,\nSource BB ID, Array of Beneficiaries)
IM -->> PBB: Register\_Beneficiary (Request ID,\nSource BB ID, Array of Beneficiaries)
note left of PBB: Validate parameters, Authenticate Source Building block exists
PBB -->> AM: Register\_Beneficiary (Request ID,\nSource BB ID, Array of Beneficiaries)
note left of AM: For each Payee Functional ID, Duplicate Check, Register in mapper
AM -->> PBB: Register\_Beneficiary\_Respone(Request\_ID,\nResponse Code,Array of Failed cases)
PBB -->> IM: Register\_Beneficiary\_Respone(Request\_ID,\nResponse Code,Array of Failed cases)
IM -->> RBB: Register\_Beneficiary\_Respone(Request\_ID,\nResponse Code,Array of Failed cases)" %}
1. The Requesting Building Block (RBB) sends a "Register\_Beneficiary" request to the Information Mediator (IM), containing the Request ID, Source Building Block (SBB) ID, and an array of beneficiaries with their Functional ID, Payment Modality, and Financial Address (if available).
2. IM forwards the "Register\_Beneficiary" request to the Payments Building Block (PBB) with the same parameters.
3. PBB validates the API parameters and checks if the Source Building Block is configured in the Payments BB as an acceptable source of the API call.
4. If the parameters are valid, PBB sends the "Register\_Beneficiary" request to the Account Mapper (AM) with the same parameters.
5. Account Mapper checks for duplicate Functional IDs registered by the same Source Building Block and registers the beneficiaries in the mapper if they are not already registered.
6. Account Mapper sends a "Register\_Beneficiary\_Response" to PBB, which contains the Request ID, response code, and an array of failed cases (if any) with descriptions.
7. PBB forwards the "Register\_Beneficiary\_Response" to IM, with the same parameters.
8. Finally, IM sends the "Register\_Beneficiary\_Response" to RBB, providing the final response code and the list of any failed cases with descriptions.
The workflow supports the addition of beneficiaries in the mapper in bulk. The source building block can use the same APIs for individual or bulk onboarding.
### 9.1.2 Pre-validation of Accounts prior to Bulk Disbursement
This flow represents the prevalidation process of accounts in a bulk disbursement scenario. The process involves a Source BB (SBB), Payments BB (PBB), Payer Bank (PrBank), and Payee Bank (PyBank).
{% @mermaid/diagram content="sequenceDiagram
title Prevalidation of Accounts
note right of SBB: Prepare Bulk Disbursement instructions containing 1. FunctionalID 2. Amount 3. Description/Narration 4. Instruction ID
SBB -> PBB: Prepayment\_Validation(Batch\_ID, Payment Instructions)
note left of PBB: 1. Debulking 2. Check each Payee Functional ID in mapper 3. Record Failed Instructions
loop Send Payee Bank wise Sub-Batches
PBB -> PrBank: Bulk\_ValidateAccount (Batch\_ID, Destination\_BIC,Payment Instructions)
PrBank -> PyBank: Account Validation Request as per Incumbent Scheme Norm
note left of PyBank: 1. Validate A/C exists 2. Validate it can receive Credit 3. Validate Credit limit won't exhaust
PyBank -> PrBank: Account Validation Response as per Incumbent Scheme Norm
PrBank -> PBB: BulkValidateAccount\_Response (BatchID, Array of Failed Instructions)
end
PBB -> SBB: Prepayment\_Validation\_Response(BatchID, Array of Failed Instructions)
" %}
1. The process begins with the Source BB (SBB) preparing bulk disbursement instructions containing key information such as the Functional ID, amount, description/narration, and instruction ID.
2. SBB sends these instructions as a prepayment validation request (Prepayment\_Validation) to Payments BB (PBB).
3. Upon receiving the request, PBB performs several actions, including debulking the instructions, checking each payee's Functional ID in the mapper, and recording any failed instructions.
4. PBB then sends payee bank-wise sub-batches for validation in a loop. For each sub-batch, PBB sends a bulk validate account request (Bulk\_ValidateAccount) to the Payer Bank (PrBank), including the batch ID, destination BIC, and payment instructions.
5. PrBank forwards the account validation request to the Payee Bank (PyBank) as per the incumbent scheme norm.
6. PyBank performs several validation checks, such as confirming the account exists, verifying that it can receive credit, and ensuring that the credit limit won't be exhausted.
7. PyBank sends an account validation response back to PrBank, adhering to the incumbent scheme norm.
8. PrBank then sends a bulk validate account response (BulkValidateAccount\_Response) to PBB, containing the batch ID and an array of any failed instructions.
9. Finally, PBB sends a prepayment validation response (Prepayment\_Validation\_Response) to SBB, including the batch ID and an array of any failed instructions.
This flow ensures that the accounts involved in a bulk disbursement transaction are valid and capable of receiving the specified credits before processing payments, reducing the risk of failed transactions and improving overall efficiency.
### **9.1.3** Bulk Disbursement into a Financial Address pre-registered in the Account Mapper
The workflow depicted below illustrates the process of bulk disbursement into financial addresses, such as bank accounts or mobile wallets, that are pre-registered in the Account Mapper. This use case is triggered when the Source BB submits a batch for processing of payments to the Payments BB.
Pre-conditions: Functional IDs intended to be recipients of funds must be pre-registered in the Account Mapper. All the financial addresses must be validated before a payment is disbursed.
Data Inputs: Source BB provides relevant confirmation to the Payments BB to begin credit transfer for successfully pre-validated accounts.
{% @mermaid/diagram content="sequenceDiagram
title Bulk Disbursement into an online Financial Address
SBB ->> PBB: BulkPayment(Batch\_ID, Payment Instructions)
PBB ->> PrBank: getAuthorization()
PrBank ->> PBB: getAuthorization\_Response()
loop Send Payee Bank wise Sub-Batches
PBB ->> PrBank: BulkPayment\_ReceiverFI(Batch\_ID, Destination\_BIC, Payment Instructions)
end
note over PrBank: Payer Bank processes each Receiving FI Batch and processes instructions as batch or single instructions, depending on available transaction rails.
PrBank ->> PBB: BulkPayment\_StatusPush(BatchID, Credit Instructions)
" %}
1. The process starts with Source Building Block (SBB) sending a BulkPayment request containing a Batch\_ID and a set of payment instructions to the Payment Building Block (PBB).
2. PBB checks if liquidity was provisioned before this batch is executed and if sufficient liquidity was provisioned. If this is the case, PBB proceeds to de-bulk crediting batches by the receiving institution.
3. PBB then requests authorization from the PrBank by sending a getAuthorization() message.
4. PrBank responds with a getAuthorization\_Response() message, granting the required authorization to PBB.
5. PBB begins sending payee bank-wise sub-batches to PrBank in a loop. For each sub-batch, PBB sends a BulkPayment\_ReceiverFI message containing the Batch\_ID, Destination\_BIC, and payment instructions.
6. The Payer Bank (PrBank) executes these batches through existing rails.
Exceptions: Some accounts might have been pre-validated or part of the crediting batch but cannot be credited by the payee bank for some reason. For such accounts, funds must be returned to the payer bank and credited back into the Source BB's Settlement Account through a separate process.
In order to facilitate the transfer of funds from the disbursement organisation (the payer) to the mobile money provider, the mobile money provider would need to be connected to the payment gateway/switch. Should this connection not be in place, the disbursement could be facilitated by a third-party aggregator or there would need to be a bilateral connection between the payer’s Financial Service Provider and the Mobile Money Provider.
## 9.2 G2P Beneficiary Payments Using Vouchers
The Voucher Management System supports three workflows for voucher payments:
1. administration (voucher provisioning and merchant registration),
2. voucher issuing (pre-activation and activation),
3. redemption use cases as shown in the diagram below.
These use cases and the relationship between each one of them are shown and further described below.
The use cases are described in the diagram below:
{% @mermaid/diagram content="graph TD
Voucher\_provisioning --> Voucher\_Printing --> Merchant\_Redemption
Voucher\_Printing --> Agent\_Cashout
Merchant\_registration --> Merchant\_Redemption" %}
### **9.2.1 Voucher administration**
These processes are usually done prior to the issuance of the voucher to ensure a smooth flow at the point of issuance.
The Admin processes for the Voucher Management Server cover the lifecycle of the vouchers and are typically performed by a privileged user (this may be done through User Interface or an API). These processes include but are not limited to creating voucher groups, provisioning vouchers, suspending vouchers, unsuspending vouchers, validating vouchers, key management, and purging of used vouchers.
* Voucher Provisioning\
This function will be done by an administrator (privileged user). It will typically be triggered by the deposit of funds in a funding account, thus the source account. Voucher provisioning creates a conditional right to funds and an inventory of issued vouchers. Other processes related to this are voucher inventory management, voucher suspension, and voucher purging.
* Merchant Registration\
In order for efficient redemption of vouchers merchants MUST be registered in advance to create a network of trusted providers. This registration is assumed to be managed by the Registration Building Block, The account verification of the merchant can be done at registration or during redemption subject to a configuration.\
\
During the registration process, merchants MAY also be assigned to different voucher groups depending on the required function that has been implemented. For example, there may be a voucher group for schools. This implies that vouchers of this type can only be redeemed at schools. This also requires that the user flow system at which the voucher is issued is aware of these voucher groups and is able to send the appropriate request to the Voucher Management System.
* Agent Registration\
In markets where cashouts are being used, it is expected that the Registration Building Block will register agents in a similar way.
* Voucher Groups\
Depending on the requirement it should also be possible to set up multiple voucher groups. Vouchers in the same voucher group will have similar characteristics and are labeled with a specific voucher group name. During voucher provisioning, a voucher can be created and attached to a single voucher group. When a voucher is requested (using the pre-activation API) it is expected that the voucher group will be one of the parameters set.
* Voucher Issuing\
Voucher issuing is triggered by the Registration Building Block which will determine whether the conditions of issuance have been met. The calling Block will determine the denomination and voucher group of the voucher to be issued. The voucher number and the voucher serial number that is issued can be presented to the beneficiary in multiple ways including but not restricted to encoding in the form of QR codes, bar codes, printed vouchers, or even SMS. This is outside the scope of the Payments Building Block. It is expected that Building Blocks through which the voucher is redeemed will also be able to decode the voucher.
### **9.2.2 Voucher Activation workflow**
The voucher activation flow is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Activation v3
Source BB->Payment BB: Activate voucher
Payment BB-->Source BB: Voucher successfully Activated
alt Error 400
Payment BB-->Source BB: Invalid request
end
alt Error 456
Payment BB-->>Source BB: Invalid voucher serial number
end
alt Error 460
Payment BB-->Source BB: Gov Stack Building Block does not exist
end
alt Error 455
Payment BB-->Source BB: Voucher group exhausted
end
alt Error 500
Payment BB-->Source BB: Internal Server error
end
alt Error 503
Payment BB-->Source BB: Service Unavailable
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end
" %}
Flow Description:
* An external Building Block may invoke the Payments Building Block API gateway to pre-activate API on the Voucher Management Server with the amount of the voucher, the voucher currency, and the voucher group. The calling Building Block may optionally send a comment. The comment will be stored by the voucher server. The voucher group will indicate that it is looking for a voucher from a specific voucher group. This API call will be made through the Payments orchestrator.
* The voucher group is typically used for conditional social transfer (e.g. for school fee payment). If any voucher can be used for any purpose, then all vouchers should be created with a generic voucher group (e.g. “GENERAL-PURPOSE”).
* The API returns to get a voucher number, the voucher serial number, and its expiry date. At this point, the voucher will be flagged as Pre-Activated.
* The calling Building Block may render the voucher as a QR code, as a barcode, or even as an SMS text. It is recommended that the voucher should include supplementary data of the recipient. It is also recommended that this data should also be printed in human-readable form so that the recipient can verify the data on the voucher. This data can also be verified at the point of redemption.
* Once the calling API successfully prints/issues the QR code, the voucher can then be activated using the activation API. It is assumed that there will not be a substantial delay between pre-activation and activation to necessitate the need for multiple expiry periods.
Alternative: the voucher could be activated immediately on being requested. This could be controlled at the Payments Orchestrator.
* Preconditions
* The calling registration block will determine that all the necessary preconditions are met.
* The most critical precondition is the prefunding which will be done manually at the voucher provisioning stage. Other options that could be prefunding triggered by activation or at redemption are not considered because they are considerably more complex and create additional failure points in the activation of the vouchers.
* Assumptions/Queries
* It is assumed that only one currency will be used.
* A zero-trust architecture.
* The transaction is not reversible.
* Post-Condition\
The calling Building Block may invoke another payment Building Block API, e.g. initiating an incentive payment for the agent.
### **9.2.3 Voucher Redemption workflow**
The voucher redemption process is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Redemption
Source BB (Merchant Interface) ->> Merchant registry: Submit voucher details
Merchant registry -->> Source BB (Merchant Interface): Merchant name and payment details
Source BB (Merchant Interface) ->> Payment BB: Submit voucher and merchant details
alt Error 400
Payment BB-->>Source BB (Merchant Interface): Invalid request
end
Payment BB ->> Payment BB: Check Voucher
alt Error 458
Payment BB-->>Source BB (Merchant Interface): Voucher number already used
end
alt Error 461
Payment BB-->>Source BB (Merchant Interface): Invalid voucher number
end
Payment BB->>FSP: Debit request
alt Error 599
Payment BB-->>Source BB (Merchant Interface): Network connection error
end
FSP->Funding A/c: Debit request
Funding A/c -->> FSP: Debit successful
alt Error 462
FSP -->> Payment BB: Insufficient funds
Payment BB -->> Source BB (Merchant Interface): Insufficient funds
end
FSP->Merchant A/c: Credit Request
Merchant A/c -->> FSP: Credit Request successful
alt Error 463
FSP -->> Payment BB: Cannot credit merchant
Payment BB -->> Source BB (Merchant Interface): Cannot credit merchant
end
Payment BB ->> Payment BB: Consume Voucher
Payment BB ->> Source BB (Merchant Interface): Amount credited to merchant account and voucher is consumed
" %}
Flow Description:
* At redemption, the beneficiary shows the voucher to the merchant or agent.
* The merchant/agent will scan and interpret the medium in which the voucher is presented (this could be a QR code or a barcode or an SMS or even a printed number).
* Voucher redemption Validation: The details presented MAY allow the merchant/agent to authenticate/validate the owner of the voucher.
* The agent will then initiate the redemption process which will call the Payment Building Block API Management Gateway.
* The API Management Gateway will validate the voucher and initiate the payment through the payment gateway.
* If specific voucher groups have been set up, voucher usage may be restricted to specific merchants. An override parameter should also be provided that will allow a Voucher of any voucher group to be redeemed at any merchant.
* Once the payment to the merchant/agent is successful the Payment gateway will inform the API Management Gateway.
* The API Management Gateway will then instruct the VMS API to flag the voucher as consumed.
Alternatives:
* Payments could be made through a switch in which case there would be no need for prefunding accounts in each financial institution.
Preconditions:
* The merchant must have been registered possibly by the Registration Building Block with their preferred payment method.
* The merchant must have a mechanism (e.g. a mobile APP, USSD app, or SMS option) to verify the beneficiary prior to redemption.
Assumptions:
* The app for reading the QR code and redemption is not part of the scope of the Payment Building Block.
* The entire voucher amount is consumed. Partial redemption will not be allowed.
* The amount that is paid to the merchant or agent is debited from a prefunded account.
**Sample Redemption**
.png?alt=media)
Note:
In the case of a physical voucher, the voucher number or the secret number is hidden behind some material that must be scratched away to see the number. The voucher number is also commonly known as the PIN.
### **9.2.4 Voucher Cancellation workflow**
The voucher cancellation flow is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Cancellation
Source BB -> Payment BB: Cancel Voucher
Payment BB-->Source BB: Voucher Cancelled
alt Error 499
Payment BB-->Source BB: Invalid Request
end
alt Error 463
Payment BB-->Source BB: Invalid Voucher
end
alt Error 464
Payment BB-->Source BB: Voucher is already cancelled
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end
" %}
Flow Description:
* The calling Building Block will request the API Management Gateway to cancel a Voucher.
* The API Management Gateway will invoke the VMS API to cancel the Voucher.
* The Vaucher Management System (VMS) API interface will check if the Voucher is valid and then cancel the Voucher.
* The VMS API interface will confirm that the Voucher has been canceled.
Alternatives:
* If the Voucher does not exist, the VMS API will respond that the Voucher does not exist.
* If the Voucher is already consumed, the VMS API will respond that the Voucher is already consumed.
* If the Voucher is already canceled the VMS API will respond that the Voucher is already canceled.
* If the Voucher is suspended the VMS API will respond that the Voucher is suspended.
* All calls from external parties (e.g. Registration Building Block) to the voucher management system will be initiated through the API management gateway.
* The payment orchestration module may direct transitions between the various functions.
* The discovery service could be called by other building blocks to determine where bank accounts/wallets sit.
* The only function that speaks to the DFS is the payment gateway. Any function that needs to speak to the DFS goes through the Payment gateway.
* The Payment gateway may need to speak to a Number Portability provider.
* Audit trails (transaction logs) capture each event as it happens and are to be used for queries, analysis, and reconciliation.
* Event logs will capture specific events that happen at each node.
## 9.3 P2G Payments
The following types of P2G payments are considered.
* Bill payments
* Payments for government services (application for a birth certificate)
* Payment for registrations. (In the case of the [Registration for Postpartum and Infant Care](https://github.com/GovStackWorkingGroup/BuildingBlockAPI/issues/1) use case)
There are two possible scenarios that can be supported:
a) P2G payment is initiated by the Payer
b) P2G payment is initiated by the Payee (USSD push payment for example)
Scenario a) can also be implemented using QR code.
### 9.3.1 P2G Payment initiated by the payer
{% @mermaid/diagram content="sequenceDiagram
title Payer initiated P2G payments
Registration BB ->> Payments BB: Send Transaction details
Payments BB-->>Registration BB: Payment reference
Registration BB ->> Payer: payment reference
Payer ->> FSP: Invoke Bill payment service
FSP -->>FSP: Debit payer, credit payee
FSP -->> Payments BB: Payment notification
Payments BB -->> Registration BB: Payment success notification
Registration BB -->> Messaging BB: Payment success notification
Messaging BB -->> Payer: Payment success notification
" %}
Flow Description:
* Upon registration for a government service, the Registration Building Block sends transaction details to the Payments Building Block which creates and returns a unique payment reference for the payer of the service.
* The Registration Building Block sends the unique reference number to the payer.
* After entering their account the payer would invoke a bill payment to a selected service (in this case paying for the registration service). The payer would need to enter the payment reference which would prompt the retrieval of the payment details from the Registration Building Block in real time. If the payment details are correct, the payer is prompted to enter their mobile money pin to authorize the payment.
* Upon authorisation, the payer’s account is debited and the government’s connected account is credited in real time. The Financial Service Provider, in this case, the mobile money provider would then notify the success status of the Payments Building Block.
* For this type of payment, as the payment reference is needed to validate the payment, this can be done by any mobile money account holder.
Notes:
The above model requires that the payer must provide two pieces of information through their USSD, STK, or mobile app:
* A merchant ID. Typically the government would be given a special merchant ID. The payer should be able to select which government service they would be paying for through the mobile money interface.
* A reference ID: this is unique and time bound for each transaction.
* As the bill payment is invoked by inputting the reference number which prompts the retrieval of the payment details in real-time from the registration building block, a failed transaction could be triggered by a session time-out or a wrong PIN. In both cases, the payer would have to re-initiate the transaction.
* In the P2G payment in the flow above, the government holds an account with the Financial Services Provider which would collect the payments on the government's behalf and transfer them to the single treasury account on a defined timeline (i.e. daily) in an aggregated way. For reconciliation purposes, the Registration Building Block would need to notify the government of a successful/unsuccessful payment.
### 9.3.2 P2G Payment Initiated by Payee (e.g USSD push payment) sequence diagram
{% @mermaid/diagram content="sequenceDiagram
title Payer initiated P2G payments
Registration BB ->> Payments BB: Send Transaction details
Payments BB->>FSP: Request USSD Push
alt Error 402: Account restrictions
FSP -->>Payments BB: Payment Failure notification
Payment BB -->> Registration BB: Payment Failure notification
end
FSP ->>Payer: Push USSD notification
Payer -->>Payer: Enter Pin to confirm the transition
Payer ->>FSP: transaction athorisation
FSP -->FSP: Debit payer, credit payee
FSP ->> Payments BB: Payment notification
Payments BB ->> Registration BB: Payment success notification
Registration BB -->> Messaging BB: Payment success notification
Messaging BB -->> Payer: Payment success notification" %}
Flow Description:
* Upon registration for a government service, the registration building sends transaction details to the Payments Building Block which sends a payment request to the payer through their mobile money provider (Unstructured Supplementary Service Data prompt).
* The payer will see a request coming for the specific service requested with payment details, prompting them to authorize the payment by entering the pin code.
* Upon authorisation, the payer’s account is debited and the government’s connected account is credited in real time.
* The Financial Services Provider, in this case, the mobile money provider would then notify the success status to the Payments Building Block.
* This payment differs from the previous P2G mobile money payment as the payment is not initiated by the payer by invoking a bill payment but is initiated by a merchant (in this case the government agency providing the service). Therefore the payer is requested to pay for the service immediately.
Notes:
* There can be no error in the above as both the merchant number and the payment reference are pushed to the phone.
* The only risk here is a timeout on the Unstructured Supplementary Service Data or the user keying in the wrong PIN which may require the transaction to be reinitiated.
### 9.3.3 P2G Payment implementation using QR Code workflow
{% @mermaid/diagram content="sequenceDiagram
title P2G Mobile Money Payment with QR code
Registration BB->>Payments BB: Send Transaction details
Payments BB -->> Registration BB: Generates payment reference
Registration BB ->> Registration BB: Generate QR code
Registration BB ->> Payer: QR code is reads Payment reference
Payer -->> FSP: Invoke Bill Payment service
FSP ->> FSP: Debit Payer
FSP ->> FSP: Credit Gov
FSP ->> Payments BB: Payment notification
Payments BB -->> FSP: Confirm payment
Payments BB -->> Registration BB: Payment success notification
Registration BB -->> Payer: Payment success notification
alt Error 401: Incorrect Payment Reference
FSP ->> FSP: Rollback Payer Debit
FSP ->> FSP: Rollback Gov Credit
FSP -->> Payments BB: Rollback successful
Payments BB -->> Registration BB: Payment failure notification
Registration BB -->> Payer: Payment failure notification\
end
" %}
Notes:
* There is small room for error in reading a QR code (unless the payer scans the wrong code).
* All mobile operators and banking apps need to be able to read the reference in the same way for this to work meaning that a standardised/interoperable QR code needs to be in place at a country level. While this is in place in some Asian countries (i.e. Indonesia, Sri Lanka) where there is widespread adoption of QR codes, In Africa the uptake of QR codes is significantly lower and standardisation is typically not in place at a country level.
* During registration, the Registration Building Block will generate transaction details including the amount to be paid by the payer and transaction ID, and send them to the Payments Building Block.
* The Payments Building Block will use the transaction details to initiate a request to pay to the Financial Service Provider.
* The QR payment widget displayed to the payer will have the following different attributes: payment\_entity\_id, amount, currency, transaction\_id
* The payer scans the QR code to approve/reject the payment.
* The Financial Service Provider sends a notification of the status of the transaction to the Payments Building Block and the payer.
* Transaction status is sent to the Registration Building Block on completion of payments.
* The Messaging Building Block sends a transaction confirmation message to the payer.
### 9.3.4 P2G Bill Payments
The P2G Bill Payments flow diagram illustrates the steps involved in processing bill payments between individuals and government agencies
{% @mermaid/diagram content="sequenceDiagram
title: P2G Bill Payments
Government agency -->>Payer: Send Invoice to payer
Government agency -->>Bill Aggregator: Send Invoice
Bill Aggregator -->> Payments BB: Send Invoice reference
Payer-->>Collection FSP: Invoice reference
Collection FSP -->> Payment BB: Request transaction details (Amount)
Payment BB -->>Bill Aggregator: Request transaction details
Bill Aggregator -->> Payment BB: transaction details
Payment BB -->>Collection FSP: transactions details
Note left of Collection FSP: Executes payment
Collection FSP -->> Payment BB: Sends payment reference
Payments BB -->> Bill Aggregator: Sends payment reference
Bill Aggregator -->> Government agency: Send payment reference
" %}
1. The Government Agency sends an invoice to the payer, detailing the amount owed.
2. The Government Agency also sends a copy of the invoice to the designated Bill Aggregator.
3. The Bill Aggregator then sends the invoice reference number to the Payments Building Block (Payments Building Block).
4. The payer, upon receiving the invoice, provides the invoice reference number to their preferred Collection Financial Service Provider (Collection Financial Services Provider).
5. The Collection Financial Services Provider (FSP) requests transaction details, including the amount to be paid, from the Payments Building Block using the invoice reference number.
6. The Payments Building Block, in turn, requests the transaction details from the Bill Aggregator.
7. The Bill Aggregator provides the requested transaction details to the Payments Building Block.
8. The Payments Building Block forwards the transaction details to the Collection FSP.
9. The Collection FSP executes the payment based on the transaction details provided.
10. After completing the payment, the Collection FSP sends the payment reference to the Payments Building Block.
11. The Payments Building Block forwards the payment reference to the Bill Aggregator.
12. Finally, the Bill Aggregator sends the payment reference to the Government Agency, confirming the completion of the payment.
# 10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
### 10.1 Key Decision Log
[A historical log of key decisions regarding this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183435345/Key+Decision+Log+Payments).
### 10.2 Future Considerations
[A list of topics that may be relevant to future versions of this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183402524/Future+Considerations+Payments).
### 10.3 Out-of-Scope Assumptions
[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/6ERMn830).
# Payments
Developed by Vijay Mauree (ITU), Arnold Kibuuka (ITU), Francesco Pasti (GSMA), James Dailey (MIFOS), Oscar Correia (Maarifa Education), Dr. P. S. Ramkumar (ITU), Khuram Farooq (World Bank), Elie Sawaya (GIZ)
# 1 Version History
The version history table describes the major changes to the specifications between published versions.
| Version | Authors | Comment |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 0.9.2 |
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, Sanjay Jain, Luukas Ilves, Lesley-Ann Vaughan
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume
Reviewers: Wesley Brown, Steve Conrad, Valeria Tafoya
| Final edits to align content to specification template for GovStack 1.0 release |
# 2 Description
This section provides context for this Building Block.
The Payments Building Block enables digital financial payments to be tracked, evaluated, initiated, validated, processed, logged, compared and verified against budget. This Building Block also provides interoperability with connections to the various external applications that need payment services in order to trigger transitions in their own workflow. Payment services generally interface through gateways to regulated financial entities such as banks, credit facilities, and insurance companies. To help users easily complete payment transactions and learn if their transaction succeeded or failed, it converts heterogeneous interface protocols, formats, and user interfaces to a standard set of common interfaces and formats. It can also help in tracking the costs of commodity and equipment purchases to optimize budgets.
The Payments Building Block consists of components that enable multiple use cases in a generic manner. The use cases include Government to Person (G2P), Person to Government (P2G), Government to Business (G2B), and Business to Government (B2G). The existing commercial Payments schemes are heterogeneous across regions and countries, the Payments Building Block assumes that some components are optional when considering implementation. The Payments Building Block covers components that can be used to deliver the key functionalities and the connections to existing systems in the market, but does not contemplate building a new Payments scheme.
### Financial Inclusion, Banks, and Mobile Money Accounts
Financial inclusion strategies have largely been based on growing access to regulated accounts. These were traditionally understood to be bank accounts, in recent years Mobile Money (MoMo) accounts have greatly increased transactional account access. These MoMo accounts are often, but not always, treated as secondary to the banking system and lack interoperability.
[According to GSMA](https://www.gsma.com/mobilefordevelopment/wp-content/uploads/2021/03/GSMA_State-of-the-Industry-Report-on-Mobile-Money-2021_Summary.pdf), globally registered mobile money accounts stood at 1.2 billion in 2020, transacting an average of over $2 billion per day, mobile money has grown to become the leading payment platform in a growing number of emerging markets. Today, there are more mobile money accounts in Sub-Saharan Africa than there are bank accounts. Indeed, during the pandemic, demand for mobile money services increased among businesses, governments, and new services that previously relied on cash or other payment channels.
There are currently active discussions in many markets on the need for the integration of mobile money into existing national infrastructure. While the integration of mobile money into existing schemes and infrastructure has the potential to create value for all stakeholders in the ecosystem, many legacy payment systems may not be suitable for mobile money integration in their current state. As an example, many existing interbank switches do not support mobile money as a core feature because of legacy technical architecture. What is often missing is the essential capability of the switch to handle high-volume, low-value flows with the mobile number (Mobile Station Integrated Services Digital Network) as identifier for routing and address resolution hence the need for integration. Recent industry developments offer solutions designed to solve many of the issues around the switching of mobile money.
Mobile money providers, regulators, infrastructure providers, and other financial system players should seek to engage in any potential interoperability initiatives from an early stage to ensure optimal payment system design for all parties. Should existing infrastructure be used, a thorough assessment should be conducted, with input from all parties, to ensure appropriate governance, commercial, and technical standards are incorporated. Mandating interoperability within a short time frame removes opportunities for a thoughtful and holistic analysis of commercial sustainability. Requiring immediate interoperability can also delay or hamper the uptake of interoperable transactions, and mobile money services altogether. This is a particular risk in contexts where regulators or governments impose immediate connections to a centralized hub. Mobile money providers should be encouraged to connect when their service is ready. However alternative modalities of payment such as cash vouchers can also be considered in scenarios of low-resource regions that lack modern infrastructure and a volume of mobile phone users. Also, in countries where mobile money providers are not connected to a payment switch, aggregators can enable the flow of funds between multiple financial service providers including banks and non-banks. While aggregators may not be as efficient and scalable as switches, they can help solve interoperability issues in the short and medium term.
## Payments Building Block Capabilities
Generally, the Building Block is supportive of multiple types of payment use cases where the Government is one of the parties:
* **Government to people (G2P)**
* Payment where the payer is a government and the payee is an individual e.g. Social benefits disbursement, government salary payments, Conditional and [Unconditional Social Cash Transfers](https://solutions.dial.community/use_cases/unconditional_social_cash_transf/use_case_steps/outreach_communications)).
* **People to Government (P2G)**
* Payment where the payer is an individual and the payee is a government. P2G payments can be government initiated, for instance, in the case of payments for registrations for government services. For bill payments and payments for government services directly by the person, the system should provide the person with the flexibility to choose which payment instrument to use (eg. mobile money, bank transfer or card payments). (e.g. payment of taxes, payment[ Registration for Postpartum and Infant Care](https://github.com/GovStackWorkingGroup/BuildingBlockAPI/issues/1), payment of school fees, driving license, utility payments).
* **Government to Business (G2B)**
* G2B payments include tax refunds, goods and services purchases, subsidies, contract payments, benefits, and loans.
* **Business to Government (B2G)**
* B2G payments include paying taxes and fees.
* **Government to Government (G2G)**
* Payments between two government entities (i.e. between Ministries/Departments and public sector institutions).
Government to Business payments (G2B) and Government to Government (G2G) are not covered in this specification and will be covered in the second phase.
## Government-to-Person Payment Principles
The implementation of the Payments Building Block should adhere to the following principles, particularly as it relates to Government-to-Person (G2P) payments:
### Beneficiary/Recipient-related Principles
* Beneficiaries can receive their payment through a fully functional account that allows them to save and make payments using an associated payment instrument with general acceptance.
* They can choose the payment service provider and payment instrument through which they receive their payments based on their informed choice; they can use the same account for multiple G2P payments, make Person-to-government (P2G) payments and easily switch if desired.
* Onboarding to their payment method is low cost and easy with account opening requirements that are available to recipients and with no opening fees; a payment instrument is provided to the recipient at no cost.
* The Integrated Financial Management Information System (IFMIS) is used to process government payments against budgetary allocations. It supports:
* the Treasury Single Account (TSA) that aggregates all incoming government receipts and disburses all government payments;
* budget management to ensure budget compliance, tracking, and reporting. The IFMIS provides the Ministry of Finance with a unified view of the government’s budget execution.
* The payment instrument is easy-to-use and generally accepted, and the overall costs for using it do not result in increased costs for the beneficiary in comparison to other forms of payment.
* Beneficiaries are well informed, their account/data is protected, and have access to redress. They know when, where, and how many payments will be made and understand how their payment method works, its costs, how to use their payment instrument, and how to access their payment. They can access and know how to access effective grievance redressal mechanisms, their funds are secured, and their data privacy is ensured.
* Beneficiaries can easily access their funds. They are able to cash out their funds at any time at a wide range of conveniently close financial access points. At a reasonable and clearly communicated withdrawal fee or at no cost.
* Beneficiaries are included regardless of gender, race, or other immutable characteristics, through at least one of the payment methods used; gender gaps are considered in the design.
### Infrastructure and Systems-related Principles
* The leveraged infrastructures and systems are shared across G2P programs and payment streams, as well as other use cases, avoiding the implementation of systems to exclusively deliver G2P payments. They are scalable and have cyber security arrangements in place.
* Common ID provides access to multiple programs; the national ID system has high coverage and quality; it allows government agencies and payment service providers to validate recipients’ identities; it enables data sharing across government agencies.
* Payment processing systems unlike social protection management information systems, pension, and payroll systems will not include gender-disaggregated data.
* The payment systems are interoperable to maximize the potential of the available infrastructure to recipients; interoperability arrangements exist for Integrated Financial Management Information System (IFMIS), Treasury Single Account (TSA), banks, and non-banks covering most channels and instruments.
* There is no manual intervention in the disbursement process and the entire payments flow is Straight-Through-Processing, including the reconciliation of payments. Payments are made without delays.
### Payment Services Provider-related Principles
* Payment service providers have a strong and long-term, predictable business case or incentives to deliver payments and provide choice.
* A large variety of bank and non-bank financial institutions operating in a competitive market are used to deliver G2P payments.
* Agents of bank and non-bank financial institutions are accessible to G2P payment recipients.
## Mapping Based on Level of Maturity
The [DIAL use cases](https://exchange.dial.global/use_cases) can be mapped to the Payments Building Block capabilities as follows.
Capabilities
Payment Infrastructure Scenario
DIAL User journey
Use Cases
Destination Channel
G2P
Scenario 1-4 & 6
Payment - Unconditional Social Cash Transfer (direct payment based on family relationship)
Payment - registration of birth (Postpartum and Infant Care)
Mobile Money.
## Payment Infrastructure Deployment Scenarios
### Regional Switch vs Country Switch
A Payment Switch is the software and hardware system that provides routing between regulated entities in a Payments Scheme.
Domestic payment switches have specific economic characteristics and may not reach adequate economies of scale. Whilst costs can be passed onto customers, without sufficiently low charges, volumes may remain perennially low. Domestic switches facing this scenario thus remain under-utilized, costly, and under-capitalized. In recent years, the concept of Regional payment switches has gained some traction with new efforts realized or underway across the Southern African Development Community (SADC), West African Monetary and Economic Union (UEMOA), East African Community (EAC), and Economic and Monetary Community of Central Africa (CEMAC).
Regional switches (which may serve as a common resource for multiple countries) often rely on pre-existing arrangements between Central Banks, regional Commercial Banks, or a combination thereof. When multiple currencies are in play, a reference currency or a basket of currencies must be chosen for regional settlement accounts to be viable. Settlement arrangements are vital to the viability of a regional switch. A Regional switch may also integrate financial transactions from countries that already have domestic payment switches (like a switch of switches).
Regional switches may take on any and all use cases or may be restricted to specific use cases, for example, Large Value Transfer or B2B trade. Because regional trade drives economic activity, regional switches often go hand in hand with the portability of business and consumer credentials (i.e. relating to Customer Due Diligence), trade policy, and movement of labor.
### Payment infrastructure scenarios
The Payments Building Block sits between the government account systems (i.e. at the Ministry of Finance or Central Bank) and the public or private switching available in the market. As such the Payments Building Block is assumed in each, but not shown. The primary focus in describing these scenarios is on the relationship between payment schemes, banking institutions, and government institutions. This section describes what is available in-country.
| **Infrastructure Scenarios** | **Suggested Approach** |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
Payment Infrastructure Scenario 1 Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks in different countries in a region.
| Government should leverage the regional payments switch (scheme) to enable all use-cases. This may also imply important developments of a standardized Customer Due Diligence (CDD). Note that while a State owned bank is shown in the diagram below, the option exists for the Government to designate a specific Commercial bank, or to have the funds flow directly from the Ministry of Finance (Treasury) assuming such Treasury payment functionality can be supported by the Regional Switch. |
|
Payment Infrastructure Scenario 2 A payment switch connecting financial service providers such as banks to non-banks including mobile money providers is in place and actively working.
| Government should leverage the existing switch to enable payments use-cases to reach mobile money providers. There may be a State Owned Bank (2-A) or not (2-B). |
|
Payment Infrastructure Scenario 3 A payment switch is in place in the country or is in the process to be deployed but non-banks, including mobile providers are not connected to it.
|
Government should leverage third-party aggregators or bilateral integrations to enable payment use-cases to reach mobile money providers.
|
|
Payment Infrastructure Scenario 4 A payment switch is not place or in the process of being deployed
| Government should leverage third-party aggregators or bilateral connections to enable payment use-cases to reach mobile money providers |
|
Payment Infrastructure Scenario 5 Government makes G2P payments using Central Bank Digital Currency (CBDC) .
| The Central Bank distributes the funds for the CBDC accounts via regulated entities (e.g. Payment Service Providers). |
|
Payment Infrastructure Scenario 6 Citizens have CBDC accounts directly with the Central Bank or other accounts with other payment service providers
| The Central Bank sets up limited accounts for each person, providing a base level of access and functionality. Such accounts may be denominated in country currency (fiat) or CBDCs. This scenario places more responsibility on government structures and is not often considered (outside of Postal Banks and the like). |
Under each of these scenarios, there are different setups possible that relate the key roles played by the Programmatic Ministries (e.g. Ministry of Education or Pension Program), the Ministry of Finance, the Central Bank, and the existing Payment Switch.
The flow of funds and the flow of data are separate but equally important and they have a number of interactions.
#### Payment Infrastructure Scenario 1
Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks.
#### Payment Infrastructure Scenario 2-A
Scenario 2-A and Scenario 2-B cover the concept of separating flows of data from accounting flows.
The Central Bank receives the funds transfer advice from the Treasury and the data from the Ministry of Health and does the steps of breaking it into bulk, based on rules of capacity of source and destination systems. Payments are then routed “on-us” or to the external financial providers “off-us” via a payment switch or similar mechanism.
#### Payment Infrastructure Scenario 2-B
The Central Bank plays a key role as a participant in the Payment scheme and routes the payment details and funds via a shared service of the payment switch. The same logic of break-bulk applies and with all transactions effectively “off-us”.
#### Payment infrastructure scenario 3
Government should leverage third-party aggregators to enable payment use cases to reach mobile money providers
#### Payment Infrastructure Scenario 4
A payment switch is not in place or in the process of being deployed. Government should leverage third-party aggregators or bilateral connections to enable payment use cases to reach mobile money providers. In the bilateral connection scenario, each mobile money provider in the country would connect to the government portal through APIs, enabling a seamless transfer of funds to end users (in the case of G2P payments) or the receiving of funds from end users (in the case of P2G payments) and facilitate reporting, reconciliation and settlement processes.
%20\(1\)%20\(2\).png?alt=media)
#### Payment Infrastructure Scenario 5
The Central Bank mints digital currency and distributes funds via regulated entities (e.g. Payment Service Providers), and in the case of G2P sends funds to destination accounts known to the Ministry of Finance. Account information is unitary and unique for all beneficiaries (e.g. citizens) but the Central Bank does not “hold” account balances on an individual basis.
#### Payment Infrastructure Scenario 6
The Central Bank directly provides Digital Accounts for all people (Citizens) and Treasury routes funds to the relevant accounts (uniquely and unitarily held by people).
* For this payment use case, the most common scenarios currently in place are 1 to 4, scenario 5 and 6 could be envisaged later.
* In Scenario 2B it is assumed that the Payment Switch is run by the Central Bank.
* In Scenario 2A and 3, it is assumed that the Payment Switch is an independent part outside the Central Bank.
# 3 Terminology
Terminology used within this specification.
Several elements of the glossary are based on the terminology defined by the [level one project](https://www.leveloneproject.org/wp-content/uploads/2020/07/L1P_Guide_2019_Final.pdf) and [ITU DFS Glossary](https://www.itu.int/en/ITU-T/focusgroups/dfs/Documents/201701/ITU_FGDFS_DFS-Glossary.pdf)
Term
Description
Authentication
The validation of user credentials for the purpose of system login and basic access.
Aggregators
Act as payment facilitators for billers by onboarding multiple billers on their platform and are responsible for, connecting with PSPs and FSPs on behalf of Billers, often, also communicating specific Bill IDs to the consumers to collect amount through their respective platforms and settling the collected amount with the billers.
Authorization
The permission given by the Payer or entity to make a Payment.
Beneficiary
Non referring to a payee of a program.
Billers
Entity responsible for: Generating Bills with Bill ID’s in PSP’s identifiable format, distributing Bills to the customer (either directly or via another service / channel), marking bill as paid upon confirmation from Payment service provider.
Bulk Payments
A Payment from a single Payer to multiple Payees, for example, cash transfer programs from a government or non-governmental organization to a set of beneficiaries.
End User
The customer of a digital financial services provider. The customer may be a consumer, a merchant, a government, or another form of enterprise.
Financial Management Information System
The budget management system of the government treasury which ensures that government (Ministries, Departments, Agencies) payments are processed within the approved budget and releases.
Financial Services Providers (FSPs)
A financial services provider refers to one that is licensed by a regulatory authority to provide transaction accounts that hold customer funds and are used to make and receive payments. Digital Financial Services Providers (DFSPs) have relationships with consumers, merchants, and other enterprises, and provide digital financial services to End Users.
Interoperability
The ability of DFSPs participating in a payment Scheme to exchange Transactions with each other. The term may also be used when two systems interconnect.
Account Mapper or Account Lookup Directory Service
A dynamic directory matching beneficiaries’ unique identifier and their account numbers enable multiple programs to direct payments to the same account and beneficiaries to switch payment service providers. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases.
Mobile Money (MoMo)
A mobile money service includes transferring money and making and receiving payments using a mobile phone. The service must be available to the unbanked, e.g. people who do not have access to a formal account at a financial institution. The service must offer a network of physical transactional points which can include agents, outside of bank branches and ATMs, that make the service widely accessible. Mobile banking or payment services (such as Apple Pay and Google Wallet) that offer the mobile phone as just another channel to access a traditional banking product are not included.
Mobile Money Services Provider
A category of DFSPs that use mobile phones as the access method to provide transaction Accounts to End Users.
Payee
The recipient of funds in a payment transaction.
Payer
The person/organization whose account is debited in a payment transaction.
Payment
Exchange of funds, credentials, and other necessary information to complete an obligation between End Users. A transfer is an example of a payment.
Payment Alias/Payment address
An alias may include phone numbers, email addresses, or other handles. They may include globally unique URIs and may be chosen by the user. These are increasingly seen in new payment systems. Within systems, the payment alias points to an underlying payment account address, specifically and uniquely located within a payment scheme. A payment address may be different from the underlying account address, depending on the payment scheme rules but is often the same thing.
Quick-Response (QR) Code
A method of encoding and visualization of data, which are machine-readable. There are multiple QR models.
Routing
The process by which a route to a payment address is determined. The mechanism of sending payment information across different systems. This is sometimes used interchangeably with addressing.
An entity which receives transactions from one provider and routes those transactions on to another provider. A switch may be owned or hired by a scheme or be hired by individual providers. A switch will connect to a settlement system for inter-participant settlement. (https://www.itu.int/dms_pub/itu-t/opb/tut/T-TUT-ECOPO-2018-PDF-E.pdf)
Transaction
A reference to the entirety of the exchange, including a Payment but may also include information between the Payer’s DFSP and the Payee’s DFSP.
Treasury Single Account
A Treasury Single Account (TSA) is a unified structure of government bank accounts that gives a consolidated view of government cash resources. Based on the principle of unity of cash and the unity of treasury, a TSA is a bank account or a set of linked accounts through which the government transacts all its receipts and payments. The principle of unity follows from the fungibility of all cash irrespective of its end use. While it is necessary to distinguish individual cash transactions for control and reporting purposes, this purpose is achieved through the accounting system and not by holding/depositing cash in transaction-specific bank accounts. This enables the treasury to delink management of cash from control at a transaction level.
Uniform Resource Identifier (URI)
A unique sequence of characters that identifies a logical or physical resource used by web technologies.
Voucher
A token that entitles the holder to a discount or that may be exchanged for goods or services.
Voucher Group
A voucher group is a characteristic of a voucher that restricts the function or use case that a voucher can be used for. It can also be used as a dimension for reporting on.
# 4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
The Payment Building Block will handle payments processing and orchestration, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions.
The Building Block will enable government programs to channel payments through a shared payments infrastructure to accounts at multiple providers, allowing citizens to choose their preferred Financial Services Provider and switch providers if their circumstances change or they discover a better service.
### 4.1 Payment Orchestration
Payments orchestration provides for end-to-end workflow across different sub-subsystems, enables asynchronous processing, and covers different payment types, use cases, account systems, and channels.
### 4.2 Voucher Management
The Payment Building Block will provide a voucher management system which is responsible for provisioning, storage, issuance, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
### 4.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
The account lookup directory service or mapper simplifies payment routing and is an important component to avoid storing the payment information of the user in the social registry system and preserve the privacy and confidentiality of sensitive information pertaining to the beneficiary.
### 4.4 Payment Request Initiation
The Payment Building Block must allow systems to initiate a payment request. This request could come from two sources: external or internal. An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll).
### 4.5 Payment Gateway
The Payments Building Block should provide a payment gateway which allows different (digital) Financial Service Providers (FSPs) to interoperate.
### 4.6 Payment Portal
The Payments Building Block should provide a Payment Portal which allows users to manage thje full lifecycle of sending and receiving payments
### 4.7 Event Management
The Payment Building block must support different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
### 4.8 Reconciliation
The Payments Building block must implement functionality that provides both internal and external reconciliation services.
### 4.9 Batch Processing
The Payments Building Block should provide batch processing services
### 4.10 Scheduling Services
The Payments Building Block should provide scheduling services to perform tasks on a regular or repeated basis
### 4.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
### 4.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
### 4.13 Reporting Services
The Building Block should provide reporting services, which may consist of dashboards or analytics reports. These reports should be configurable based on user needs.
### 4.14 Security layer
The Payments Building Block must provide a security layer which protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication.
### 4.15 Bulk payment service
The Payments Building Block must provide bulk payment services. This bulk payment service is invoked in the case of G2P bulk disbursement.
# 5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
## 5.1 Requirements
## 5.1.1 External Identification, Registration, and Enrollment Logic (REQUIRED)
The Payments Building Block assumes that all identification, registration, and enrollment logic is done externally and are compliant with regulated payments and banking systems within a jurisdiction.
## 5.1.2 Registration Requirements (RECOMMENDED)
The Payment System or Scheme in a country may require that participating payor or payee entities, whether health clinics, ministries, or individuals must have been registered with a regulated banking or non-banking entity prior to the use of the Payments Building Block.
## 5.1.3 Compliance Verification (OPTIONAL)
In the context of Central Bank Digital Currency or Central Bank Accounts for individuals, the payment system block would assume that the regulatory conditions must have been verified for compliance and that payor and payee entities must have been properly registered according to the rules in that scheme.
## 5.1.4 Statutory and Operational Requirements (REQUIRED)
The Payments Building Block assumes that the statutory and operational requirements around accounts (i.e. know your customer/anti-money laundering/counter-terrorist financing) must have been completed by an outside system, which is capable of communicating that status in appropriate timeframes.
## 5.1.5 Real-time Response (RECOMMENDED)
The Payments Building Block assumes that the capabilities of the underlying infrastructure must enable transactions to meet a predefined limit to turn-around-time in real-time response.
## 5.1.6 Validation (REQUIRED)
The Payments Building Block should have the ability to validate against a set of external systems for the status of an account, account address and routing information, confirmation of payment, and various error conditions of accounts and specific payments.
## 5.1.7 Authorization (RECOMMENDED)
During operation in certain modes, the Payments Block would be validating against authorizations/releases or allotments provided by the treasury systems for the source of funds.
## 5.1.8 Eligibility Verification (RECOMMENDED)
Normally, verification of eligibility of beneficiaries for the service should be done in another Block.
## 5.1.9 Budget Availability (REQUIRED)
Budget availability must be checked before voucher creation is requested.
## 5.1.10 Calculation of Payments (OPTIONAL)
Calculations of payments may depend on several attributes laid down by a specific program.
## 5.1.11 Payment Systems (REQUIRED)
Payment systems in the market, either provided by a public entity, a quasi-public entity, or a purely commercial player, are required for the functioning of this Building Block.
## 5.1.12 Settlement (REQUIRED)
Settlement (gross or net) must be handled externally to this Building Block.
## 5.1.13 Security (REQUIRED)
The Payments Building Block must meet the security requirements described in the Security Building Block.
## 5.1.14 API Mechanisms (REQUIRED)
The Payments Building Block should meet the mechanisms for consuming and publishing APIs as described in the Information Mediator Building Block.
## 5.1.15 Architecture (REQUIRED)
The Payments Building Block must meet the requirements described in the Architecture Building Block.
## 5.2 Infrastructure Requirements
### 5.2.1 Mobile Money
Infrastructure Components:
* Account lookup - directory service.
* Payment portal.
* Payment gateway (only in selected scenarios).
* Payment request initiation.
* Notification service.
Mobile money is a destination account to distribute funds to end users (in the case of G2P) or an initiation account to enable users to initiate a payment for government services (P2G) which is facilitated by private commercial entities, typically Mobile Network Operators.
There are three ways that facilitate interoperability between a mobile money provider and a financial service institution (which could be the initiator of a payment - G2P or the receive - P2G): Through a Switch, through a third-party aggregator or through a bilateral integration. We expect one or multiple of these components to be in place to facilitate the use cases discussed in this document but these will remain out of the Payment Building Block.
### 5.2.2 Vouchers
Infrastructure Components:
* Voucher Management System.
* Merchant Ecosystem.
* Merchant Registry.
The Merchant Ecosystem and the Merchant Registry are both outside the scope of the Payments Building Block. The development of the Merchant Ecosystem will be driven by the relevant government institution. The Merchant Registry will be managed by another Building Block.
## 5.3 Payments Building Block Technical Requirements
Requirement
Type (Must/Should/May)
Secure API exposure: All APIs exposed via secure socket connections (HTTPS).
MUST
Client application authorization tokens: Client applications must send authorization tokens in the authorization header of the request to authenticate users and the API Management Gateway will verify whether the token is valid.
MUST
Transaction receipting: For each disbursement made by the system, a receipt should be issued to the recipient of the funds containing information about the transaction id, transaction date and time, reason for the payment, details of the payor, and the system should store all receipts issued for easy reference and reconciliation.
MUST
Transaction status querying capability
MUST
Display details of the transaction to the payer
MUST
Transaction pre approval: Prior to processing bulk payment and batch payment transactions, the transaction must be authorized and approved in the system.
MUST
Pre-processing validation of data (well formed data and completeness checks) prior to disbursement.
MUST
Ability to schedule bulk payments
MUST
Support for batch payments
MUST
Ability to lookup payment addresses
SHOULD
Error handling and reconciliation
MUST
Transaction status logging
MUST
Triggering of payments
MUST
Voucher Management
Batch generation of vouchers
MUST
Voucher uniqueness and randomness: Voucher pin must be unique and unpredictable.
MUST
Secure voucher data storage
MUST
High availability of storage
MUST
Expose APIs that can be invoked by voucher serial number for purposes of querying a voucher, suspending, or unsuspending a voucher.
MUST
Support an API that can be invoked to redeem a voucher using the voucher number.
MUST
Support an API that can invoke payment gateway
MUST
Mobile Payments
Real time debiting/crediting of mobile money accounts
SHOULD
Regular balance reconciliation with disbursement Agency
MUST
Documented process for partners to dispute transaction records
MUST
Target account identifier or lookup of payment address
MUST
Ability to retrieve details of completed transactions in the batch
MUST
Bulk Payments
Ability to securely receive bulk payment requests as a single HTTPS request containing data for multiple transactions. The transaction data (with payment instructions data) is passed format and will be compatible with ISO 20022.
MUST
The number of transactions that can be included in a single batch is limited by the size of the file upload and the processing time. If the number of transactions in the file exceeds the file size and could impact the performance of the system, the batch should be split into multiple batch requests.
MUST
Batch files should be verified for any errors and validated as per business rules and regulations before it is accepted as a valid bulk payment file.
MUST
Batch files containing duplicate payments will not be processed and an error will be generated.
MUST
The bulk payment process has to be explicitly triggered by an authorized user. All requests to the Bulk Payment Application API must be authorized and digitally signed by the person initiating the bulk payment request.
MUST
The batch file for bulk payments should contain the beneficiary ID token, and the amount to be paid. The payment information is not included in the batch file for security and privacy but is resolved by the verification and validation component of the bulk payment service by invoking the Account Lookup Directory Service (ALDS/ALS).
MUST
The Bulk Payment Application API shall inspect the batch disbursement file and split transactions into bank payments and non-bank payments (e.g. Mobile money) in separate payment files before initiating the call to the Payment Gateway.
MUST
The status of the bulk payment transaction can be obtained from the event log. The payment status code indicates the status of a single payment transaction and will be according to ISO 20022 Payment status codes table.
MUST
## 5.4 Standards
The following standards are applicable to data structures in the Payments Building Block:
# 6 Functional Requirements
This section lists the technical capabilities of this Building Block.
## 6.1 Payment Orchestration
Payment orchestration is an overarching concern which relates different sub-components or microservices whereby it:
* Explicitly defines and models workflows that span multiple microservices (REQUIRED)
* Provides detailed visibility into how a workflow is performing and identifying where there are issues (REQUIRED)
* Ensure that within a defined workflow, all workflow instances are completed according to plan, even when there are issues along the way (REQUIRED)
Payments orchestration is used to configure the Payments Building Block functionalities to be exercised during a specific workflow and provides functionality such as:
* Sending receipts, notifications, and acknowledgement of receipts in a secure manner to payers and other external applications to receive confirmation of payment made and safekeeping of a record of the receipt that was sent (REQUIRED)
* Provides for auditability of the Payments Building Block to have its controls evaluated for effectiveness, efficiency, and security, including tracing transactions, identifying users who access the system, clearly defined system controls, and compliance with local regulations and global best practices (REQUIRED)
* Schedule and aggregate payments to individuals, allowing programs to stagger payments or combine them with other payments to the same groups of individuals (REQUIRED)
* Enable payment confirmation through secure receipts, notifications, and acknowledgement of receipts to payers and other external applications (REQUIRED)
* Store event logs and audit trails for all transactions processed and their outcomes for monitoring and audit purposes (REQUIRED)
* Validate data structures and content to ensure that it is not missing key pieces of information, including verifying the destination account and triggering a different process if the account is not in good status (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed with throttling to reduce the flow of payment initiated (REQUIRED)
* Coordinate or orchestrate the validation, verification, batching, and scheduling using a set of rules, including options for kicking back to the operator for review or resubmission in certain error cases (REQUIRED)
* Generate reconciliation of accounts based on the successful sending of funds into accounts and reports to show the additional status of systems and payment types and timings (REQUIRED)
* Manage fees in a centralized way and support the use of digital channels to/from end-users, regulated account systems with payment signalling, and notifications by the Financial Services Provider enablers (REQUIRED)
* Scale on transaction performance, transaction latency, reliability, resilience, and graceful service degradation (REQUIRED)
* Support digital tools for query management, including beneficiary queries and complaints about payment services (REQUIRED)
* Route bulk payments through the account holding the funds, either at the government Treasury or a commercial bank (REQUIRED)
* Release funds by the Ministry or payroll master after appropriate approvals (REQUIRED)
* Handle processing and orchestration of bulk payments, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions (REQUIRED)
* Validate data structures and content to ensure that key information is not missing (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed (REQUIRED)
* Generate reconciliation of accounts based on successful sending of funds into accounts (REQUIRED)
* Provision, issue, activate, and redeem vouchers to support G2P beneficiary payments (REQUIRED)
* Ensure that adequate funds have been allocated to the voucher during provisioning (REQUIRED)
* Allow issuance of vouchers but make them unusable until they are in the hands of the beneficiary (REQUIRED)
* Activate vouchers to make them usable for predefined use cases and for a certain period of time (REQUIRED)
* Handle redemption of vouchers so that beneficiaries receive appropriate benefits from third parties (REQUIRED)
* Generate reports that show the vouchers in their different states as well as the aggregate quantity "stock", which triggers requests for "re-stocking" of vouchers (REQUIRED)
* Authenticate beneficiaries at the point of redemption by checking the Digital Registries Building Block to authenticate the user (REQUIRED)
* Cater for the distribution of social service transfers electronically and cash safely to end users (in the case where the user does not want to use electronic payments it is recommended that vouchers are used) (REQUIRED)
* Creates eVouchers to disburse financial subsidies in a controlled and safe manner (REQUIRED)
* Responds to payers to provide information about the status of the payments (e.g. confirmation of payment, insufficient balance or a mismatch in credentials, transfer failure, etc.), based on the status in the backend applications (REQUIRED)
* Posts status of transactions with traceability information into transaction logs (REQUIRED)
* Tracks due payment and sent payment notifications through alerting mechanisms, along with associated information (REQUIRED)
* Receives triggers for payment collection, posts the amount with relevant disclaimers to the payer, and obtains payer approval (REQUIRED)
* Securely posts the approval, user ID, and associated payment information to the appropriate backend (e.g. mobile, debit/credit card, internet banking entities) of relevant financial applications from banks, employers, and insurance; awaits transfer confirmation from those applications (REQUIRED)
* Searches and provides a logged information-based query of other applications (REQUIRED)
* Able to handle operations in remote and inaccessible locations (REQUIRED)
## 6.2 Voucher Management
The voucher management system is responsible for prectivation, storage, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
### **6.2.1 Voucher Provisioning**
This process traditionally involves the generation of group vouchers against some authorized value (budget release or allotment).
* Each voucher should have a unique secret voucher number, a unique identification number (voucher serial number) indicating its position in an inventory of pre-activated ~~issued~~ vouchers, and is linked to a fixed amount of value in a particular currency. Vouchers will also be associated with a voucher group during ~~provisioning~~ pre-activation. Voucher serial numbers will be unique across currencies should there be vouchers of multiple currencies.
* The vouchers should be created with an expiry date and MUST be stored securely. All vouchers will be expected to have the same duration of expiry and this expiry period will be from the moment the voucher is activated.
* Alternative design options include dynamically pre-activating a voucher at transaction time and creating variable amounts, but this increases complexity and requires tighter operational controls.
### **6.2.2 Voucher Issuance**
This process involves the Registration Building Block (or any other Building Block for that matter) requesting a voucher number from the voucher management system through an API.
* Once confirmation is received that the voucher has been released it flags the voucher as activated. Design decisions include making this step optional. Having an additional step increases security by ensuring that the voucher is not used until it is in the hands of the beneficiary (RECOMMENDED)
* Once a voucher has been issued by the calling Building Block (Registration Building Block) it will be presented to the beneficiary in a form that is determined by the calling Building Block (refer to voucher workflow). The format of the final voucher presentation will be determined by the function of the calling Building Block. At a minimum, this presentation should have the voucher number as well as the voucher serial number. it could also have the details of the beneficiary, which when placed on the voucher presentation, will help the merchant authenticate the beneficiary at the point of redemption (REQUIRED)
### **6.2.3 Voucher Redemption**
* In the redemption process, the merchant will authenticate the beneficiary and use a predefined technology (Unstructured Supplementary Service Data, Mobile App, Web Browser) to extract the voucher number and call a redemption API through the relevant calling Building Block. The calling Building Block may also validate the beneficiary details if so required. The Building Block will also be able to validate the merchant and determine the voucher group to which the merchant belongs. Lastly, the calling Building Block will invoke the Payment Building Block Redeem API, through the Payments Building Block API Management gateway, to validate the voucher and if valid to redeem it (REQUIRED)
* Once the voucher is validated, the Voucher Management System should invoke an API on the Payment Gateway to effect the payment in the merchant or agent wallet or bank account (depending on what was set up at merchant/agent registration). The payment gateway/switch will debit a pre-funded account/wallet and credit the merchant/agent account/wallet. The successful execution will result in the voucher being flagged as consumed/used (REQUIRED)
### 6.2.4 Voucher Management System (VMS) API interface
The details of the VMS APIs are described in the Service API section.
The VMS functionality can be accessed by four external APIs:
* **Voucher preactivate**: An API call to pre-activate the voucher and get a voucher number, a voucher serial number, and an expiry date.
* **Voucher activate**: An API call to activate the vouchers by serial number.
* **Voucher validity**: An API call to check the validity of a voucher by serial number.
* **Voucher redeem**: An API to redeem the voucher by voucher number.
The API interface should provide a minimum of five internal API calls.
* Voucher preactivation: An API to pre-activate the voucher and get a voucher number, a voucher serial number, and an expiry date.
* Voucher activation: A call to activate the voucher, by serial number.
* Voucher validity:
* A call to check the validity of the voucher by serial number.
* A call to check the validity of the voucher by voucher number and group.
* Voucher consumption: A call to consume the voucher by voucher number.
### 6.2.5 Voucher Storage
The voucher management server shall have a storage subsystem to store the vouchers.
* Vouchers must be stored in secure but high-performance data storage (read access will marginally exceed write access) (REQUIRED)
* The storage of the voucher number will require encryption of data at rest and in motion (unless the channel is encrypted) (REQUIRED)
* Logs generated should NEVER contain the voucher numbers (REQUIRED)
* All access to the voucher database must be logged (REQUIRED)
* Segregation of duty must be done with respect to privileged access to the database and key management of the encryption of the voucher (the level of key management may need to be determined) (REQUIRED)
## 6.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
The account lookup directory service provides a directory that maps the beneficiary's unique identifier (which matches the record in the social registry system) to the transaction account where the beneficiary wishes to receive their G2P payment, allowing the government to address payments to a specific individual. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases. The information will be kept in a tokenised form in the account lookup directory service.
In the case where there is a national payment switch, the account lookup directory service will be maintained by the FSPs, In the scenario, where there is no payment switch, the government would need to manage the account lookup directory service and provide a mechanism for linking it to the FSPs.
## 6.4 Payment Request Initiation
* A request can come from either internal or external sources (REQUIRED)
* An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll). Either source must be appropriately authenticated and authorized to initiate the request.
* The initiation can be synchronous (typically for a single payment) or asynchronous (typically for batch payments) (REQUIRED)
* The request must contain at a minimum: the payer identifier, the payee identifier, the amount, the currency, the policy, and the initiating source’s unique transaction ID. In the case of the internal payment request, it should also contain an ID provided by the payment orchestration module (REQUIRED)
* Certain processes in the transaction flow might require proof of intent from the user, for example, entering the PIN/Password or pressing an ’accept‘ key to initiate the payment process. Such events and their outcomes should be recorded for audit trail purposes. However, the PINs and passwords should not be stored in logs or if they have to, PINs and passwords should be hashed out (RECOMMENDED)
## 6.5 Payment Gateway
A payment gateway allows different (digital) Financial Service Providers (FSPs) to:
* Interconnect and exchange information (REQUIRED)
* Initiate and receive transactions (REQUIRED)
* Accept or reject transactions and debit or credit end-user accounts (REQUIRED)
## 6.6 Payment Portal (RECOMMENDED)
The payment portal will:
* Enable government payers (departments/ministries/public sector bodies) to make G2P payments through one or multiple FSP/payment service providers (REQUIRED)
* Focus on managing, sending, and reconciling payments (REQUIRED)
* Connect government agencies to sending and recipient institutions (REQUIRED)
* Coordinates sending/receiving of payment requests, and approvals (REQUIRED)
* Provide reports across G2P programs, FSPs, and beneficiaries (RECOMMENDED)
* Track payment status and payment history (REQUIRED)
* Register FSPs who are entitled to process payments for G2P payments (REQUIRED)
* Provide restricted access to authorized FSPs to connect to the portal, to process the payments for beneficiaries who are their customers (REQUIRED)
* Automate reconciliation (RECOMMENDED)
* Provide data analytics on payments processed and their status, whether successful or not (REQUIRED)
## 6.7 Event Management
This functionality supports different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
All notification events shall have a timestamp associated with them and be kept as part of the audit log.
## 6.8 Reconciliation (RECOMMENDED)
This should happen at two levels: internally and externally.
* The internal reconciliation will occur between the different sub-blocks within the Payments Building Blocks. In order to achieve internal reconciliation the internal payment request initiator should issue a unique ID that will be referenced by subsequent Payments Building Blocks in all future calls related to the particular payment. This will allow end-to-end tracing of the transaction within the Payments Building Blocks (REQUIRED)
* The external reconciliation is more complex as it involves a calling Building Block which is outside the Payments Building Blocks (such as the Registration Building Block) and a third party (e.g. DFS). Ideally, there needs to be a sequence of IDs that can identify a transaction from start to finish (REQUIRED)
* Cross-cutting Prerequisites for reconciliation:
* The nodes that are under the control of the GovStack should be time synched (REQUIRED)
* IDs should be unique, if possible contain the timestamp, and should not roll over across short ranges (REQUIRED)
* Transactions are expected to be irrevocable. Transaction reversals are subject to local regulations. In some countries, a transaction is revoked/clawed back if the beneficiary has not withdrawn the payment within a certain time period. Good practice, from a financial inclusion perspective, is to not claw back. The beneficiary could use this money as savings when needed. The system should allow both configurations (REQUIRED)
## 6.9 Batch Processing (RECOMMENDED)
* Prepares the batch breakdown on the basis of rulesets governing: which Financial Services Providers shall receive, which payments, and other considerations (REQUIRED)
* Combines payments with other payments to the same beneficiary (REQUIRED)
* Detects batch failure rates (REQUIRED)
Batch files go through a final check to be clean of defects and inconsistencies, to check with external systems as necessary:
* At high volumes, batches are queued for processing (REQUIRED)
* Low-level validation of data types and data completeness (REQUIRED)
* Verification of lookup of accounts to ensure that the account information matches the destination system expectation (REQUIRED)
* Check for inconsistencies (REQUIRED)
* Auto-correct items as possible - consistency logic can be applied to fill in missing formatting if required by recipient banks and telecoms (REQUIRED)
* Errors are kicked back to program level or to an internal data review process (REQUIRED)
## 6.10 Scheduling Services
* In relation to batch logic, payments are scheduled against the availability of systems, throughput limitations, and rules set by programs (REQUIRED)
* Regular and repeat payments are scheduled (REQUIRED)
* Batches may be given prioritization in the queue (REQUIRED)
* Essential control logic may be included here, specific to the individual batch sending and resending (REQUIRED)
* Availability of funds in different budget accounts may be incorporated into this process (REQUIRED)
* Additional workflow checks as required, including the resending of failed transactions (REQUIRED)
## 6.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
* Application or event logs will capture events that each component performs and should contain at least the following information (REQUIRED):
* application/user ID
* event date and time
* terminal identity (name and/or IP address)
* event-related information (message or code)
* event success or failure
* The components should also generate transaction logs that capture at least the following information (REQUIRED):
* transaction date and time
* transaction source
* transaction destination
* supplementary data
* transaction status (success, failed, in progress)
* The event logs and the transaction logs should NOT capture any sensitive data such as voucher numbers, passwords, etc. (REQUIRED)
* There should be an individual transaction record for every payment transaction. For example, if a batch payment process is executed there should be a transaction record for each individual transaction and a separate event log for the entire batch (RECOMMENDED)
## 6.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
* Must be automatically captured by the computer system whenever a payment request is created, modified, or deleted (REQUIRED)
* Must be stored in a secure manner and must not be editable by any user, including privileged users. A common approach is to copy/redirect logging to a separate logging server (REQUIRED)
* Each audit trail entry must be time-stamped according to a controlled clock which cannot be altered. The time should either be based on central server time or a local time, so long as it is clear in which time zone the entry was performed (REQUIRED)
* Each audit trail entry must be traceable, i.e. attributable to the individual responsible for the direct data input. Updates made to data records must not obscure previous values and where required by regulation the reason for changing the data must also be recorded (REQUIRED)
* The audit trail must be retained as long as the electronic record is legally required to be stored (REQUIRED)
* The audit trail must be available for internal review/audit (REQUIRED)
* The auditing system must be self-sufficient, i.e. for auditing/regulatory purposes the information stored by a BC must be enough (REQUIRED)
* Audit entries cannot be changed, i.e. the audit BC persisted store should be immutable, and should only support append and not changes or deletes (REQUIRED)
* Audit entries should have a pair of fields to store encrypted data and the encryption key id - these are provided by the submitting BCs (REQUIRED)
* Querying capabilities (REQUIRED):
* Auditor wants to see all activity in the last X days.
* Auditor wants to see all activity of action type Y, or from a certain BC.
* Auditor should be able to request the decryption of encrypted data to an operator.
* Access to the audit store must be securable, so whatever tech is chosen must implement access control mechanisms (ideally that can connect to our Identity and Access Management provider/connector) (REQUIRED)
## 6.13 Reporting Services
* The data store will be write-only from the core service and should be read-only by external components (RECOMMENDED)
* The data model on the reporting data store can be different from the internal operational data models that the switch uses (RECOMMENDED)
* The component provided by the switch will be translating internal events and internal data models to the external data store models. This component can be replaced (RECOMMENDED)
## 6.14 Security layer
Protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication. The digital signatures are based on public key cryptography using X.509 digital certificates.
At the transport layer:
* All communication between building blocks must use secure protocols to protect the confidentiality and integrity of the data in transit (REQUIRED)
* Strong authentication for parties involved in the transactions should be supported (REQUIRED)
* Confidentiality of personal information related to the transaction – Information on account data, transaction data, payment credentials, and users’/payee’ personal profiles must never be disclosed to any unauthorized party (REQUIRED)
* Non-repudiation of transactions by parties involved (REQUIRED)
* Acknowledgement receipt: this will result in creating a trusted communication path for all transactions between each party, by the end users, telecommunication companies, merchants, or banks (REQUIRED)
* The messages concerning the payment transaction shall be authenticated (REQUIRED)
## 6.15 Data Protection
Use of a hardware security module (HSM) or equivalent to provide cryptographic keys for critical functions such as encryption, decryption, and authentication for the use of applications, identities, and databases.
## 6.16 Bulk payment service (RECOMMENDED)
The bulk payment service is invoked in the case of G2P bulk disbursement and should provide the following functionality:
### 6.16.1 G2P Bulk disbursement (REQUIRED)
The following are the prerequisites required before bulk payments can be initiated:
A) Funding requirements
* The funding requirements must operate within the budget/ceiling.
* The number of funding accounts and the life cycle processes will vary depending on the payment infrastructure scenarios.
B) Bulk payments file
* For the salary payments use case, this would be generated by the payroll system.
* For the unconditional social cash transfer use case, this would be generated by a process that would be triggered as per a pre-agreed frequency and the information about the payments to be made would be extracted from the registry (a database containing the information about beneficiaries for a particular government social cash transfer programme). The process of generating this payments file is outside the Payments Building Block.
There are three options for the disbursement:
* Manual process for Government/Department to send the retail payment details to each Financial Services Provider (FSP) (i.e. either by email or other means). This would be the case where there is a lack of interoperability among FSPs.
* Upload the batch disbursement file in the payment web portal for each FSP to retrieve in the case of a centralised Account Lookup Directory Service.
* Automate the disbursement process through the decentralised Account Lookup Directory Service and the payment gateway.
**Option 1**: Retail payment information is sent securely to each Payment Service Provider for disbursement
**Option 2**: Retail payments are accessed via a payment web portal by the Payment Service Provider. The advice/electronic fund transfer request, or paper-based check is issued from the Financial Management Information System to the Trusted Single Account (TSA) -holding Bank.\
Based on this advice, the Bank disburses funds from the TSA into the digital payments system of the FSP which transfers the corresponding funds to the recipient’s account. For the retail payment scrolls, where each agency is responsible for running the payment system - payroll, social welfare payments, etc. - the payment details are not stored in those systems. Instead, the beneficiary’s payment token is retrieved from the Centralised Account Lookup Directory Service and kept in the government payment portal. The payment lists are only shared with the program account holder institution/FSP, Payment Service Provider (PSP), via the government payment portal. The FSP/PSP can log in on the government web portal to access the directory for payments that the FSP needs to effect for each G2P Program.
**Option 3**: Similar to option 2 but the disbursement process to the beneficiary is routed automatically through the payment gateway using the payment token retrieved from the decentralised account lookup directory service.
Bulk payments require the functionality of a Payments Gateway and the functionality therein. It also assumes a separate mechanism by which the recipient account address is determined. In the figure below the “account lookup directory service” functionality maps the concept of identity to the payment alias and from there to the Financial Services Provider routing address. (i.e. wallet address or account address)
### **6.16.2 Interaction with Other Building Blocks (REQUIRED)**
The diagram below shows the interaction with the registries Building Blocks.
At a high level, the payment components used for bulk payments are shown in the figure below.
Figure: Key digital requirements of Bulk Payments expressed as a high-level block diagram. Dotted line for required components.
### 6.17 P2G Bill payments
The Billing ecosystem would consist of various actors performing core and secondary processes to complete the bill payment function. Some of the actors only play an auxiliary role to enable bill payment.
**Payments Building Block**
* Main payments facilitator enabling exchange of all financial and non-financial messages related to: Biller/Aggregator Registration o Bill discovery o Bill Payment Confirmation messages
* Biller Discovery through internally referring to the Billers Table updated by PBB Billing sub-Module
* Generation of transaction/ activity reports for registered Billers/ Aggregators
* Registration of Billers in the system
* Allocation of unique Biller IDs / Prefixes
**Billers Table**
* Database of all registered billers
* Internally referenced by the Payments BB each time a Bill Inquiry comes in
* Returns the endpoints for the registered biller/ aggregators
* Biller Details and Account Details from this table would be shared with the Payer FIs during Payments BB and Payer FSP linking for Bill Payments.
**Billers/ Aggregators**
* Getting registered at the PBB – Bill Payment Service
* Returning the correct Bill Details against the Bill Inquiries received from PBB
* Marking the Bills as “Paid” upon receiving Payment confirmation from PBB
* \[Out of Scope of PBB] Performing Bill validation and Bill discovery in their system
**Payer FIs**
* Sending Bill inquiry Requests
* Sending Bill Payment Confirmation
* \[Out of Scope of PBB] Customer validation and Payment debit
## 6.17 Payments Building Block Components
The following components are needed to achieve the technical functionalities of the Payments Building Block.
Many of the components outlined above are used to deliver the Functional Requirements for the Payments Building Block. Components which are not directly related to the delivery of these functions are described here:
### 6.17.1 API Management Gateway
The Payment Building Block provides an API Gateway to handle all the API messaging calls and API access control verification from other Building Blocks to the Payments Building Block and vice versa as well as within the Payments Building Block. All requests from other Building Blocks first go through the API gateway. The gateway then routes requests to the appropriate application/service.
The API Management gateway will:
* Use Identity and access management for authentication.
* Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats.
* Require authentication for all API users.
* Manage access quotas and throttling.
* Log all API calls.
* Allow API providers to limit the rate of consumption for all API users.
* Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.
# 7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
### 7.1 Account Mapper
**Beneficiary onboarding**
Field
Type
M/O
Description
requestID
String (12)
M
Globally unique ID
beneficiaries
Object
JSON Array
payeeIdentity
String (20)
M
The functional Id of the beneficiary.
paymentModality
String (2)
O
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
bankingInstitutionCode(BBIC)
String (11)
C
Beneficiary Bank Institution code that will receive the address. This is conditional as it will only be present in case of bank account, mobile money account and digital wallet ID
financialAddress
String (30)
O
Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
**Onboarded beneficiary**
Field
Type
M/O
Description
requestID
String (12)
M
Globally unique ID
registerRequestID
String (12)
M
Referenced GUID of original request by Source BB to register a beneficiary.
rumberFailedCases
Number
M
The number of cases failed. 0 if none, otherwise integer value
failedCases
Object
O
JSON Array containing the list of FunctionalIDs and Payment Modalities that were not updated in the ID Mapper.
payeeIdentity
String (20)
M
The functional Id of the beneficiary.
bankingInstitutionCode
String (11)
C
Beneficiary Bank Institution Code (BBIC).The beneficiary bank institution code. This is conditional as it will only be present in case of bank account, mobile money account and digital wallet ID
paymentModality
String (2)
M
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
failureReason
String(100)
O
Description of why this particular record failed to add
The relevant bill details including biller ID, Name, Bank Institutional Code (BIC), Status, Amount with due date and after due date
billerId
String (10)
M
Biller Id
billerName
String (10)
M
Biller Name
billStatus
String (10)
M
Informs the status whether paid or unpaid
dueDate
Epoch
M
amountonDueDate
Integer
C
The amount at which the consumer needs to pay bill with due date.
amountAfterDueDate
Integer
C
Amount calculated after due date.
**Billers table**
The Biller Table may need to include the following fields:
| Fields/ Records | Description | Provided/ Generated By |
| --------------- | -------------------------------------------------------------- | ---------------------------------------- |
| Unique ID | Prefix allocated to every entity directly registering with PBB | PBB Billing Module |
| Biller Details | Records Biller Details | Biller/ Aggregator |
| Biller FSP | Recorded Biller’s Bank Details | Biller/ Aggregator |
| Bill ID Details | Maximum number of Digits in Bill ID | Biller/ Aggregator |
| Biller Status | Active/ Inactive | PBB Billing Module |
| End-Points | Addresses to send requests | Biller/ Aggregator Technology Partner |
| Response Codes | Mapping of codes received and sent to Billers/ Agg. | PBB Billing Module + Biller Tech Partner |
# 8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
The [GovStack non-functional requirements document](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.
The tests for the Payments Building Block can be found in [this GitHub repository](https://github.com/GovStackWorkingGroup/bb-payments/tree/main/test/openAPI).
# 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://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-1c328d746bd61660b255a7e8c90ee5d9befd708b%2FRegisterBeneficiaryRequest.yml?alt=media)
{% 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://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-ba63bb50f5d2d369689d1b09f58bce05953f67e0%2FRegisterBeneficiaryResponse.yml?alt=media)
{% 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://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-bf1521820cdafc5cc118b8dd6f646d94c587484c%2FUpdateBeneficiaryRequest.yml?alt=media)
{% 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://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-601d8307797a4f8660bce79a7dfdbcbc9989926b%2FUpdateBeneficiaryResponse.yml?alt=media)
{% 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://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fd6bMx7fuLxOdoXFJY6UB%2Fv1_0_1_fixed_BulkPayment.yml?alt=media\&token=cbd69265-bc9d-49ce-a846-971b308e7edc)
{% 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.
# 8.2 Voucher Management APIs
The first API in the section below is used to request for a voucher with a specific value, currency, and purpose. The server responds with a voucher number, serial number, and expiry date. The second call activates the pre-activated voucher. The third call processes voucher redemption, crediting the merchant if valid. The fourth APIs allow for voucher status checks.
### 8.2.1 VoucherPreActivation
#### a) VoucherPreActivation()
The VoucherPreActivation API is used by non-Payment Building Blocks in the GovStack Framework to request for a voucher to be used. This call reserves the voucher (for a period, which is to be implemented). This API requests a single voucher from the voucher server that can be used for a future redemption process. The caller sends an amount, a voucher group (depending on the use case), the currency, and the name of the calling GovStack Building Block. If the API call is successful, the Payment Building Block will respond with a voucher number, a voucher serial number, and an expiry date.
{% openapi src="/files/akKaWsoHkYroeiiaezPy" path="/vouchers" method="post" %}
[VoucherPreactivationRequest.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-7382d9a0ff52ed9101be397a76cc8cb9458c1354%2FVoucherPreactivationRequest.yml?alt=media)
{% endopenapi %}
**b) Create\_Vouchers\_Response()**
Description This is the API called by the Voucher Engine to return Voucher Details once vouchers have been created in the Voucher Engine.
{% openapi src="/files/kymL9dFqJRQwqj2ZbVnb" path="/voucher-details-return" method="post" %}
[VoucherCreationResponse.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-ae91711067fcaf2bcc61b505493efe6b74a311aa%2FVoucherCreationResponse.yml?alt=media)
{% endopenapi %}
### 8.2.2 VoucherActivation
#### a) Voucher\_Activation()
The VoucherActivation API is used by non-Payments Building Blocks in the GovStack Framework to activate a pre-activated voucher. This second function call is intended to ensure that the voucher is only activated when it is disbursed. This API requests for the activation of a voucher when the caller sends the voucher number to be activated. If the API call is successful, the activation is confirmed, and the voucher can now be used by the beneficiary.
{% openapi src="/files/hNbVGyfbAq5Qp2treCMB" path="/vouchers" method="put" %}
[VoucherActivate.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-2e16000e9e5e3e8d61f486716ea2cb8fb6344aa5%2FVoucherActivate.yml?alt=media)
{% endopenapi %}
For Batch voucher activation, the voucher activation APIS is used by calling Building Block to activate vouchers in bulk. This may be used for bulk social cash transfers where the recipients receive benefits by vouchers. The calling Building Block is responsible for generating the beneficiary file as well as dispensing the vouchers. The Payments Building Block is responsible for generating and redeeming the voucher codes. Both BBs will have had to have exchanged encryption keys during the implementation phase.
The file provided by the calling Building Block will typically contain a unique identifier, the amount of the voucher required, the currency of the voucher, and the voucher group. While the file format may vary, the recommended file format is an encrypted JSON file.
If the file is properly formatted, the Payments Building Block will respond with a file that contains the unique ID that was sent, the status, the voucher number, the voucher serial number, and the expiry date of the voucher. The response file will also be an encrypted file to ensure the appropriate security of the voucher number.
The calling building block will dispense the vouchers as needed using an appropriate delivery mechanism. The calling Building Block will also be responsible for any verification of the beneficiary during the redemption process. The description of the dispensing of the vouchers once the calling block has received it is outside the scope of the Payments Building Block.
**b) Voucher\_Activate\_Response()**
Description This is the response API called by the Voucher Engine to confirm the status of batch activation back to the calling BB.
{% openapi src="/files/gTJTFvsyMuUlN5puMwsg" path="/callback-url" method="post" %}
[VoucherActivateResponse.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-6736795e87631a3624f5d9277f208b58e79ae084%2FVoucherActivateResponse.yml?alt=media)
{% endopenapi %}
### 8.2.3 VoucherRedemption
The VoucherRedemption API is used by non-Payment Building Blocks in the GovStack Framework to redeem a voucher. The calling Building Block will capture the voucher number and the voucher serial number from the merchant point. The external Building Block will also acquire the merchant name and payment details from the merchant registry. The calling Building Block will then send the voucher number, the voucher serial number, the merchant’s name, and payment details. The Payment Building Block will verify that the voucher has been activated and has not been used or blocked or canceled. If so, the Payment Building Block will then send a payment request to the funding agency/Financial Services Provider. The Payment Gateway of the Payments Building Block will facilitate the debit of the funding account, and the credit of the merchant as well as handle any intermediary fees. Once the payment has been successfully done the Payment Building Block will mark the voucher as consumed and notify the merchant (and beneficiary if possible).
{% openapi src="/files/GUlYJ2URXiIPyTpg7MNa" path="/vouchers" method="post" %}
[VoucherRedemption.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-7c69707b4d6a2928d1c0002a110e2dfe37a13c25%2FVoucherRedemption.yml?alt=media)
{% endopenapi %}
### 8.2.4 VoucherStatus
The VoucherStatus API is used by non-Payment Building Blocks in the GovStack Framework to check the status of a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to determine the status of a voucher. The Payments Building Block will respond with one of the statuses of Pre-Activated, Activated, Suspended, Blocked, or Not Existing.
{% openapi src="/files/0B9qQSLnxFgYZKwvlVfd" path="/vouchers/{serialNumber}" method="get" %}
[VoucherStatus.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-81761343674de32b98debc63c97ca5f6e32a52cf%2FVoucherStatus.yml?alt=media)
{% endopenapi %}
### 8.2.5 VoucherCancellation
**Voucher\_Cancellation()**
Description This API will be called by the Source-BB to update the status of the voucher(s), in the case of cancellation, the status code 03 is sent to the relevant field of the instruction array.
The VoucherCancellation API is used by non-Payments Building Blocks in the GovStack Framework to cancel a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to cancel the voucher.
{% openapi src="/files/IUXMve3eLkypdGI3B2vz" path="/vouchers" method="post" %}
[VoucherCancellation.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-98ae0649dbcf9e05ff81154f20ab6b6d8ba72204%2FVoucherCancellation.yml?alt=media)
{% endopenapi %}
***
**Voucher\_ Cancellation\_Response()**
Description Response API called by the Voucher Engine to confirm the cancellation of the voucher. The Payments Building Block will respond with a status of Cancelled, Already Cancelled, or Not Existing. The Voucher Cancellation will override the Blocked status and render the voucher permanently unusable.
{% openapi src="/files/eUVlXuWlhJvRaWpK2Spg" path="/vouchers/cancellation/confirmation" method="post" %}
[VoucherCancellationResponse.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-06d209dfb9ac6279d50319ebf2777c3e0d3219f6%2FVoucherCancellationResponse.yml?alt=media)
{% endopenapi %}
# 8.3 Person-to-Government APIs (P2G) Bill Payments
The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money and vouchers.
#### **8.3.1 billInquiryBiller**
This API is called to inquire about bill details from a Bill Aggregator or Govt Entity.
{% openapi src="/files/PansJNWk0m2kneSdMloT" path="/bills/{billId}" method="get" %}
[billInquiryRequest.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-debd1e06142237ee227e8a2f315c4daeea069cf3%2FbillInquiryRequest.yml?alt=media)
{% endopenapi %}
#### **8.3.2 billrInquiryResponse**
The Payment BB updates the Bill Aggregator or government entity on the status of the Request to Pay.
{% openapi src="/files/NJJFfQMZm4M3Mh0hWhPX" path="/bills/{billId}" method="post" %}
[billInquiryResponse.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-df259211ef8e5bff9ec0eeef5f18c50d6a0a967f%2FbillInquiryResponse.yml?alt=media)
{% endopenapi %}
#### **8.3.3 markBillPayment**
This API marks a bill as paid.
{% openapi src="/files/d9p4i8OugFALHuGESq2t" path="/billTransferRequests" method="post" %}
[markBillPpaymentRequest.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-066035ee1f560895486c6f82bb6456b93aebcf99%2FmarkBillPpaymentRequest.yml?alt=media)
{% endopenapi %}
#### **8.3.4 billerRtpReq**
The Bill Aggregator or Govt Entity initiates a “Request to Pay” (RTP) through this API.
{% openapi src="/files/i2cjhDNnY6iHRVGsHAVW" path="/billTransferRequests" method="post" %}
[markBillPpaymentResponse.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-3cf76f7bd2e65bd6eb3562b46dee433e0e545b00%2FmarkBillPpaymentResponse.yml?alt=media)
{% endopenapi %}
#### **8.3.5 billerRtpReq**
{% openapi src="/files/Ijrsl5MigugoM6A2XV4N" path="/rtpUpdate" method="post" %}
[billerRtpResponse.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-3583f1dce3230a0d763c91077be842457aa05196%2FbillerRtpResponse.yml?alt=media)
{% endopenapi %}
#### **8.3.6 rtpStatusUpdate**
This API allows the Biller or Aggregator to inquire about the status of its RTP.
{% openapi src="/files/P4TVnG2YVqyBlcRwRqtW" path="/transferRequests/{transferRequestId}" method="get" %}
[rtpStatusUpdateRequest.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-fedd9b7e3d4a4bf6632fec23b10603fbcc6d0452%2FrtpStatusUpdateRequest.yml?alt=media)
{% endopenapi %}
#### **8.3.7 rtpStatusUpdateResponse**
This API allows the Biller or Aggregator to receive the status of its RTP.
{% openapi src="/files/8vhgVuPX4Gnr4jkD75Dm" path="/transferRequests/{transferRequestId}" method="post" %}
[rtpStatusUpdateResponse.yml](https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-48a978a6775aca857fa8a4029efb6e9a10288da8%2FrtpStatusUpdateResponse.yml?alt=media)
{% endopenapi %}
# 9 Internal Workflows
This section provides a detailed view of how the Payments Building Block will interact with other Building Blocks to support payments.
## 9.1 G2P Bulk Payment Workflows
This section discusses the various processes involved in G2P disbursement, such as beneficiary onboarding into the Account Mapper, bulk disbursements to pre-registered financial addresses, and account pre-validation prior to bulk disbursement.
### 9.1.1 Beneficiary Onboarding in Account Mapper
The workflow represents the process of onboarding beneficiaries in the ID Mapper as a prerequisite step before any payment processing can occur. This use case is triggered when a new G2P beneficiary has been onboarded by a G2P program, assigned a Functional ID, and verified as eligible for the social benefit program.
{% @mermaid/diagram content="sequenceDiagram
note left of RBB: Functional ID is issued to Beneficiary, Request parameters can be json array for bulk onboarding
RBB -->> IM: Register\_Beneficiary (Request ID,\nSource BB ID, Array of Beneficiaries)
IM -->> PBB: Register\_Beneficiary (Request ID,\nSource BB ID, Array of Beneficiaries)
note left of PBB: Validate parameters, Authenticate Source Building block exists
PBB -->> AM: Register\_Beneficiary (Request ID,\nSource BB ID, Array of Beneficiaries)
note left of AM: For each Payee Functional ID, Duplicate Check, Register in mapper
AM -->> PBB: Register\_Beneficiary\_Respone(Request\_ID,\nResponse Code,Array of Failed cases)
PBB -->> IM: Register\_Beneficiary\_Respone(Request\_ID,\nResponse Code,Array of Failed cases)
IM -->> RBB: Register\_Beneficiary\_Respone(Request\_ID,\nResponse Code,Array of Failed cases)" %}
1. The Requesting Building Block (RBB) sends a "Register\_Beneficiary" request to the Information Mediator (IM), containing the Request ID, Source Building Block (SBB) ID, and an array of beneficiaries with their Functional ID, Payment Modality, and Financial Address (if available).
2. IM forwards the "Register\_Beneficiary" request to the Payments Building Block (PBB) with the same parameters.
3. PBB validates the API parameters and checks if the Source Building Block is configured in the Payments BB as an acceptable source of the API call.
4. If the parameters are valid, PBB sends the "Register\_Beneficiary" request to the Account Mapper (AM) with the same parameters.
5. Account Mapper checks for duplicate Functional IDs registered by the same Source Building Block and registers the beneficiaries in the mapper if they are not already registered.
6. Account Mapper sends a "Register\_Beneficiary\_Response" to PBB, which contains the Request ID, response code, and an array of failed cases (if any) with descriptions.
7. PBB forwards the "Register\_Beneficiary\_Response" to IM, with the same parameters.
8. Finally, IM sends the "Register\_Beneficiary\_Response" to RBB, providing the final response code and the list of any failed cases with descriptions.
The workflow supports the addition of beneficiaries in the mapper in bulk. The source building block can use the same APIs for individual or bulk onboarding.
### 9.1.2 Pre-validation of Accounts prior to Bulk Disbursement
This flow represents the prevalidation process of accounts in a bulk disbursement scenario. The process involves a Source BB (SBB), Payments BB (PBB), Payer Bank (PrBank), and Payee Bank (PyBank).
{% @mermaid/diagram content="sequenceDiagram
title Prevalidation of Accounts
note right of SBB: Prepare Bulk Disbursement instructions containing 1. FunctionalID 2. Amount 3. Description/Narration 4. Instruction ID
SBB -> PBB: Prepayment\_Validation(Batch\_ID, Payment Instructions)
note left of PBB: 1. Debulking 2. Check each Payee Functional ID in mapper 3. Record Failed Instructions
loop Send Payee Bank wise Sub-Batches
PBB -> PrBank: Bulk\_ValidateAccount (Batch\_ID, Destination\_BIC,Payment Instructions)
PrBank -> PyBank: Account Validation Request as per Incumbent Scheme Norm
note left of PyBank: 1. Validate A/C exists 2. Validate it can receive Credit 3. Validate Credit limit won't exhaust
PyBank -> PrBank: Account Validation Response as per Incumbent Scheme Norm
PrBank -> PBB: BulkValidateAccount\_Response (BatchID, Array of Failed Instructions)
end
PBB -> SBB: Prepayment\_Validation\_Response(BatchID, Array of Failed Instructions)
" %}
1. The process begins with the Source BB (SBB) preparing bulk disbursement instructions containing key information such as the Functional ID, amount, description/narration, and instruction ID.
2. SBB sends these instructions as a prepayment validation request (Prepayment\_Validation) to Payments BB (PBB).
3. Upon receiving the request, PBB performs several actions, including debulking the instructions, checking each payee's Functional ID in the mapper, and recording any failed instructions.
4. PBB then sends payee bank-wise sub-batches for validation in a loop. For each sub-batch, PBB sends a bulk validate account request (Bulk\_ValidateAccount) to the Payer Bank (PrBank), including the batch ID, destination BIC, and payment instructions.
5. PrBank forwards the account validation request to the Payee Bank (PyBank) as per the incumbent scheme norm.
6. PyBank performs several validation checks, such as confirming the account exists, verifying that it can receive credit, and ensuring that the credit limit won't be exhausted.
7. PyBank sends an account validation response back to PrBank, adhering to the incumbent scheme norm.
8. PrBank then sends a bulk validate account response (BulkValidateAccount\_Response) to PBB, containing the batch ID and an array of any failed instructions.
9. Finally, PBB sends a prepayment validation response (Prepayment\_Validation\_Response) to SBB, including the batch ID and an array of any failed instructions.
This flow ensures that the accounts involved in a bulk disbursement transaction are valid and capable of receiving the specified credits before processing payments, reducing the risk of failed transactions and improving overall efficiency.
### **9.1.3** Bulk Disbursement into a Financial Address pre-registered in the Account Mapper
The workflow depicted below illustrates the process of bulk disbursement into financial addresses, such as bank accounts or mobile wallets, that are pre-registered in the Account Mapper. This use case is triggered when the Source BB submits a batch for processing of payments to the Payments BB.
Pre-conditions: Functional IDs intended to be recipients of funds must be pre-registered in the Account Mapper. All the financial addresses must be validated before a payment is disbursed.
Data Inputs: Source BB provides relevant confirmation to the Payments BB to begin credit transfer for successfully pre-validated accounts.
{% @mermaid/diagram content="sequenceDiagram
title Bulk Disbursement into an online Financial Address
SBB ->> PBB: BulkPayment(Batch\_ID, Payment Instructions)
PBB ->> PrBank: getAuthorization()
PrBank ->> PBB: getAuthorization\_Response()
loop Send Payee Bank wise Sub-Batches
PBB ->> PrBank: BulkPayment\_ReceiverFI(Batch\_ID, Destination\_BIC, Payment Instructions)
end
note over PrBank: Payer Bank processes each Receiving FI Batch and processes instructions as batch or single instructions, depending on available transaction rails.
PrBank ->> PBB: BulkPayment\_StatusPush(BatchID, Credit Instructions)
" %}
1. The process starts with Source Building Block (SBB) sending a BulkPayment request containing a Batch\_ID and a set of payment instructions to the Payment Building Block (PBB).
2. PBB checks if liquidity was provisioned before this batch is executed and if sufficient liquidity was provisioned. If this is the case, PBB proceeds to de-bulk crediting batches by the receiving institution.
3. PBB then requests authorization from the PrBank by sending a getAuthorization() message.
4. PrBank responds with a getAuthorization\_Response() message, granting the required authorization to PBB.
5. PBB begins sending payee bank-wise sub-batches to PrBank in a loop. For each sub-batch, PBB sends a BulkPayment\_ReceiverFI message containing the Batch\_ID, Destination\_BIC, and payment instructions.
6. The Payer Bank (PrBank) executes these batches through existing rails.
Exceptions: Some accounts might have been pre-validated or part of the crediting batch but cannot be credited by the payee bank for some reason. For such accounts, funds must be returned to the payer bank and credited back into the Source BB's Settlement Account through a separate process.
In order to facilitate the transfer of funds from the disbursement organisation (the payer) to the mobile money provider, the mobile money provider would need to be connected to the payment gateway/switch. Should this connection not be in place, the disbursement could be facilitated by a third-party aggregator or there would need to be a bilateral connection between the payer’s Financial Service Provider and the Mobile Money Provider.
## 9.2 G2P Vouchers Payments
The Voucher Management System supports three workflows for voucher payments:
1. administration (voucher provisioning and merchant registration),
2. voucher issuing (pre-activation and activation),
3. redemption use cases as shown in the diagram below.
These use cases and the relationship between each one of them are shown and further described below.
The use cases are described in the diagram below:
{% @mermaid/diagram content="graph TD
Voucher\_provisioning --> Voucher\_Printing --> Merchant\_Redemption
Voucher\_Printing --> Agent\_Cashout
Merchant\_registration --> Merchant\_Redemption" %}
### **9.2.1 Voucher administration**
These processes are usually done prior to the issuance of the voucher to ensure a smooth flow at the point of issuance.
The Admin processes for the Voucher Management Server cover the lifecycle of the vouchers and are typically performed by a privileged user (this may be done through User Interface or an API). These processes include but are not limited to creating voucher groups, provisioning vouchers, suspending vouchers, unsuspending vouchers, validating vouchers, key management, and purging of used vouchers.
* Voucher Provisioning\
This function will be done by an administrator (privileged user). It will typically be triggered by the deposit of funds in a funding account, thus the source account. Voucher provisioning creates a conditional right to funds and an inventory of issued vouchers. Other processes related to this are voucher inventory management, voucher suspension, and voucher purging.
* Merchant Registration\
In order for efficient redemption of vouchers merchants MUST be registered in advance to create a network of trusted providers. This registration is assumed to be managed by the Registration Building Block, The account verification of the merchant can be done at registration or during redemption subject to a configuration.\
\
During the registration process, merchants MAY also be assigned to different voucher groups depending on the required function that has been implemented. For example, there may be a voucher group for schools. This implies that vouchers of this type can only be redeemed at schools. This also requires that the user flow system at which the voucher is issued is aware of these voucher groups and is able to send the appropriate request to the Voucher Management System.
* Agent Registration\
In markets where cashouts are being used, it is expected that the Registration Building Block will register agents in a similar way.
* Voucher Groups\
Depending on the requirement it should also be possible to set up multiple voucher groups. Vouchers in the same voucher group will have similar characteristics and are labeled with a specific voucher group name. During voucher provisioning, a voucher can be created and attached to a single voucher group. When a voucher is requested (using the pre-activation API) it is expected that the voucher group will be one of the parameters set.
* Voucher Issuing\
Voucher issuing is triggered by the Registration Building Block which will determine whether the conditions of issuance have been met. The calling Block will determine the denomination and voucher group of the voucher to be issued. The voucher number and the voucher serial number that is issued can be presented to the beneficiary in multiple ways including but not restricted to encoding in the form of QR codes, bar codes, printed vouchers, or even SMS. This is outside the scope of the Payments Building Block. It is expected that Building Blocks through which the voucher is redeemed will also be able to decode the voucher.
### **9.2.2 Voucher Activation workflow**
The voucher activation flow is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Activation v3
Source BB->Payment BB: Activate voucher
Payment BB-->Source BB: Voucher successfully Activated
alt Error 400
Payment BB-->Source BB: Invalid request
end
alt Error 456
Payment BB-->>Source BB: Invalid voucher serial number
end
alt Error 460
Payment BB-->Source BB: Gov Stack Building Block does not exist
end
alt Error 455
Payment BB-->Source BB: Voucher group exhausted
end
alt Error 500
Payment BB-->Source BB: Internal Server error
end
alt Error 503
Payment BB-->Source BB: Service Unavailable
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end
" %}
Flow Description:
* An external Building Block may invoke the Payments Building Block API gateway to pre-activate API on the Voucher Management Server with the amount of the voucher, the voucher currency, and the voucher group. The calling Building Block may optionally send a comment. The comment will be stored by the voucher server. The voucher group will indicate that it is looking for a voucher from a specific voucher group. This API call will be made through the Payments orchestrator.
* The voucher group is typically used for conditional social transfer (e.g. for school fee payment). If any voucher can be used for any purpose, then all vouchers should be created with a generic voucher group (e.g. “GENERAL-PURPOSE”).
* The API returns to get a voucher number, the voucher serial number, and its expiry date. At this point, the voucher will be flagged as Pre-Activated.
* The calling Building Block may render the voucher as a QR code, as a barcode, or even as an SMS text. It is recommended that the voucher should include supplementary data of the recipient. It is also recommended that this data should also be printed in human-readable form so that the recipient can verify the data on the voucher. This data can also be verified at the point of redemption.
* Once the calling API successfully prints/issues the QR code, the voucher can then be activated using the activation API. It is assumed that there will not be a substantial delay between pre-activation and activation to necessitate the need for multiple expiry periods.
Alternative: the voucher could be activated immediately on being requested. This could be controlled at the Payments Orchestrator.
* Preconditions
* The calling registration block will determine that all the necessary preconditions are met.
* The most critical precondition is the prefunding which will be done manually at the voucher provisioning stage. Other options that could be prefunding triggered by activation or at redemption are not considered because they are considerably more complex and create additional failure points in the activation of the vouchers.
* Assumptions/Queries
* It is assumed that only one currency will be used.
* A zero-trust architecture.
* The transaction is not reversible.
* Post-Condition\
The calling Building Block may invoke another payment Building Block API, e.g. initiating an incentive payment for the agent.
### **9.2.3 Voucher Redemption workflow**
The voucher redemption process is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Redemption
Source BB (Merchant Interface) ->> Merchant registry: Submit voucher details
Merchant registry -->> Source BB (Merchant Interface): Merchant name and payment details
Source BB (Merchant Interface) ->> Payment BB: Submit voucher and merchant details
alt Error 400
Payment BB-->>Source BB (Merchant Interface): Invalid request
end
Payment BB ->> Payment BB: Check Voucher
alt Error 458
Payment BB-->>Source BB (Merchant Interface): Voucher number already used
end
alt Error 461
Payment BB-->>Source BB (Merchant Interface): Invalid voucher number
end
Payment BB->>FSP: Debit request
alt Error 599
Payment BB-->>Source BB (Merchant Interface): Network connection error
end
FSP->Funding A/c: Debit request
Funding A/c -->> FSP: Debit successful
alt Error 462
FSP -->> Payment BB: Insufficient funds
Payment BB -->> Source BB (Merchant Interface): Insufficient funds
end
FSP->Merchant A/c: Credit Request
Merchant A/c -->> FSP: Credit Request successful
alt Error 463
FSP -->> Payment BB: Cannot credit merchant
Payment BB -->> Source BB (Merchant Interface): Cannot credit merchant
end
Payment BB ->> Payment BB: Consume Voucher
Payment BB ->> Source BB (Merchant Interface): Amount credited to merchant account and voucher is consumed
" %}
Flow Description:
* At redemption, the beneficiary shows the voucher to the merchant or agent.
* The merchant/agent will scan and interpret the medium in which the voucher is presented (this could be a QR code or a barcode or an SMS or even a printed number).
* Voucher redemption Validation: The details presented MAY allow the merchant/agent to authenticate/validate the owner of the voucher.
* The agent will then initiate the redemption process which will call the Payment Building Block API Management Gateway.
* The API Management Gateway will validate the voucher and initiate the payment through the payment gateway.
* If specific voucher groups have been set up, voucher usage may be restricted to specific merchants. An override parameter should also be provided that will allow a Voucher of any voucher group to be redeemed at any merchant.
* Once the payment to the merchant/agent is successful the Payment gateway will inform the API Management Gateway.
* The API Management Gateway will then instruct the VMS API to flag the voucher as consumed.
Alternatives:
* Payments could be made through a switch in which case there would be no need for prefunding accounts in each financial institution.
Preconditions:
* The merchant must have been registered possibly by the Registration Building Block with their preferred payment method.
* The merchant must have a mechanism (e.g. a mobile APP, USSD app, or SMS option) to verify the beneficiary prior to redemption.
Assumptions:
* The app for reading the QR code and redemption is not part of the scope of the Payment Building Block.
* The entire voucher amount is consumed. Partial redemption will not be allowed.
* The amount that is paid to the merchant or agent is debited from a prefunded account.
**Sample Redemption**
.png?alt=media)
Note:
In the case of a physical voucher, the voucher number or the secret number is hidden behind some material that must be scratched away to see the number. The voucher number is also commonly known as the PIN.
### **9.2.4 Voucher Cancellation workflow**
The voucher cancellation flow is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Cancellation
Source BB -> Payment BB: Cancel Voucher
Payment BB-->Source BB: Voucher Cancelled
alt Error 499
Payment BB-->Source BB: Invalid Request
end
alt Error 463
Payment BB-->Source BB: Invalid Voucher
end
alt Error 464
Payment BB-->Source BB: Voucher is already cancelled
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end
" %}
Flow Description:
* The calling Building Block will request the API Management Gateway to cancel a Voucher.
* The API Management Gateway will invoke the VMS API to cancel the Voucher.
* The Vaucher Management System (VMS) API interface will check if the Voucher is valid and then cancel the Voucher.
* The VMS API interface will confirm that the Voucher has been canceled.
Alternatives:
* If the Voucher does not exist, the VMS API will respond that the Voucher does not exist.
* If the Voucher is already consumed, the VMS API will respond that the Voucher is already consumed.
* If the Voucher is already canceled the VMS API will respond that the Voucher is already canceled.
* If the Voucher is suspended the VMS API will respond that the Voucher is suspended.
* All calls from external parties (e.g. Registration Building Block) to the voucher management system will be initiated through the API management gateway.
* The payment orchestration module may direct transitions between the various functions.
* The discovery service could be called by other building blocks to determine where bank accounts/wallets sit.
* The only function that speaks to the DFS is the payment gateway. Any function that needs to speak to the DFS goes through the Payment gateway.
* The Payment gateway may need to speak to a Number Portability provider.
* Audit trails (transaction logs) capture each event as it happens and are to be used for queries, analysis, and reconciliation.
* Event logs will capture specific events that happen at each node.
## 9.3 P2G Bill Payments
The following types of P2G payments are considered.
* Bill payments such as utilities
* Payments for government services (for example application for a birth certificate)
The following is assumed for bill payment with the Payments BB
* The Bill ID generation/ distribution scenario of a jurisdiction is already decided and in place.
* Depending upon the applicable scenario all relevant billers/ aggregators/ Bill payment Systems responsible for distributing the Bill IDs to consumers are also registered with the Payments BB.
* The Settlement of bill amounts is carried out by the relevant payers and payee FSPs.
* The Payments BB will generate a report/ allow a data extract that would contain the log of transactions that would be used for settlement of the transactions between the Payer FSP and the Billers/ Aggregators FSPs
The following processes are involved in government bill payments:
### **9.3.1 Biller Onboarding**
The Biller onboarding would be a one–time prerequisite activity required to be carried out before consumers could pay bills to them.
The main function of Payment BB in this case is allocating unique IDs to the registering entity and ensuring that all Bill Payment related queries are routed to these registered entities.
The relationship between billers/ aggregators and how they identify specific bills from the consumers numbers is the billers'/aggregators' responsibility only and out of scope for Payments BB.
Biller/Aggregator Onboarding
**Pre-req to Biller Onboarding**
* The structure of the unique ID is defined including, the length of the unique ID and whether the ID is simply a sequential number or if each digit of the ID identifies any unique entity/actions.
The incoming biller/ aggregator has the required infra to support continuous requests and updates.
**Onboarding Process**
* Onboarding Request: This step could be a manual process where a representative gathers all the required information from the billers/ aggregators and enters it into the system via a UI-based form/ table. (This process may go through the make checker process)
* Unique IDs/ Prefixes are generated by the system for each direct biller or aggregator (depending upon the billing ecosystem model). The entire information is saved in the system in the ‘Billers Table’.
* The billers/ aggregators are returned a unique ID/ prefix allocated to them.
* The billers/ aggregators concatenate the unique ID/ prefix before the Bill IDs that they generate and share with their consumers.
### **9.3.2 Payer Financial Institution – PBB Linking for Bill Payments**
The Payer FI – PBB linking is a one–time prerequisite activity required before consumers can request bill payment over the Payments BB. Setting up of the front end, UI to take the requests from the consumers would fall under the responsibility of the Payer FI only and would be out of the scope of payments BB
Pre-requisites for the Payer FSP – PBB Linking Process
* The Payer FSP is enabled for Interbank Funds Transfer (for settlement) – Out of Scope of PBB
* The Payer FSP is equipped with the right infrastructure to communicate with the PBB
Payer FSP – PBB Linking would be an offline process comprising formal agreements and the following activities to ensure proper functioning:
* PBB shares the list of Billers and the unique IDs allotted to them with the Payer FSP
* PBB shares its endpoints and required API contracts that need to be setup at the FSP;
* PBB shares the *required* Bank and Account Details of each registered Biller with the FSP for carrying out financial transactions and settlement activities. The biller details could be either manually configured by the Payer FSP at their end or Payments BB could prepare a file and keep it at a central location for Payer FSP to download/ upload it (as decided).
Once the Payer FSP is setup with PBB for Bill Payment Services then it is expected that it:
* Would be able to accept from its customers Bill IDs of different Billers.
* Would be able to differentiate at its end the exact biller/ aggregator for which the customer has entered the Bill ID.
* Would be able to credit the respective account of the biller based on the account information shared by PBB at the time of linking.
* Would duly notify the PBB of the final status of the Bill Payment Request (successful debit/ Failed debit)
### **9**.3\*\*.3 Bill Inquiry & Bill Payment Update via Payment BB\*\*
After the completion of the prerequisite setups, the Payment BB is ready to accept requests from the Payer FSPs and retrieve information from and communicate with the Billers, Aggregators, and Government Entities.
Main Responsibilities of Payment BB in the flow
1. The PBB would receive the Bill Inquiry as a result of Pay Bill request at a Payer FI – Payer end.
2. PBB would validate the sender of request and send it on to the respective Biller/ Govt. Entity to fetch bill.
3. The Payer FSP would then either perform payment confirmation or abort the transaction – in either case it would notify the PBB of the Payment Status
4. Receiving the Payment Status Update the PBB would forward the Payment confirmation to Biller/ Govt. Entity
5. PBB sends Mark Bill Paid Advice to the Biller/ Govt Entity until a response is received from that site.
6. Upon receiving a response from the Biller/ Aggregator, the PBB would notify the Payer FSP of the response.
7. The Government Agency sends an invoice to the payer, detailing the amount owed.
8. The Government Agency also sends a copy of the invoice to the designated Bill Aggregator.
9. The Bill Aggregator then sends the invoice reference number to the Payments Building Block .
10. The payer, upon receiving the invoice, provides the invoice reference number to their preferred Collection Financial Service Provider (Collection Financial Services Provider).
11. The Collection Financial Services Provider (FSP) requests transaction details, including the amount to be paid, from the Payments Building Block using the invoice reference number.
12. The Payments Building Block, in turn, requests the transaction details from the Bill Aggregator.
13. The Bill Aggregator provides the requested transaction details to the Payments Building Block.
14. The Payments Building Block forwards the transaction details to the Collection FSP.
15. The Collection FSP executes the payment based on the transaction details provided.
16. After completing the payment, the Collection FSP sends the payment reference to the Payments Building Block.
17. The Payments Building Block forwards the payment reference to the Bill Aggregator.
18. Finally, the Bill Aggregator sends the payment reference to the Government Agency, confirming the completion of the payment.
**Push Payment Flow with Bill Inquiry Flow**
{% @mermaid/diagram content="sequenceDiagram
title Push Payment Flow with Bill Inquiry
title P2G Bill Payment via RTP
participant "Payer FI" as PayerFI
participant PaymentsBB
participant ALS
participant "Bill Aggregator GovtEntity" as BillAggregator
```
BillAggregator->>PaymentsBB: 1. billerRtpReq (txnID, rtpId, billId, requestType, aliasID (C))
PaymentsBB-->>BillAggregator: billerRtpReq (Ack)
alt RTP Type = 00
note over PaymentsBB: Jump to "SEND RTP TO PAYER FI" Step
else RTP Type = 01
PaymentsBB->>* ALS: Bill ID is routed to lookup service.
ALS->>PaymentsBB: Returns back with Payer FI details.
note over PaymentsBB: Jump to "SEND RTP TO PAYER FI" Step
end
note over PaymentsBB, PayerFI: SEND RTP TO PAYER FI
PaymentsBB->>PayerFI: 2. payerRtpReq \n(txnId, billId, [Bill Details])
PayerFI-->>PaymentsBB: payerRtpResp (Ack)
note over PayerFI: Initiate "RTP Notification Sequence - Customer<->FSP"
PayerFI->>PaymentsBB: 3. payerRtpResp\n(txnId, referenceId)
PaymentsBB-->>PayerFI: payerRtpResp (Ack)
PaymentsBB->>BillAggregator: 4. billerRtpResp (txnId, paymentStatus, referenceId)
BillAggregator-->>PaymentsBB: billerRtpResp (Ack)
opt If BillAggregator requires status update
BillAggregator->>PaymentsBB: rtpStatusUpdate (txnId, rtpID)_ Req
PaymentsBB-->>BillAggregator: rtpStatusUpdate (Status Code) _ Resp
end
note over PayerFI, BillAggregator: BILL PAYMENT STATUS STAGE
note over PayerFI: Initiate "LEG2:PayBill Sequence - Customer/FSP"
PayerFI->>PaymentsBB: paymentStatusUpdate(Payment Status, Txn ID, RespCode) _ Req
PaymentsBB-->>PayerFI: paymentStatusUpdate(Ack)
note over PaymentsBB, BillAggregator: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB->>BillAggregator: markBillPaid(Bill ID, ReceiptNum, PaymentStatus) _ Req
note right of PaymentsBB: Payments BB keeps sending \n Bill Payment Advice to BillAggregator \n until Response received from BillAggregator
end
BillAggregator-->>PaymentsBB: markBillPaid (Ack)
BillAggregator->>PaymentsBB: markBillPaid(MarkStatus, RespCode(C)) _ Resp
PaymentsBB->>PayerFI: paymentStatusUpdate(Payment Status, Txn ID, RespCode) _ Resp
PayerFI-->>PaymentsBB: paymentStatusUpdate(Ack)" %}
```
1. **Bill Inquiry stage**
* **Payer FI** initiates the process by querying bill details.
* **Payer FI** requests bill inquiry using `billInq(Txn ID, Bill ID)_Req`.
* **PaymentsBB** validates the request, performing security checks and registration status verification.
* If validations fail, **PaymentsBB** sends an error response to **Payer FI**.
* If validations succeed, **PaymentsBB** identifies the biller and moves to the next step.
**2. Biller discovery**
* **PaymentsBB** identifies the biller by querying the **Billers Table** using `IdentifyBiller(Prefix)`.
* **Billers Table** provides **PaymentsBB** with the Biller's endpoint information.
* **PaymentsBB** then proceeds to fetch the bill from the **Bill Aggregator/Government Entity**.
3. **Fetch Bill**
* **PaymentsBB** requests bill details from **Bill Aggregator/Government Entity** using `billInqBiller(Bill ID)`.
* **Bill Aggregator/Government Entity** performs internal checks (e.g., payment status, expiry) and responds with bill details.
* **PaymentsBB** forwards bill details to **Payer FI** for review.
**4. Bill Payment Status**
* **Payer FI** reviews the bill details and initiates the payment sequence.
* **Payer FI** updates the payment status using `paymentStatusUpdate(Payment Status, Txn ID, RespCode)`.
* **PaymentsBB** acknowledges the update and marks the bill as "PAID" in the request sequence.
* **PaymentsBB** sends payment advice to **Bill Aggregator/Government Entity** until a response is received.
* Once confirmed, **Bill Aggregator/Government Entity** acknowledges the payment and updates the status.
* Finally, **PaymentsBB** notifies **Payer FI** of the successful payment update
### Payer FI – Customer Bill Payment Flow
{% @mermaid/diagram content="sequenceDiagram
title PayBill Sequence - Customer/FSP
participant Payer as Payer
participant PayerFI as Payer FI
```
note over Payer, PayerFI: LEG 1: BILL PAYMENT REQUEST
Payer->>PayerFI: Pay_Bill_Req (Bill ID)
note right of PayerFI: Forwards billInquiry (Bill ID) _ Req to PBB
note left of PayerFI: Receives billInquiry_Resp from PBB
PayerFI->>Payer: Pay_Bill_Resp \n(Biller Name, Due Date\nAmount,Bill Status )
note over Payer, PayerFI: LEG 2: BILL PAYMENT CONFIRMATION
Payer-->>PayerFI: Confirms Bill Payment
PayerFI->>PayerFI: * Performs Account Validations \n * Identifies the Biller Account
note over PayerFI: Logs Txn_Success_Ref ID/ \n Txn_Fail_Ref ID
alt If Validations OK
PayerFI->>PayerFI: Debits Payer's Account
PayerFI->>Payer: Sends Payment Receipt \n(Txn_Success_Ref ID)
PayerFI->>Payer: Account/ Wallet Debited - Bill Paid (Txn_Success_Ref ID)
Note right of PayerFI: Initiates: "(PBB) BILL PAYMENT STATUS STAGE" \nCalls PAYER BB API -> paymentStatusUpdate
else If Validations KO
PayerFI->>PayerFI: No Debit
PayerFI->>Payer: Sends Txn Failure Message (Txn_Fail_Ref ID)
note right of PayerFI: Bill Paid Status (Txn_Fail_Ref ID)
end
```
" %}
### P2G Bill Payment via Request to Pay Flow
{% @mermaid/diagram content="sequenceDiagram
title P2G Bill Payment via RTP
participant PayerFI as "Payer FI"
participant PaymentsBB as "PaymentsBB"
participant ALS as "ALS"
participant BillAggregator as "Bill Aggregator GovtEntity"
```
BillAggregator->>PaymentsBB: 1. billerRtpReq (txnID, rtpId, billId, requestType, aliasID (C))
PaymentsBB-->>BillAggregator: billerRtpReq (Ack)
alt RTP Type = 00
PaymentsBB->>PayerFI: Jump to \"SEND RTP TO PAYER FI\" Step
else RTP Type = 01
PaymentsBB->>+ALS: Bill ID is routed to lookup service.
ALS->>PaymentsBB: Returns back with Payer FI details.
PaymentsBB->>PayerFI: Jump to \"SEND RTP TO PAYER FI\" Step
end
Note over PaymentsBB, PayerFI: SEND RTP TO PAYER FI
PaymentsBB->>PayerFI: 2. payerRtpReq (txnId, billId, [Bill Details])
PayerFI-->>PaymentsBB: payerRtpResp (Ack)
Note over PayerFI: Initiate \"RTP Notification Sequence - Customer<->FSP\"
PayerFI->>PaymentsBB: 3. payerRtpResp (txnId, referenceId)
PaymentsBB-->>PayerFI: payerRtpResp (Ack)
PaymentsBB->>BillAggregator: 4.billerRtpResp (txnId, paymentStatus, referenceId)
BillAggregator-->>PaymentsBB: billerRtpResp (Ack)
opt If BillAggregator requires status update
BillAggregator->>PaymentsBB: rtpStatusUpdate (txnId, rtpID)_ Req
PaymentsBB-->>BillAggregator: rtpStatusUpdate (Status Code) _ Resp
end
Note over PayerFI, BillAggregator: BILL PAYMENT STATUS STAGE
Note over PayerFI: Initiate \"LEG2:PayBill Sequence - Customer/FSP\"
PayerFI->>PaymentsBB: paymentStatusUpdate(Payment Status, Txn ID, RespCode) _ Req
PaymentsBB-->>PayerFI: paymentStatusUpdate(Ack)
Note over PaymentsBB, BillAggregator: Mark Bill == \"PAID\" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB->>BillAggregator: markBillPaid(Bill ID, ReceiptNum, PaymentStatus) _ Req
BillAggregator-->>PaymentsBB: markBillPaid (ack)
end
BillAggregator->>PaymentsBB: markBillPaid(MarkStatus, RespCode(C)) _ Resp
PaymentsBB->>PayerFI: paymentStatusUpdate(Payment Status, Txn ID, RespCode) _ Resp
PayerFI-->>PaymentsBB: paymentStatusUpdate(Ack)" %}
```
### P2G Bill Payment with Voucher
{% @mermaid/diagram content="sequenceDiagram
title Payment By Voucher
```
participant Payer FI as PR
participant PaymentsBB as PBB
participant Voucher Engine as V
participant Biller as Biller
note over PR: Bill Inquiry is Done - For Bill Payment "Voucher" is chosen as option
note over Payer FI, Biller: BILL PAYMENT STATUS STAGE
PR ->> PBB: voucherRedemptionforBillPayment(BillInquiryCorrelationID, Bill Details, Voucher Secret Code)
note over PBB: PBB receives API Call with Voucher as well as Bill Details.
PBB ->> V: VOUCHER REDEMPTION
note over PBB,V: PAYBB checks that Voucher is valid, Voucher Amount and Bill Amount are same
PBB ->> V: VoucherInquiry(Secret Code)
V -->> PBB: VoucherInquiry_Response
note over PBB: Check Voucher Value, Bill\nValue, Check Compatibility\n\nIf Okay, Redeem Else Cancel
PBB ->> V: redemptionWithoutAuthentication_Request
V -->> PBB: redemptionWithoutAuthentication_Response
PBB --x V: destroy V
PBB -->> PR: voucherRedemptionforBillPayment(Status)_Resp
note over PBB, Biller: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB ->> Biller: markBillPaid(Bill ID, ReceiptNum, PaymentStatus) _ Req
note right of PaymentsBB: Payments BB keeps sending \n Bill Payment Advice to Biller \n until Response received from Biller
end
Biller -->> PaymentsBB: markBillPaid(ack)
Biller -->> PaymentsBB: markBillPaid(MarkStatus, RespCode(C)) _ Resp
PaymentsBB ->> PR: paymentStatusUpdate(Payment Status, Txn ID, RespCode) _ Resp
Payer FI -->> PaymentsBB: paymentStatusUpdate(ack)
```
" %}
# 10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
### 10.1 Key Decision Log
[A historical log of key decisions regarding this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183435345/Key+Decision+Log+Payments).
### 10.2 Future Considerations
[A list of topics that may be relevant to future versions of this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183402524/Future+Considerations+Payments).
### 10.3 Out-of-Scope Assumptions
[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/6ERMn830).
# Payments Building Block Specification
Version 3.0; December 2025
***First Developed by:***\
Vijay Mauree, Arnold Kibuuka, and Dr. P. S. Ramkumar ([ITU](https://itu.int)), Francesco Pasti ([GSMA](https://www.gsma.com/)), James Dailey, David Higgins ([MIFOS](https://mifos.org)), Oscar Correia ([Maarifa Education](https://www.maarifaeducation.com/)), Khuram Farooq ([World Bank](https://www.worldbank.org/)) and Elie Sawaya ([GIZ](https://giz.de/))
***
***Authors to this version:***\
Vijay Mauree, Arnold Kibuuka, David Higgins, and Oscar Correia
***Editor:***\
Ali González-García
Payments Building Block cover
# 1 Version History
The version history table describes the major changes to the specifications between published versions.
Version
Authors
Comment
0.9.2
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, Sanjay Jain, Luukas Ilves, Lesley-Ann Vaughan
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume
Reviewers:
Sasa Kovacevic, Aare Lapõnin, Anita Mitta, Amy Darling
Editors:
Wesley Brown, Steve Conrad, Valeria Tafoya
Feedback incorporated from Technical Advisory Committee review
Final edits to align content to specification template for GovStack 1.0 release
2.0.0 (previously known as 23Q4) October 2023
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume, and Elie Sawaya
Editors:
Wesley Brown, Steve Conrad, Valeria Tafoya
Introduced new terminology, enhanced P2G requirements, added Billers Table, updated multiple APIs (Onboarding, Bulk Disbursement, Voucher, new P2G APIs), and revised internal P2G workflows.
2.1.0 (previously known as 23Q4) July 2024
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq, James Dailey, Luukas Ilves, Sanjay Jain, Achim Blume, and Elie Sawaya
Editors:
Wesley Brown, Steve Conrad, Valeria Tafoya
Addressed discrepancies found during sandbox implementation: modified scheduling services, made eligibility verification required, included recommended reporting requirements, and removed external scheduling.
3.0 December 2025
Vijay Mauree, Arnold Kibuuka, Oscar Correia, David Higgins, Dr. P. S. Ramkumar
Editor:
Ali González-García
Specification for In-Country Multicurrency Payment Systems for governments, persons and businesses.
# Release Notes
## Version 3
***
### **v3.0.0**
*Release date: December 2025*
#### **Release Overview:**
This update primarily expand the Payments Building Block with guidance to implement Multicurrency use cases, as well as extending the use of existing APIs, originally implemented for Government-to-Person (G2P) and Person-to-Government (P2G) transactions, to also support Government-to-Business (G2B) and Business-to-Government (B2G) use cases.
Detailed context on multicurrency payments can be viewed on [Payments BB: Multicurrency - GovStack - GovStack Wiki](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/1014693904/Payments+BB+Multicurrency?force_transition=f336d546-d52d-486b-8e52-b20a721d5890)).
Multicurrency is important because it enables seamless transactions across different currencies, enhancing efficiency, transparency, and access to financial services in diverse economic environments. Additionally, some countries have multiple currencies due to reasons such as economic instability, historical factors, or the presence of a significant informal economy. This multiplicity can facilitate trade and investment but may also complicate financial management and regulatory oversight.
#### **Multicurrency updates:**
* Description: The description was updated to include the multicurrency use cases
* Terminology: New terms have been added to better define multicurrency operations.
* Key Digital Functionalities: We have implemented support for multiple currencies.
* Crosscutting Requirements: We've incorporated additional requirements for the calculation of multicurrency payments, ensuring independent calculations and settlements in the same currency as the transaction. This update also includes the handling of multicurrency accounts for both payers and payees.
* Standards: Standards for currency and payment status codes have been integrated into the specification.
* Data Structures: Updates to the data structures, now include currency indication as a mandatory field for multicurrency transactions.
* Service APIs: The P2G APIs have been enhanced to include the currency functionality for multicurrency use cases. Additionally, updates have been made to the G2P bulk disbursement payment APIs and P2G responses to correct display errors.
* Internal Workflows: Adjustments have been made to display workflows that accommodate multicurrency transactions.
#### **G2B and B2G updates:**
* Updated [Description](/2-description) chapter to reference G2B additions
* Bulk Payments on section [4.15](https://payments.govstack.global/1-version-history/pages/5btM4AznD7kQwFbRf5C7#id-4.15-bulk-payment-service) now references G2B case
* Added service API guidance for [8.4 Government to Business](/8-service-apis) and [8.5 Business to Government](/8-service-apis/8.5-business-to-government-b2g-payments)
* Added [9.4 Government to Business](/9-internal-workflows/9.4-government-to-business-g2b) and [9.5 Business to Government](/9-internal-workflows/9.5-business-to-government-b2g) guidance
* Re-structuring of [chapter 9](/9-internal-workflows) to spread the content on sub-pages for readability
* Added 2 uses cases: [Government to Business](/use-cases/government-to-business-g2b-use-case) and [Business to Government](/use-cases/business-to-government-b2g-use-case) for guidance on how to use these features.
#### **Other changes in this release.**
* [4.10 Scheduling Services](https://payments.govstack.global/1-version-history/pages/5btM4AznD7kQwFbRf5C7#id-4.10-scheduling-services): The scheduling feature within the payments module has been refined to clearly define internal payments BB scheduling processes.
* [8. Service APIs](/8-service-apis): The issue with Section 8 not loading due to excessive swagger blocks has been identified and resolved, mirroring a similar fix implemented in the bb-emarketplace.
* The following optional cross-cutting requirements are changed to "recommended":
* Compliance Verification
* Calculation of Payments
* [5.3 Technical Requirements](https://payments.govstack.global/1-version-history/pages/wJ5tgdMYdre4XPqtYRex#id-5.3-payments-building-block-technical-requirements) tables are re-worked for legibility and requirement level terms homologated to match GovSpecs 2.0 requirement levels.
* [5.4 Standards](https://payments.govstack.global/1-version-history/pages/wJ5tgdMYdre4XPqtYRex#id-5.4-standards) section is added recommending [ISO 20022](https://www.iso.org/standard/57341.html) and [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) to enhance industry interoperability
#### **Documentation**
For more information regarding these updates, users are encouraged to consult the revised sections within the specification. Additionally, for details on multicurrency, please refer to the multicurrency use case document available here: [Specification for In-Country Multicurrency Payment Systems for governments, persons and businesses](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/1014693904/Payments+BB+Multicurrency?force_transition=f336d546-d52d-486b-8e52-b20a721d5890)
***
## Version 2
***
### **v2.1.0 (previously known as 23Q4)**
*Released date: July 2024*
#### Overview
Following the sandbox implementation of the payments BB in February 2024, discrepancies below were noted in the spec and subsequently updated in this version.
#### **Section 4: Key Digital Functionalities**
4.10 Changes: Modification of the scheduling services in the payments BB; i.e., to enable internal functionalities like bulk processing of payments.
#### **Section 5: Cross-cutting requirements**
5.1.8 Change of eligibility verification from recommended to required
5.2.3 Inclusion of the recommended requirements for reporting services into cross-cutting requirements:
* The data store will be write-only from the core service and should be read-only by external components (RECOMMENDED)
* The data model on the reporting data store can be different from the internal operational data models that the switch uses (RECOMMENDED)
* The component provided by the switch will translate internal events and internal data models to the external data store models. This component can be replaced (RECOMMENDED)
#### **Section 6: Functional requirements:**
6.10 Removal of the "Regular and repeat payments are scheduled (REQUIRED)" from Scheduling Services as this is done outside the payments BB.
### **v2.0.0 (previously 23Q4)**
*Release date: October 2023*
#### **Overview:**
These updates aim to refine the specifications necessary for executing payments from individuals to governments.
#### **Terminology Updates:**
New terminologies have been introduced in the document, including: "Billers," "Aggregators," "Payer," and "Payee."
#### **Functional Requirements:**
Enhancements have been made to the P2G (Person to Government) requirements, now encompassing the billers table, aggregator, and Payer Financial Institutions.
#### **Data Structures:**
A new addition in this section is the "Billers Table," curated for the essential fields pertinent to a biller's table used in the new P2G workflows.
#### **Service APIs:**
Multiple APIs have been revised and enhanced with additional endpoints. The updates encompass:
* **Onboarding to the Account Mapper:**
* Register\_Beneficiary\_Response
* Register\_Beneficiary
* Update\_BeneficiaryDetails
* Update\_BeneficiaryDetails\_Response
* **Bulk Disbursement:**
* PrePayment\_Validation
* PrePayment\_Validation\_Response
* BulkPayment
* **Voucher APIs:**
* VoucherPreActivation
* VoucherActivation
* VoucherStatus
* VoucherCancellation
* VoucherRedemption
* BatchVoucherActivation
Note: The Voucher Redemption API may operate synchronously to ensure the delivery of prompt and reliable responses to the initiating clients, whether users or systems.
* **New P2G APIs:**
* billInquiryBiller
* markBillPayment
* BillerRtpReq
* billerRtpResp
* rtpStatusUpdate
#### **Internal Workflows:**
Significant updates have been made to the internal workflows to accommodate P2G bill payment flows. The enhancements include:
* Workflows supporting biller onboarding – envisioned as a one-time activity on the Payments BB.
* The incorporation of workflows for linking the Payer Financial Institutions (PFI) with the Payments BB for bill payments.
* Implementation of workflows for Bill Inquiry & Bill Payment Updates via the Payment BB.
* Additional flows introduced are:
* Push Payment Flow integrated with Bill Inquiry Flow.
* Payer Financial Institution (PFI) – Customer Bill Payment Flow.
* P2G Bill Payment via Request to Pay (RTP) Flow.
* P2G Bill Payment with Voucher.
***
## Version 1
***
### **v1.0.0**
*Released date: May 2022*
#### Overview
Payments Building Block was first published in May 2022 by the Payments Working Work as reference specification for implementers.
# 2 Description
This section provides context for this Building Block.
The Payments Building Block enables digital financial payments to be tracked, evaluated, initiated, validated, processed, logged, compared and verified against budget. This Building Block also provides interoperability with connections to the various external applications that need payment services in order to trigger transitions in their own workflow. Payment services generally interface through gateways to regulated financial entities such as banks, credit facilities, and insurance companies. To help users easily complete payment transactions and learn if their transaction succeeded or failed, it converts heterogeneous interface protocols, formats, and user interfaces to a standard set of common interfaces and formats. It can also help in tracking the costs of commodity and equipment purchases to optimize budgets.
The Payments Building Block consists of components that enable multiple use cases in a generic manner. The use cases include Government to Person (G2P), Person to Government (P2G), Government to Business (G2B), and Business to Government (B2G). The existing commercial Payments schemes are heterogeneous across regions and countries, the Payments Building Block assumes that some components are optional when considering implementation. The Payments Building Block covers components that can be used to deliver the key functionalities and the connections to existing systems in the market, but does not contemplate building a new Payments scheme. The Payments Building Block supports multicurrency payments in countries where there is more than one currency used. Multicurrency payments are supported based on the independent multicurrency model, where there is no exchange rate conversion. For more information on the multicurrency payments refer to: [Specification for In-Country Multicurrency Payment Systems for governments, persons and businesses](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/1014693904/Payments+BB+Multicurrency?force_transition=f336d546-d52d-486b-8e52-b20a721d5890).
### Financial Inclusion, Banks, and Mobile Money Accounts
Financial inclusion strategies have largely been based on growing access to regulated accounts. These were traditionally understood to be bank accounts, in recent years Mobile Money (MoMo) accounts have greatly increased transactional account access. These MoMo accounts are often, but not always, treated as secondary to the banking system and lack interoperability.
[According to GSMA](https://www.gsma.com/mobilefordevelopment/wp-content/uploads/2021/03/GSMA_State-of-the-Industry-Report-on-Mobile-Money-2021_Summary.pdf), globally registered mobile money accounts stood at 1.2 billion in 2020, transacting an average of over $2 billion per day, mobile money has grown to become the leading payment platform in a growing number of emerging markets. Today, there are more mobile money accounts in Sub-Saharan Africa than there are bank accounts. Indeed, during the pandemic, demand for mobile money services increased among businesses, governments, and new services that previously relied on cash or other payment channels.
There are currently active discussions in many markets on the need for the integration of mobile money into existing national infrastructure. While the integration of mobile money into existing schemes and infrastructure has the potential to create value for all stakeholders in the ecosystem, many legacy payment systems may not be suitable for mobile money integration in their current state. As an example, many existing interbank switches do not support mobile money as a core feature because of legacy technical architecture. What is often missing is the essential capability of the switch to handle high-volume, low-value flows with the mobile number (Mobile Station Integrated Services Digital Network) as identifier for routing and address resolution hence the need for integration. Recent industry developments offer solutions designed to solve many of the issues around the switching of mobile money.
Mobile money providers, regulators, infrastructure providers, and other financial system players should seek to engage in any potential interoperability initiatives from an early stage to ensure optimal payment system design for all parties. Should existing infrastructure be used, a thorough assessment should be conducted, with input from all parties, to ensure appropriate governance, commercial, and technical standards are incorporated. Mandating interoperability within a short time frame removes opportunities for a thoughtful and holistic analysis of commercial sustainability. Requiring immediate interoperability can also delay or hamper the uptake of interoperable transactions, and mobile money services altogether. This is a particular risk in contexts where regulators or governments impose immediate connections to a centralized hub. Mobile money providers should be encouraged to connect when their service is ready. However alternative modalities of payment such as cash vouchers can also be considered in scenarios of low-resource regions that lack modern infrastructure and a volume of mobile phone users. Also, in countries where mobile money providers are not connected to a payment switch, aggregators can enable the flow of funds between multiple financial service providers including banks and non-banks. While aggregators may not be as efficient and scalable as switches, they can help solve interoperability issues in the short and medium term.
## Payments Building Block Capabilities
Generally, the Building Block is supportive of multiple types of payment use cases where the Government is one of the parties:
* **Government to people (G2P)**
* Payment where the payer is a government and the payee is an individual e.g. Social benefits disbursement, government salary payments, Conditional and [Unconditional Social Cash Transfers](https://solutions.dial.community/use-cases/unconditional-social-cash-transfer/use-case-steps/payment)).
* **People to Government (P2G)**
* Payment where the payer is an individual and the payee is a government. P2G payments can be government initiated, for instance, in the case of payments for registrations for government services. For bill payments and payments for government services directly by the person, the system should provide the person with the flexibility to choose which payment instrument to use (eg. mobile money, bank transfer or card payments). (e.g. payment of taxes, payment [Registration for Postpartum and Infant Care](https://govstack.gitbook.io/use-cases/ruc-23q4/use-cases/hltc-1-postpartum-and-infant-care#id-6-payment), payment of school fees, driving license, utility payments).
* **Government to Business (G2B)**
* G2B payments include tax refunds, goods and services purchases, subsidies, contract payments, benefits, and loans.
* **Business to Government (B2G)**
* B2G payments include paying taxes and fees.
* **Government to Government (G2G)**
* Payments between two government entities (i.e. between Ministries/Departments and public sector institutions).
Government to Government (G2G) are not covered in this specification and will be covered in a later phase.
## Government-to-Person Payment Principles
The implementation of the Payments Building Block should adhere to the following principles, particularly as it relates to Government-to-Person (G2P) payments:
### Beneficiary/Recipient-related Principles
* Beneficiaries can receive their payment through a fully functional account that allows them to save and make payments using an associated payment instrument with general acceptance.
* They can choose the payment service provider and payment instrument through which they receive their payments based on their informed choice; they can use the same account for multiple G2P payments, make Person-to-government (P2G) payments and easily switch if desired.
* On-boarding to their payment method is low cost and easy with account opening requirements that are available to recipients and with no opening fees; a payment instrument is provided to the recipient at no cost.
* The Integrated Financial Management Information System (IFMIS) is used to process government payments against budgetary allocations. It supports:
* the Treasury Single Account (TSA) that aggregates all incoming government receipts and disburses all government payments;
* budget management to ensure budget compliance, tracking, and reporting. The IFMIS provides the Ministry of Finance with a unified view of the government’s budget execution.
* The payment instrument is easy-to-use and generally accepted, and the overall costs for using it do not result in increased costs for the beneficiary in comparison to other forms of payment.
* Beneficiaries are well informed, their account/data is protected, and have access to redress. They know when, where, and how many payments will be made and understand how their payment method works, its costs, how to use their payment instrument, and how to access their payment. They can access and know how to access effective grievance redressal mechanisms, their funds are secured, and their data privacy is ensured.
* Beneficiaries can easily access their funds. They are able to cash out their funds at any time at a wide range of conveniently close financial access points. At a reasonable and clearly communicated withdrawal fee or at no cost.
* Beneficiaries are included regardless of gender, race, or other immutable characteristics, through at least one of the payment methods used; gender gaps are considered in the design.
### Infrastructure and Systems-related Principles
* The leveraged infrastructures and systems are shared across G2P programs and payment streams, as well as other use cases, avoiding the implementation of systems to exclusively deliver G2P payments. They are scalable and have cyber security arrangements in place.
* Common ID provides access to multiple programs; the national ID system has high coverage and quality; it allows government agencies and payment service providers to validate recipients’ identities; it enables data sharing across government agencies.
* Payment processing systems unlike social protection management information systems, pension, and payroll systems will not include gender-disaggregated data.
* The payment systems are interoperable to maximize the potential of the available infrastructure to recipients; interoperability arrangements exist for Integrated Financial Management Information System (IFMIS), Treasury Single Account (TSA), banks, and non-banks covering most channels and instruments.
* There is no manual intervention in the disbursement process and the entire payments flow is Straight-Through-Processing, including the reconciliation of payments. Payments are made without delays.
### Payment Services Provider-related Principles
* Payment service providers have a strong and long-term, predictable business case or incentives to deliver payments and provide choice.
* A large variety of bank and non-bank financial institutions operating in a competitive market are used to deliver G2P payments.
* Agents of bank and non-bank financial institutions are accessible to G2P payment recipients.
## Mapping Based on Level of Maturity
The following use cases can be mapped to the Payments Building Block capabilities as follows.
Capabilities
Payment Infrastructure Scenario
User journey
Use Cases
Destination Channel
G2P
Scenario 1-4 & 6
Payment - Unconditional Social Cash Transfer (direct payment based on family relationship)
Payment - registration of birth (Postpartum and Infant Care)
Mobile Money.
## Payment Infrastructure Deployment Scenarios
### Regional Switch vs Country Switch
A Payment Switch is the software and hardware system that provides routing between regulated entities in a Payments Scheme.
Domestic payment switches have specific economic characteristics and may not reach adequate economies of scale. Whilst costs can be passed onto customers, without sufficiently low charges, volumes may remain perennially low. Domestic switches facing this scenario thus remain under-utilized, costly, and under-capitalized. In recent years, the concept of Regional payment switches has gained some traction with new efforts realized or underway across the Southern African Development Community (SADC), West African Monetary and Economic Union (UEMOA), East African Community (EAC), and Economic and Monetary Community of Central Africa (CEMAC).
Regional switches (which may serve as a common resource for multiple countries) often rely on pre-existing arrangements between Central Banks, regional Commercial Banks, or a combination thereof. When multiple currencies are in play, a reference currency or a basket of currencies must be chosen for regional settlement accounts to be viable. Settlement arrangements are vital to the viability of a regional switch. A Regional switch may also integrate financial transactions from countries that already have domestic payment switches (like a switch of switches).
Regional switches may take on any and all use cases or may be restricted to specific use cases, for example, Large Value Transfer or B2B trade. Because regional trade drives economic activity, regional switches often go hand in hand with the portability of business and consumer credentials (i.e. relating to Customer Due Diligence), trade policy, and movement of labor.
### Payment infrastructure scenarios
The Payments Building Block sits between the government account systems (i.e. at the Ministry of Finance or Central Bank) and the public or private switching available in the market. As such the Payments Building Block is assumed in each, but not shown. The primary focus in describing these scenarios is on the relationship between payment schemes, banking institutions, and government institutions. This section describes what is available in-country.
| **Infrastructure Scenarios** | **Suggested Approach** |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
Payment Infrastructure Scenario 1 Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks in different countries in a region.
| Government should leverage the regional payments switch (scheme) to enable all use-cases. This may also imply important developments of a standardized Customer Due Diligence (CDD). Note that while a State owned bank is shown in the diagram below, the option exists for the Government to designate a specific Commercial bank, or to have the funds flow directly from the Ministry of Finance (Treasury) assuming such Treasury payment functionality can be supported by the Regional Switch. |
|
Payment Infrastructure Scenario 2 A payment switch connecting financial service providers such as banks to non-banks including mobile money providers is in place and actively working.
| Government should leverage the existing switch to enable payments use-cases to reach mobile money providers. There may be a State Owned Bank (2-A) or not (2-B). |
|
Payment Infrastructure Scenario 3 A payment switch is in place in the country or is in the process to be deployed but non-banks, including mobile providers are not connected to it.
|
Government should leverage third-party aggregators or bilateral integrations to enable payment use-cases to reach mobile money providers.
|
|
Payment Infrastructure Scenario 4 A payment switch is not place or in the process of being deployed
| Government should leverage third-party aggregators or bilateral connections to enable payment use-cases to reach mobile money providers |
|
Payment Infrastructure Scenario 5 Government makes G2P payments using Central Bank Digital Currency (CBDC) .
| The Central Bank distributes the funds for the CBDC accounts via regulated entities (e.g. Payment Service Providers). |
|
Payment Infrastructure Scenario 6 Citizens have CBDC accounts directly with the Central Bank or other accounts with other payment service providers
| The Central Bank sets up limited accounts for each person, providing a base level of access and functionality. Such accounts may be denominated in country currency (fiat) or CBDCs. This scenario places more responsibility on government structures and is not often considered (outside of Postal Banks and the like). |
Under each of these scenarios, there are different setups possible that relate the key roles played by the Programmatic Ministries (e.g. Ministry of Education or Pension Program), the Ministry of Finance, the Central Bank, and the existing Payment Switch.
The flow of funds and the flow of data are separate but equally important and they have a number of interactions.
#### Payment Infrastructure Scenario 1
Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks.
#### Payment Infrastructure Scenario 2-A
Scenario 2-A and Scenario 2-B cover the concept of separating flows of data from accounting flows.
The Central Bank receives the funds transfer advice from the Treasury and the data from the Ministry of Health and does the steps of breaking it into bulk, based on rules of capacity of source and destination systems. Payments are then routed “on-us” or to the external financial providers “off-us” via a payment switch or similar mechanism.
#### Payment Infrastructure Scenario 2-B
The Central Bank plays a key role as a participant in the Payment scheme and routes the payment details and funds via a shared service of the payment switch. The same logic of break-bulk applies and with all transactions effectively “off-us”.
#### Payment infrastructure scenario 3
Government should leverage third-party aggregators to enable payment use cases to reach mobile money providers
#### Payment Infrastructure Scenario 4
A payment switch is not in place or in the process of being deployed. Government should leverage third-party aggregators or bilateral connections to enable payment use cases to reach mobile money providers. In the bilateral connection scenario, each mobile money provider in the country would connect to the government portal through APIs, enabling a seamless transfer of funds to end users (in the case of G2P payments) or the receiving of funds from end users (in the case of P2G payments) and facilitate reporting, reconciliation and settlement processes.
%20\(1\)%20\(2\).png)
#### Payment Infrastructure Scenario 5
The Central Bank mints digital currency and distributes funds via regulated entities (e.g. Payment Service Providers), and in the case of G2P sends funds to destination accounts known to the Ministry of Finance. Account information is unitary and unique for all beneficiaries (e.g. citizens) but the Central Bank does not “hold” account balances on an individual basis.
#### Payment Infrastructure Scenario 6
The Central Bank directly provides Digital Accounts for all people (Citizens) and Treasury routes funds to the relevant accounts (uniquely and unitarily held by people).
* For this payment use case, the most common scenarios currently in place are 1 to 4, scenario 5 and 6 could be envisaged later.
* In Scenario 2B it is assumed that the Payment Switch is run by the Central Bank.
* In Scenario 2A and 3, it is assumed that the Payment Switch is an independent part outside the Central Bank.
# 3 Terminology
Terminology used within this specification.
Several elements of the glossary are based on the terminology defined by the [level one project](https://www.leveloneproject.org/wp-content/uploads/2020/07/L1P_Guide_2019_Final.pdf) and [ITU DFS Glossary](https://www.itu.int/en/ITU-T/focusgroups/dfs/Documents/201701/ITU_FGDFS_DFS-Glossary.pdf)
### **Account Mapper or Account Lookup Directory Service**
A dynamic directory matching beneficiaries’ unique identifier and their account numbers enable multiple programs to direct payments to the same account and beneficiaries to switch payment service providers. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases.
### **Authentication**
The validation of user credentials for the purpose of system login and basic access.
### **Aggregators**
Act as payment facilitators for billers by onboarding multiple billers on their platform and are responsible for, connecting with PSPs and FSPs on behalf of Billers, often, also communicating specific Bill IDs to the consumers to collect amount through their respective platforms and settling the collected amount with the billers.
### **Authorization**
The permission given by the Payer or entity to make a Payment.
### **Base Currency Model**
A single currency to which all other currencies are converted for processing
### **Beneficiary**
A single currency to which all other currencies are converted for processing
### **Billers**
Entity responsible for: Generating Bills with Bill ID’s in PSP’s identifiable format, distributing Bills to the customer (either directly or via another service / channel), marking bill as paid upon confirmation from Payment service provider.
### **Bulk Payments**
A Payment from a single Payer to multiple Payees, for example, cash transfer programs from a government or non-governmental organization to a set of beneficiaries.
### **Currency Conversion**
The process of exchanging one currency for another based on current exchange rates.
### **End User**
The customer of a digital financial services provider. The customer may be a consumer, a merchant, a government, or another form of enterprise.
### **Financial Management Information System**
The budget management system of the government treasury which ensures that government (Ministries, Departments, Agencies) payments are processed within the approved budget and releases.
### **Financial Services Providers (FSPs)**
A financial services provider refers to one that is licensed by a regulatory authority to provide transaction accounts that hold customer funds and are used to make and receive payments. Digital Financial Services Providers (DFSPs) have relationships with consumers, merchants, and other enterprises, and provide digital financial services to End Users.
### **Independent Currency Model**
A system where each currency is processed and settled independently.
### **Interoperability**
The ability of DFSPs participating in a payment Scheme to exchange Transactions with each other. The term may also be used when two systems interconnect.
### **Mobile Money (MoMo)**
A mobile money service includes transferring money and making and receiving payments using a mobile phone. The service must be available to the unbanked, e.g. people who do not have access to a formal account at a financial institution. The service must offer a network of physical transactional points which can include agents, outside of bank branches and ATMs, that make the service widely accessible. Mobile banking or payment services (such as Apple Pay and Google Wallet) that offer the mobile phone as just another channel to access a traditional banking product are not included.
### **Mobile Money Services Provider**
A category of DFSPs that use mobile phones as the access method to provide transaction Accounts to End Users.
### **Payee**
The recipient of funds in a payment transaction.
### **Payer**
The person/organization whose account is debited in a payment transaction.
### **Payment**
Exchange of funds, credentials, and other necessary information to complete an obligation between End Users. A transfer is an example of a payment.
### **Payment Alias (also, Payment address)**
An alias may include phone numbers, email addresses, or other handles. They may include globally unique URIs and may be chosen by the user. These are increasingly seen in new payment systems. Within systems, the payment alias points to an underlying payment account address, specifically and uniquely located within a payment scheme. A payment address may be different from the underlying account address, depending on the payment scheme rules but is often the same thing.
### **Quick-Response (QR) Code**
A method of encoding and visualization of data, which are machine-readable. There are multiple QR models.
### **Routing**
The process by which a route to a payment address is determined. The mechanism of sending payment information across different systems. This is sometimes used interchangeably with addressing.
### **Settlement**
The process of transferring funds between parties to complete a financial transaction.
### **Switch**
A processing entity in a payments system that routes a Transaction from one DFSP to another DFSP. A system may operate its own Switch, or this function may be done by one or more third parties
See for reference:
An entity which receives transactions from one provider and routes those transactions on to another provider. A switch may be owned or hired by a scheme or be hired by individual providers. A switch will connect to a settlement system for inter-participant settlement.
See for reference:
### **Transaction**
A reference to the entirety of the exchange, including a Payment but may also include information between the Payer’s DFSP and the Payee’s DFSP.
### **Treasury Single Account**
A Treasury Single Account (TSA) is a unified structure of government bank accounts that gives a consolidated view of government cash resources. Based on the principle of unity of cash and the unity of treasury, a TSA is a bank account or a set of linked accounts through which the government transacts all its receipts and payments. The principle of unity follows from the fungibility of all cash irrespective of its end use. While it is necessary to distinguish individual cash transactions for control and reporting purposes, this purpose is achieved through the accounting system and not by holding/depositing cash in transaction-specific bank accounts. [This enables the treasury to delink management of cash from control at a transaction level](https://www.imf.org/external/pubs/ft/wp/2010/wp10143.pdf#%3A~%3Atext%3DA%20treasury%20single%20account%20%28TSA%29%20is%20an%20essential%2Cpriority%20in%20the%20public%20financial%20management%20reform%20agenda).
### **Uniform Resource Identifier (URI)**
A unique sequence of characters that identifies a logical or physical resource used by web technologies.
### **Voucher**
A token that entitles the holder to a discount or that may be exchanged for goods or services.
### **Voucher Group**
A voucher group is a characteristic of a voucher that restricts the function or use case that a voucher can be used for. It can also be used as a dimension for reporting on.
# 4 Key Digital Functionalities
Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform.
The Payment Building Block will handle payments processing and orchestration, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions.
The Building Block will enable government programs to channel payments through a shared payments infrastructure to accounts at multiple providers, allowing citizens to choose their preferred Financial Services Provider and switch providers if their circumstances change or they discover a better service.
## 4.1 Payment Orchestration
Payments orchestration provides for end-to-end workflow across different sub-subsystems, enables asynchronous processing, and covers different payment types, use cases, account systems, and channels.
## 4.2 Voucher Management
The Payment Building Block will provide a voucher management system which is responsible for provisioning, storage, issuance, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
## 4.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
The account lookup directory service or mapper simplifies payment routing and is an important component to avoid storing the payment information of the user in the social registry system and preserve the privacy and confidentiality of sensitive information pertaining to the beneficiary.
## 4.4 Payment Request Initiation
The Payment Building Block must allow systems to initiate a payment request. This request could come from two sources: external or internal. An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll).
## 4.5 Payment Gateway
The Payments Building Block should provide a payment gateway which allows different (digital) Financial Service Providers (FSPs) to interoperate.
## 4.6 Payment Portal
The Payments Building Block should provide a Payment Portal which allows users to manage thje full lifecycle of sending and receiving payments
## 4.7 Event Management
The Payment Building block must support different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
## 4.8 Reconciliation
The Payments Building block must implement functionality that provides both internal and external reconciliation services.
## 4.9 Batch Processing
The Payments Building Block should provide batch processing services
## 4.10 Scheduling Services
The Payments Building Block should allow for scheduling services to perform tasks on a regular or repeated basis. This may be achieved through the Schedular BB or through internal timer functions.
## 4.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
## 4.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
## 4.13 Reporting Services
The Building Block should provide reporting services, which may consist of dashboards or analytics reports. These reports should be configurable based on user needs.
## 4.14 Security layer
The Payments Building Block must provide a security layer which protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication.
## 4.15 Bulk payment service
The Payments Building Block must provide bulk payment services. This bulk payment service is invoked in the case of G2P or G2B bulk disbursement.
## 4.16 Support for multicurrency payments
The payments BB supports a multicurrency system where each accepted currency is processed independently without conversion, allowing users to transact directly in their preferred currency. The source building block where the payment request is initiated (for eg in G2P payments this would be the Registry BB and for P2G payments this would be a Biller) will specify the currency for the payment. The treasury will maintain separate accounts and financial records for each currencies.
# 5 Cross-Cutting Requirements
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
## 5.1 Requirements
### 5.1.1 External Identification, Registration, and Enrollment Logic (REQUIRED)
The Payments Building Block assumes that all identification, registration, and enrollment logic is done externally and are compliant with regulated payments and banking systems within a jurisdiction.
### 5.1.2 Registration Requirements (RECOMMENDED)
The Payment System or Scheme in a country may require that participating payor or payee entities, whether health clinics, ministries, or individuals must have been registered with a regulated banking or non-banking entity prior to the use of the Payments Building Block.
### 5.1.3 Compliance Verification (RECOMMENDED)
In the context of Central Bank Digital Currency or Central Bank Accounts for individuals, the payment system block would assume that the regulatory conditions must have been verified for compliance and that payer and payee entities must have been properly registered according to the rules in that scheme.
### 5.1.4 Statutory and Operational Requirements (REQUIRED)
The Payments Building Block assumes that the statutory and operational requirements around accounts (i.e. know your customer/anti-money laundering/counter-terrorist financing) must have been completed by an outside system, which is capable of communicating that status in appropriate timeframes.
### 5.1.5 Real-time Response (RECOMMENDED)
The Payments Building Block assumes that the capabilities of the underlying infrastructure must enable transactions to meet a predefined limit to turn-around-time in real-time response.
### 5.1.6 Validation (REQUIRED)
The Payments Building Block should have the ability to validate against a set of external systems for the status of an account, account address and routing information, confirmation of payment, and various error conditions of accounts and specific payments.
### 5.1.7 Authorization (RECOMMENDED)
During operation in certain modes, the Payments Block would be validating against authorizations/releases or allotments provided by the treasury systems for the source of funds.
### 5.1.8 Eligibility Verification (RECOMMENDED)
Normally, verification of eligibility of beneficiaries for the service should be done in another Block.
### 5.1.9 Budget Availability (REQUIRED)
Budget availability must be checked before voucher creation is requested.
### 5.1.10 Calculation of Payments (RECOMMENDED)
Calculations of payments may depend on several attributes laid down by a specific program.
In an independent multicurrency model, systems must process transactions directly in the selected currency without converting to a base or alternate currency to maintain currency integrity during the transaction process and ensure transparency and reliability for users, reducing the need for cross-currency conversions and associated costs.
### 5.1.11 Payment Systems (REQUIRED)
Payment systems in the market, either provided by a public entity, a quasi-public entity, or a purely commercial player, are required for the functioning of this Building Block.
### 5.1.12 Settlement (REQUIRED)
Settlement (gross or net) must be handled externally to this Building Block.
In an independent multicurrency model, the system must support settlements in the same currency as the transaction, ensuring that the funds transferred match the original transaction currency.
### 5.1.13 Security (REQUIRED)
The Payments Building Block must meet the security requirements described in the Security Building Block.
### 5.1.14 API Mechanisms (REQUIRED)
The Payments Building Block should meet the mechanisms for consuming and publishing APIs as described in the Information Mediator Building Block.
### 5.1.15 Architecture (REQUIRED)
The Payments Building Block must meet the requirements described in the Architecture Building Block.
### 5.1.16 Multicurrency Accounts (RECOMMENDED)
The treasury will maintain separate accounts and financial records for each currency. The source building block where the payment request is initiated will specify the currency for the payment to the Payments building block.
The system must generate reports for payments made in each currency type.
## 5.2 Infrastructure Requirements
### 5.2.1 Mobile Money
Infrastructure Components:
* Account lookup - directory service.
* Payment portal.
* Payment gateway (only in selected scenarios).
* Payment request initiation.
* Notification service.
Mobile money is a destination account to distribute funds to end users (in the case of G2P) or an initiation account to enable users to initiate a payment for government services (P2G) which is facilitated by private commercial entities, typically Mobile Network Operators.
There are three ways that facilitate interoperability between a mobile money provider and a financial service institution (which could be the initiator of a payment - G2P or the receive - P2G): Through a Switch, through a third-party aggregator or through a bilateral integration. We expect one or multiple of these components to be in place to facilitate the use cases discussed in this document but these will remain out of the Payment Building Block.
### 5.2.2 Vouchers
Infrastructure Components:
* Voucher Management System.
* Merchant Ecosystem.
* Merchant Registry.
The Merchant Ecosystem and the Merchant Registry are both outside the scope of the Payments Building Block. The development of the Merchant Ecosystem will be driven by the relevant government institution. The Merchant Registry will be managed by another Building Block.
## 5.3 Payments Building Block Technical Requirements
### 5.3.1 General requirements
Requirement
Type
Secure API exposure: All APIs exposed via secure socket connections (HTTPS).
REQUIRED
Client application authorization tokens: Client applications must send authorization tokens in the authorization header of the request to authenticate users and the API Management Gateway will verify whether the token is valid.
REQUIRED
Transaction receipting: For each disbursement made by the system, a receipt should be issued to the recipient of the funds containing information about the transaction id, transaction date and time, reason for the payment, details of the payer, and the system should store all receipts issued for easy reference and reconciliation.
REQUIRED
Transaction status querying capability
REQUIRED
Display details of the transaction to the payer
REQUIRED
Transaction pre-approval: Prior to processing bulk payment and batch payment transactions, the transaction must be authorized and approved in the system.
REQUIRED
Pre-processing validation of data (well formed data and completeness checks) prior to disbursement.
REQUIRED
Ability to schedule bulk payments
REQUIRED
Support for batch payments
REQUIRED
Ability to lookup payment addresses
RECOMMENDED
Error handling and reconciliation
REQUIRED
Transaction status logging
REQUIRED
Triggering of payments
REQUIRED
### 5.3.2 Voucher Management
Requirement
Type
Batch generation of vouchers
REQUIRED
Voucher uniqueness and randomness: Voucher pin must be unique and unpredictable.
REQUIRED
Secure voucher data storage
REQUIRED
High availability of storage
REQUIRED
Expose APIs that can be invoked by voucher serial number for purposes of querying a voucher, suspending, or unsuspending a voucher.
REQUIRED
Support an API that can be invoked to redeem a voucher using the voucher number.
REQUIRED
Support an API that can invoke payment gateway
REQUIRED
### 5.3.3 Mobile Payments
Requirement
Type
Real time debiting/crediting of mobile money accounts
RECOMMENDED
Regular balance reconciliation with disbursement Agency
REQUIRED
Documented process for partners to dispute transaction records
REQUIRED
Target account identifier or lookup of payment address
REQUIRED
Ability to retrieve details of completed transactions in the batch
REQUIRED
### 5.3.4 Bulk Payments
Requirement
Type
Ability to securely receive bulk payment requests as a single HTTPS request containing data for multiple transactions. The transaction data (with payment instructions data) is passed format and will be compatible with ISO 20022.
REQUIRED
The number of transactions that can be included in a single batch is limited by the size of the file upload and the processing time. If the number of transactions in the file exceeds the file size and could impact the performance of the system, the batch should be split into multiple batch requests.
REQUIRED
Batch files should be verified for any errors and validated as per business rules and regulations before it is accepted as a valid bulk payment file.
REQUIRED
Batch files containing duplicate payments will not be processed and an error will be generated.
REQUIRED
The bulk payment process has to be explicitly triggered by an authorized user. All requests to the Bulk Payment Application API must be authorized and digitally signed by the person initiating the bulk payment request.
REQUIRED
The batch file for bulk payments should contain the beneficiary ID token, and the amount to be paid. The payment information is not included in the batch file for security and privacy but is resolved by the verification and validation component of the bulk payment service by invoking the Account Lookup Directory Service (ALDS/ALS).
REQUIRED
The Bulk Payment Application API shall inspect the batch disbursement file and split transactions into bank payments and non-bank payments (e.g. Mobile money) in separate payment files before initiating the call to the Payment Gateway.
REQUIRED
The status of the bulk payment transaction can be obtained from the event log. The payment status code indicates the status of a single payment transaction and will be according to ISO 20022 Payment status codes table.
REQUIRED
## 5.4 Standards
The following standards are applicable to data structures in the Payments Building Block:
[ISO 20022](https://www.iso.org/standard/57341.html): Universal financial industry message scheme
[ISO 4217](https://www.iso.org/iso-4217-currency-codes.html): Currency Codes
# 6 Functional Requirements
This section lists the technical capabilities of this Building Block.
## 6.1 Payment Orchestration
Payment orchestration is an overarching concern which relates different sub-components or microservices whereby it:
* Explicitly defines and models workflows that span multiple microservices (REQUIRED)
* Provides detailed visibility into how a workflow is performing and identifying where there are issues (REQUIRED)
* Ensure that within a defined workflow, all workflow instances are completed according to plan, even when there are issues along the way (REQUIRED)
Payments orchestration is used to configure the Payments Building Block functionalities to be exercised during a specific workflow and provides functionality such as:
* Sending receipts, notifications, and acknowledgement of receipts in a secure manner to payers and other external applications to receive confirmation of payment made and safekeeping of a record of the receipt that was sent (REQUIRED)
* Provides for auditability of the Payments Building Block to have its controls evaluated for effectiveness, efficiency, and security, including tracing transactions, identifying users who access the system, clearly defined system controls, and compliance with local regulations and global best practices (REQUIRED)
* Schedule and aggregate payments to individuals, allowing programs to stagger payments or combine them with other payments to the same groups of individuals (REQUIRED)
* Enable payment confirmation through secure receipts, notifications, and acknowledgement of receipts to payers and other external applications (REQUIRED)
* Store event logs and audit trails for all transactions processed and their outcomes for monitoring and audit purposes (REQUIRED)
* Validate data structures and content to ensure that it is not missing key pieces of information, including verifying the destination account and triggering a different process if the account is not in good status (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed with throttling to reduce the flow of payment initiated (REQUIRED)
* Coordinate or orchestrate the validation, verification, batching, and scheduling using a set of rules, including options for kicking back to the operator for review or resubmission in certain error cases (REQUIRED)
* Generate reconciliation of accounts based on the successful sending of funds into accounts and reports to show the additional status of systems and payment types and timings (REQUIRED)
* Manage fees in a centralized way and support the use of digital channels to/from end-users, regulated account systems with payment signalling, and notifications by the Financial Services Provider enablers (REQUIRED)
* Scale on transaction performance, transaction latency, reliability, resilience, and graceful service degradation (REQUIRED)
* Support digital tools for query management, including beneficiary queries and complaints about payment services (REQUIRED)
* Route bulk payments through the account holding the funds, either at the government Treasury or a commercial bank (REQUIRED)
* Release funds by the Ministry or payroll master after appropriate approvals (REQUIRED)
* Handle processing and orchestration of bulk payments, including verification of user information, confirmation of payee details, verification of destination account for the beneficiary, fee calculation, and handling of automated bulk transactions (REQUIRED)
* Validate data structures and content to ensure that key information is not missing (REQUIRED)
* Break down bulk payments into batches that can be handled efficiently or create a queue mechanism whereby the list is sequentially processed (REQUIRED)
* Generate reconciliation of accounts based on successful sending of funds into accounts (REQUIRED)
* Provision, issue, activate, and redeem vouchers to support G2P beneficiary payments (REQUIRED)
* Ensure that adequate funds have been allocated to the voucher during provisioning (REQUIRED)
* Allow issuance of vouchers but make them unusable until they are in the hands of the beneficiary (REQUIRED)
* Activate vouchers to make them usable for predefined use cases and for a certain period of time (REQUIRED)
* Handle redemption of vouchers so that beneficiaries receive appropriate benefits from third parties (REQUIRED)
* Generate reports that show the vouchers in their different states as well as the aggregate quantity "stock", which triggers requests for "re-stocking" of vouchers (REQUIRED)
* Authenticate beneficiaries at the point of redemption by checking the Digital Registries Building Block to authenticate the user (REQUIRED)
* Cater for the distribution of social service transfers electronically and cash safely to end users (in the case where the user does not want to use electronic payments it is recommended that vouchers are used) (REQUIRED)
* Creates eVouchers to disburse financial subsidies in a controlled and safe manner (REQUIRED)
* Responds to payers to provide information about the status of the payments (e.g. confirmation of payment, insufficient balance or a mismatch in credentials, transfer failure, etc.), based on the status in the backend applications (REQUIRED)
* Posts status of transactions with traceability information into transaction logs (REQUIRED)
* Tracks due payment and sent payment notifications through alerting mechanisms, along with associated information (REQUIRED)
* Receives triggers for payment collection, posts the amount with relevant disclaimers to the payer, and obtains payer approval (REQUIRED)
* Securely posts the approval, user ID, and associated payment information to the appropriate backend (e.g. mobile, debit/credit card, internet banking entities) of relevant financial applications from banks, employers, and insurance; awaits transfer confirmation from those applications (REQUIRED)
* Searches and provides a logged information-based query of other applications (REQUIRED)
* Able to handle operations in remote and inaccessible locations (REQUIRED)
## 6.2 Voucher Management
The voucher management system is responsible for prectivation, storage, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
### **6.2.1 Voucher Provisioning**
This process traditionally involves the generation of group vouchers against some authorized value (budget release or allotment).
* Each voucher should have a unique secret voucher number, a unique identification number (voucher serial number) indicating its position in an inventory of pre-activated vouchers, and is linked to a fixed amount of value in a particular currency (REQUIRED)\
\
Vouchers will also be associated with a voucher group during pre-activation. Voucher serial numbers will be unique across currencies should there be vouchers of multiple currencies.
* The vouchers should be created with an expiry date and MUST be stored securely (REQUIRED)\
\
All vouchers will be expected to have the same duration of expiry and this expiry period will be from the moment the voucher is activated.
* Alternative design options include dynamically pre-activating a voucher at transaction time and creating variable amounts, but this increases complexity and requires tighter operational controls (RECOMMENDED)
### **6.2.2 Voucher Issuance**
This process involves the Registration Building Block (or any other Building Block for that matter) requesting a voucher number from the voucher management system through an API.
* Once confirmation is received that the voucher has been released it flags the voucher as activated. Design decisions include making this step recommended. Having an additional step increases security by ensuring that the voucher is not used until it is in the hands of the beneficiary (RECOMMENDED)
* Presentation of the voucher. At a minimum, this presentation should have the voucher number as well as the voucher serial number (REQUIRED)\
\
Once a voucher has been issued by the calling Building Block (Registration Building Block) it will be presented to the beneficiary in a form that is determined by the calling Building Block (refer to voucher workflow). The format of the final voucher presentation will be determined by the function of the calling Building Block. It could include the details of the beneficiary, which when placed on the voucher presentation, will help the merchant authenticate the beneficiary at the point of redemption
### **6.2.3 Voucher Redemption**
* Extract and authenticate voucher data (REQUIRED)\
\
In the redemption process, the merchant will authenticate the beneficiary and use a predefined technology (Unstructured Supplementary Service Data, Mobile App, Web Browser) to extract the voucher number and call a redemption API through the relevant calling Building Block. The calling Building Block may also validate the beneficiary details if so required. The Building Block will also be able to validate the merchant and determine the voucher group to which the merchant belongs. Lastly, the calling Building Block will invoke the Payment Building Block Redeem API, through the Payments Building Block API Management gateway, to validate the voucher and if valid to redeem it
* Initiate payment in the merchant or agent wallet or bank account (REQUIRED)\
\
Once the voucher is validated, the Voucher Management System should invoke an API on the Payment Gateway to effect the payment in the merchant or agent wallet or bank account (depending on what was set up at merchant/agent registration). The payment gateway/switch will debit a pre-funded account/wallet and credit the merchant/agent account/wallet. The successful execution will result in the voucher being flagged as consumed/used (REQUIRED)
### 6.2.4 Voucher Management System (VMS) API interface
The details of the VMS APIs are described in the Service API section.
The VMS functionality can be accessed by four external APIs and includes the following functionalities:
* Preactivate a voucher (REQUIRED)\
\
An API call to pre-activate the voucher and get a voucher number, a voucher serial number, and an expiry date.
* Activate a voucher (REQUIRED)\
\
An API call to activate the vouchers by serial number.
* Verify validity of a voucher by serial number (REQUIRED)\
\
An API call to check the validity of a voucher by serial number, or by voucher number and group
* Redeem/consume voucher (REQUIRED)
### 6.2.5 Voucher Storage
The voucher management server shall have a storage subsystem to store the vouchers.
* Vouchers must be stored in secure but high-performance data storage (read access will marginally exceed write access) (REQUIRED)
* The storage of the voucher number will require encryption of data at rest and in motion (unless the channel is encrypted) (REQUIRED)
* Logs generated should NEVER contain the voucher numbers (REQUIRED)
* All access to the voucher database must be logged (REQUIRED)
* Segregation of duty must be done with respect to privileged access to the database and key management of the encryption of the voucher (the level of key management may need to be determined) (REQUIRED)
## 6.3 Account Lookup Services (Account Mapper)
The account lookup directory service identifies the Financial Service Providers (FSP) where the merchant/agent/payee’s account is located.
Account lookup directory service (REQUIRED)
* The account lookup directory service provides a directory that maps the beneficiary's unique identifier (which matches the record in the social registry system) to the transaction account where the beneficiary wishes to receive their G2P payment, allowing the government to address payments to a specific individual. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases. The information will be kept in a tokenised form in the account lookup directory service.
* In the case where there is a national payment switch, the account lookup directory service will be maintained by the FSPs, In the scenario, where there is no payment switch, the government would need to manage the account lookup directory service and provide a mechanism for linking it to the FSPs.
## 6.4 Payment Request Initiation
A request can come from either internal or external sources (REQUIRED)
* An external source could be another GovStack Building Block (e.g. the Registration Building Block or Social Benefits Registry Building Block or Payroll). Either source must be appropriately authenticated and authorized to initiate the request.
The initiation can be synchronous (typically for a single payment) or asynchronous (typically for batch payments) (REQUIRED)
The request must contain at a minimum: the payer identifier, the payee identifier, the amount, the currency, the policy, and the initiating source’s unique transaction ID. In the case of the internal payment request, it should also contain an ID provided by the payment orchestration module (REQUIRED)
Certain processes in the transaction flow might require proof of intent from the user, for example, entering the PIN/Password or pressing an ’accept‘ key to initiate the payment process. Such events and their outcomes should be recorded for audit trail purposes. However, the PINs and passwords should not be stored in logs or if they have to, PINs and passwords should be hashed out (RECOMMENDED)
## 6.5 Payment Gateway
A payment gateway allows different (digital) Financial Service Providers (FSPs) to:
* Interconnect and exchange information (REQUIRED)
* Initiate and receive transactions (REQUIRED)
* Accept or reject transactions and debit or credit end-user accounts (REQUIRED)
## 6.6 Payment Portal
The payment portal will:
* Enable government payers (departments/ministries/public sector bodies) to make G2P payments through one or multiple FSP/payment service providers (REQUIRED)
* Focus on managing, sending, and reconciling payments (REQUIRED)
* Connect government agencies to sending and recipient institutions (REQUIRED)
* Coordinates sending/receiving of payment requests, and approvals (REQUIRED)
* Provide reports across G2P programs, FSPs, and beneficiaries (RECOMMENDED)
* Track payment status and payment history (REQUIRED)
* Register FSPs who are entitled to process payments for G2P payments (REQUIRED)
* Provide restricted access to authorized FSPs to connect to the portal, to process the payments for beneficiaries who are their customers (REQUIRED)
* Automate reconciliation (RECOMMENDED)
* Provide data analytics on payments processed and their status, whether successful or not (REQUIRED)
## 6.7 Event Management
Create logs and notifications for specific actions on any transaction (REQUIRED)
* This functionality supports different events related to triggering specific actions on payment outcomes such as issuing receipts upon successful payment, automating payments in case of bulk transactions, passing information to other Building Blocks as necessary, and handling exceptional cases for instance user/system errors amongst others.
* All notification events shall have a timestamp associated with them and be kept as part of the audit log.
## 6.8 Reconciliation
This should happen at two levels: internally and externally.
* The internal reconciliation will occur between the different sub-blocks within the Payments Building Blocks. In order to achieve internal reconciliation the internal payment request initiator should issue a unique ID that will be referenced by subsequent Payments Building Blocks in all future calls related to the particular payment. This will allow end-to-end tracing of the transaction within the Payments Building Blocks (REQUIRED)
* The external reconciliation is more complex as it involves a calling Building Block which is outside the Payments Building Blocks (such as the Registration Building Block) and a third party (e.g. DFS). Ideally, there needs to be a sequence of IDs that can identify a transaction from start to finish (REQUIRED)
* The nodes that are under the control of the GovStack should be time synched (REQUIRED)
* IDs should be unique, if possible contain the timestamp, and should not roll over across short ranges (REQUIRED)
## 6.9 Batch Processing
* Prepares the batch breakdown on the basis of rulesets governing: which Financial Services Providers shall receive, which payments, and other considerations (REQUIRED)
* Combines payments with other payments to the same beneficiary (REQUIRED)
* Detects batch failure rates (REQUIRED)
Batch files go through a final check to be clean of defects and inconsistencies, to check with external systems as necessary:
* At high volumes, batches are queued for processing (REQUIRED)
* Low-level validation of data types and data completeness (REQUIRED)
* Verification of lookup of accounts to ensure that the account information matches the destination system expectation (REQUIRED)
* Check for inconsistencies (REQUIRED)
* Auto-correct items as possible - consistency logic can be applied to fill in missing formatting if required by recipient banks and telecoms (REQUIRED)
* Errors are kicked back to program level or to an internal data review process (REQUIRED)
## 6.10 Scheduling Services
The payments BB must be able to internally schedule tasks as needed using dependencies to be able to execute workflows (REQUIRED).
## 6.11 Event Logging
Each component of the Payments Building Block should be capable of producing both application and transaction logs. This is important to ensure that the system can be adequately monitored and troubleshooting can be performed efficiently and effectively.
Application or event logs will capture events that each component performs and should contain at least the following information (REQUIRED):
* application/user ID
* event date and time
* terminal identity (name and/or IP address)
* event-related information (message or code)
* event success or failure
The components should also generate transaction logs that capture at least the following information (REQUIRED):
* transaction date and time
* transaction source
* transaction destination
* supplementary data
* transaction status (success, failed, in progress)
The event logs and the transaction logs should NOT capture any sensitive data such as voucher numbers, passwords, etc. (REQUIRED)
There should be an individual transaction record for every payment transaction. For example, if a batch payment process is executed there should be a transaction record for each individual transaction and a separate event log for the entire batch (RECOMMENDED)
## 6.12 Audit Logging
Audit trails are required to provide assurance of the integrity of the requests received and actions taken on these requests. An audit trail is a chronological record of system activities that is sufficient to enable the reconstruction and examination of the sequence of environments and activities surrounding or leading to an operation, procedure, or event in a transaction from inception to final results. The audit trail shall comply with the following requirements:
* Must be automatically captured by the computer system whenever a payment request is created, modified, or deleted (REQUIRED)
* Must be stored in a secure manner and must not be editable by any user, including privileged users. A common approach is to copy/redirect logging to a separate logging server (REQUIRED)
* Each audit trail entry must be time-stamped according to a controlled clock which cannot be altered. The time should either be based on central server time or a local time, so long as it is clear in which time zone the entry was performed (REQUIRED)
* Each audit trail entry must be traceable, i.e. attributable to the individual responsible for the direct data input. Updates made to data records must not obscure previous values and where required by regulation the reason for changing the data must also be recorded (REQUIRED)
* The audit trail must be retained as long as the electronic record is legally required to be stored (REQUIRED)
* The audit trail must be available for internal review/audit (REQUIRED)
* The auditing system must be self-sufficient, i.e. for auditing/regulatory purposes the information stored by a BC must be enough (REQUIRED)
* Audit entries cannot be changed, i.e. the audit BC persisted store should be immutable, and should only support append and not changes or deletes (REQUIRED)
* Audit entries should have a pair of fields to store encrypted data and the encryption key id - these are provided by the submitting BCs (REQUIRED)
* Querying capabilities (REQUIRED):
* Auditor wants to see all activity in the last X days.
* Auditor wants to see all activity of action type Y, or from a certain BC.
* Auditor should be able to request the decryption of encrypted data to an operator.
* Access to the audit store must be securable, so whatever tech is chosen must implement access control mechanisms (ideally that can connect to our Identity and Access Management provider/connector) (REQUIRED)
## 6.13 Reporting Services
The data store will be write-only from the core service and should be read-only by external components (RECOMMENDED)
The data model on the reporting data store can be different from the internal operational data models that the switch uses (RECOMMENDED)
The component provided by the switch will be translating internal events and internal data models to the external data store models. This component can be replaced (RECOMMENDED)
## 6.14 Security layer
Protects the system at the transport and application levels. It provides the necessary APIs for encrypting the data in transit and when stored as well as the digital signatures used for API authentication. The digital signatures are based on public key cryptography using X.509 digital certificates.
At the transport layer:
* All communication between building blocks must use secure protocols to protect the confidentiality and integrity of the data in transit (REQUIRED)
* Strong authentication for parties involved in the transactions should be supported (REQUIRED)
* Confidentiality of personal information related to the transaction – Information on account data, transaction data, payment credentials, and users’/payee’ personal profiles must never be disclosed to any unauthorized party (REQUIRED)
* Non-repudiation of transactions by parties involved (REQUIRED)
* Acknowledgement receipt: this will result in creating a trusted communication path for all transactions between each party, by the end users, telecommunication companies, merchants, or banks (REQUIRED)
* The messages concerning the payment transaction shall be authenticated (REQUIRED)
## 6.15 Data Protection
Use of a hardware security module (HSM) or equivalent to provide cryptographic keys for critical functions such as encryption, decryption, and authentication for the use of applications, identities, and databases (REQUIRED)
## 6.16 Bulk payment service
### 6.16.1 G2P bulk disbursement (RECOMMENDED)
The following are the prerequisites required before bulk payments can be initiated:
Funding requirements:
* The funding requirements must operate within the budget/ceiling.
* The number of funding accounts and the life cycle processes will vary depending on the payment infrastructure scenarios.
Bulk payments file:
* For the salary payments use case, this would be generated by the payroll system.
* For the unconditional social cash transfer use case, this would be generated by a process that would be triggered as per a pre-agreed frequency and the information about the payments to be made would be extracted from the registry (a database containing the information about beneficiaries for a particular government social cash transfer programme). The process of generating this payments file is outside the Payments Building Block.
There are three options for the disbursement:
* Manual process for Government/Department to send the retail payment details to each Financial Services Provider (FSP) (i.e. either by email or other means). This would be the case where there is a lack of interoperability among FSPs.
* Upload the batch disbursement file in the payment web portal for each FSP to retrieve in the case of a centralised Account Lookup Directory Service.
* Automate the disbursement process through the decentralised Account Lookup Directory Service and the payment gateway.
**Option 1**: Retail payment information is sent securely to each Payment Service Provider for disbursement
**Option 2**: Retail payments are accessed via a payment web portal by the Payment Service Provider. The advice/electronic fund transfer request, or paper-based check is issued from the Financial Management Information System to the Trusted Single Account (TSA) -holding Bank.\
Based on this advice, the Bank disburses funds from the TSA into the digital payments system of the FSP which transfers the corresponding funds to the recipient’s account. For the retail payment scrolls, where each agency is responsible for running the payment system - payroll, social welfare payments, etc. - the payment details are not stored in those systems. Instead, the beneficiary’s payment token is retrieved from the Centralised Account Lookup Directory Service and kept in the government payment portal. The payment lists are only shared with the program account holder institution/FSP, Payment Service Provider (PSP), via the government payment portal. The FSP/PSP can log in on the government web portal to access the directory for payments that the FSP needs to effect for each G2P Program.
**Option 3**: Similar to option 2 but the disbursement process to the beneficiary is routed automatically through the payment gateway using the payment token retrieved from the decentralised account lookup directory service.
Bulk payments require the functionality of a Payments Gateway and the functionality therein. It also assumes a separate mechanism by which the recipient account address is determined. In the figure below the “account lookup directory service” functionality maps the concept of identity to the payment alias and from there to the Financial Services Provider routing address. (i.e. wallet address or account address)
### **6.16.2 Interaction with Other Building Blocks (REQUIRED)**
The diagram below shows the interaction with the registries Building Blocks.
At a high level, the payment components used for bulk payments are shown in the figure below.
Figure: Key digital requirements of Bulk Payments expressed as a high-level block diagram. Dotted line for required components.
### 6.16.3 P2G Bill payments
The Billing ecosystem would consist of various actors performing core and secondary processes to complete the bill payment function. Some of the actors only play an auxiliary role to enable bill payment.
**Payments Building Block**
* Main payments facilitator enabling exchange of all financial and non-financial messages related to: Biller/Aggregator Registration o Bill discovery o Bill Payment Confirmation messages
* Biller Discovery through internally referring to the Billers Table updated by PBB Billing sub-Module
* Generation of transaction/ activity reports for registered Billers/ Aggregators
* Registration of Billers in the system
* Allocation of unique Biller IDs / Prefixes
**Billers Table**
* Database of all registered billers
* Internally referenced by the Payments BB each time a Bill Inquiry comes in
* Returns the endpoints for the registered biller/ aggregators
* Biller Details and Account Details from this table would be shared with the Payer FIs during Payments BB and Payer FSP linking for Bill Payments.
**Billers/ Aggregators**
* Getting registered at the PBB – Bill Payment Service
* Returning the correct Bill Details against the Bill Inquiries received from PBB
* Marking the Bills as “Paid” upon receiving Payment confirmation from PBB
* \[Out of Scope of PBB] Performing Bill validation and Bill discovery in their system
**Payer FIs**
* Sending Bill inquiry Requests
* Sending Bill Payment Confirmation
* \[Out of Scope of PBB] Customer validation and Payment debit
## 6.17 Payments Building Block Components
The following components are needed to achieve the technical functionalities of the Payments Building Block.
Many of the components outlined above are used to deliver the Functional Requirements for the Payments Building Block. Components which are not directly related to the delivery of these functions are described here:
### 6.17.1 API Management Gateway
The Payment Building Block provides an API Gateway to handle all the API messaging calls and API access control verification from other Building Blocks to the Payments Building Block and vice versa as well as within the Payments Building Block. All requests from other Building Blocks first go through the API gateway. The gateway then routes requests to the appropriate application/service.
The API Management gateway will:
* Use Identity and access management for authentication.
* Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats.
* Require authentication for all API users.
* Manage access quotas and throttling.
* Log all API calls.
* Allow API providers to limit the rate of consumption for all API users.
* Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.
# 7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
## 7.1 Account Mapper
### **7.1.1 Beneficiary on-boarding**
Field
Type
M/O
Description
requestID
String (12)
M
Globally unique ID
beneficiaries
Object
JSON Array
payeeIdentity
String (20)
M
The functional Id of the beneficiary.
paymentModality
String (2)
O
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
bankingInstitutionCode(BBIC)
String (11)
C
Beneficiary Bank Institution code that will receive the address. This is conditional as it will only be present in case of bank account, mobile money account and digital wallet ID
financialAddress
String (30)
O
Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
### **7.1.2 On-boarded beneficiary**
Field
Type
M/O
Description
requestID
String (12)
M
Globally unique ID
registerRequestID
String (12)
M
Referenced GUID of original request by Source BB to register a beneficiary.
rumberFailedCases
Number
M
The number of cases failed. 0 if none, otherwise integer value
failedCases
Object
O
JSON Array containing the list of FunctionalIDs and Payment Modalities that were not updated in the ID Mapper.
payeeIdentity
String (20)
M
The functional Id of the beneficiary.
bankingInstitutionCode
String (11)
C
Beneficiary Bank Institution Code (BBIC). The beneficiary bank institution code. This is conditional as it will only be present in case of bank account, mobile money account and digital wallet ID
paymentModality
String (2)
M
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
failureReason
String(100)
O
Description of why this particular record failed to add
The relevant bill details including biller ID, Name, Bank Institutional Code (BIC), Status, Amount with due date and after due date, *Currency (multicurrency use case)
billerId
String (10)
M
Biller Id
billerName
String (10)
M
Biller Name
billStatus
String (10)
M
Informs the status whether paid or unpaid
dueDate
Epoch
M
currency
string(3)
M
Needed in multicurrency operations
amountonDueDate
Integer
M
The amount at which the consumer needs to pay bill with due date.
amountAfterDueDate
Integer
M
Amount calculated after due date.
### **7.4.2 Billers table**
The Biller Table may need to include the following fields:
| Fields/ Records | Description | Provided/ Generated By |
| --------------- | -------------------------------------------------------------- | ---------------------------------------- |
| Unique ID | Prefix allocated to every entity directly registering with PBB | PBB Billing Module |
| Biller Details | Records Biller Details | Biller/ Aggregator |
| Biller FSP | Recorded Biller’s Bank Details | Biller/ Aggregator |
| Bill ID Details | Maximum number of Digits in Bill ID | Biller/ Aggregator |
| Biller Status | Active/ Inactive | PBB Billing Module |
| End-Points | Addresses to send requests | Biller/ Aggregator Technology Partner |
| Response Codes | Mapping of codes received and sent to Billers/ Agg. | PBB Billing Module + Biller Tech Partner |
# 8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionalities that should be provided by any implementation of this Building Block.
The [GovStack non-functional requirements document](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.
The tests for the Payments Building Block can be found in [this GitHub repository](https://github.com/GovStackWorkingGroup/bb-payments/tree/main/test/openAPI).
The following pages cover service API references for:
* [**8.1 Government to Person (G2P) payments**](/8-service-apis/8.1-government-to-person-g2p-payments)
* [**8.2 Voucher Management**](/8-service-apis/8.2-voucher-management-apis)
* [**8.3 Person-to-Government (P2G) payments**](/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments)
* [**8.4 Government-to-Business (B2G) payments**](/8-service-apis/8.4-government-to-business-g2b-payments)
* [**8.5 Business-to-Government (B2G) payments**](/8-service-apis/8.5-business-to-government-b2g-payments)
# 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 %}
# 8.2 Voucher Management APIs
The first API in the section below is used to request for a voucher with a specific value, currency, and purpose. The server responds with a voucher number, serial number, and expiry date. The second call activates the pre-activated voucher. The third call processes voucher redemption, crediting the merchant if valid. The fourth APIs allow for voucher status checks.
### 8.2.1 VoucherPreActivation
#### a) VoucherPreActivation()
The VoucherPreActivation API is used by non-Payment Building Blocks in the GovStack Framework to request for a voucher to be used. This call reserves the voucher (for a period, which is to be implemented). This API requests a single voucher from the voucher server that can be used for a future redemption process. The caller sends an amount, a voucher group (depending on the use case), the currency, and the name of the calling GovStack Building Block. If the API call is successful, the Payment Building Block will respond with a voucher number, a voucher serial number, and an expiry date.
{% openapi src="/files/akKaWsoHkYroeiiaezPy" path="/vouchers" method="post" %}
[VoucherPreactivationRequest.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/5DAjkyEGbHIR2ib2AOI8/VoucherPreactivationRequest.yml)
{% endopenapi %}
**b) Create\_Vouchers\_Response()**
Description This is the API called by the Voucher Engine to return Voucher Details once vouchers have been created in the Voucher Engine.
{% openapi src="/files/kymL9dFqJRQwqj2ZbVnb" path="/voucher-details-return" method="post" %}
[VoucherCreationResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/hCypOGDDDJDof6D3XKTf/VoucherCreationResponse.yml)
{% endopenapi %}
### 8.2.2 VoucherActivation
#### a) Voucher\_Activation()
The VoucherActivation API is used by non-Payments Building Blocks in the GovStack Framework to activate a pre-activated voucher. This second function call is intended to ensure that the voucher is only activated when it is disbursed. This API requests for the activation of a voucher when the caller sends the voucher number to be activated. If the API call is successful, the activation is confirmed, and the voucher can now be used by the beneficiary.
{% openapi src="/files/hNbVGyfbAq5Qp2treCMB" path="/vouchers" method="put" %}
[VoucherActivate.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/eEWF9MTBXOr65Nd87Fc8/VoucherActivate.yml)
{% endopenapi %}
For Batch voucher activation, the voucher activation APIS is used by calling Building Block to activate vouchers in bulk. This may be used for bulk social cash transfers where the recipients receive benefits by vouchers. The calling Building Block is responsible for generating the beneficiary file as well as dispensing the vouchers. The Payments Building Block is responsible for generating and redeeming the voucher codes. Both BBs will have had to have exchanged encryption keys during the implementation phase.
The file provided by the calling Building Block will typically contain a unique identifier, the amount of the voucher required, the currency of the voucher, and the voucher group. While the file format may vary, the recommended file format is an encrypted JSON file.
If the file is properly formatted, the Payments Building Block will respond with a file that contains the unique ID that was sent, the status, the voucher number, the voucher serial number, and the expiry date of the voucher. The response file will also be an encrypted file to ensure the appropriate security of the voucher number.
The calling building block will dispense the vouchers as needed using an appropriate delivery mechanism. The calling Building Block will also be responsible for any verification of the beneficiary during the redemption process. The description of the dispensing of the vouchers once the calling block has received it is outside the scope of the Payments Building Block.
**b) Voucher\_Activate\_Response()**
Description This is the response API called by the Voucher Engine to confirm the status of batch activation back to the calling BB.
{% openapi src="/files/gTJTFvsyMuUlN5puMwsg" path="/callback-url" method="post" %}
[VoucherActivateResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/sdEtWfMvtR9cQElV5rYg/VoucherActivateResponse.yml)
{% endopenapi %}
### 8.2.3 VoucherRedemption
The VoucherRedemption API is used by non-Payment Building Blocks in the GovStack Framework to redeem a voucher. The calling Building Block will capture the voucher number and the voucher serial number from the merchant point. The external Building Block will also acquire the merchant name and payment details from the merchant registry. The calling Building Block will then send the voucher number, the voucher serial number, the merchant’s name, and payment details. The Payment Building Block will verify that the voucher has been activated and has not been used or blocked or canceled. If so, the Payment Building Block will then send a payment request to the funding agency/Financial Services Provider. The Payment Gateway of the Payments Building Block will facilitate the debit of the funding account, and the credit of the merchant as well as handle any intermediary fees. Once the payment has been successfully done the Payment Building Block will mark the voucher as consumed and notify the merchant (and beneficiary if possible).
{% openapi src="/files/GUlYJ2URXiIPyTpg7MNa" path="/vouchers" method="post" %}
[VoucherRedemption.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/rZcIndekG37qvvxVTBZN/VoucherRedemption.yml)
{% endopenapi %}
### 8.2.4 VoucherStatus
The VoucherStatus API is used by non-Payment Building Blocks in the GovStack Framework to check the status of a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to determine the status of a voucher. The Payments Building Block will respond with one of the statuses of Pre-Activated, Activated, Suspended, Blocked, or Not Existing.
{% openapi src="/files/0B9qQSLnxFgYZKwvlVfd" path="/vouchers/{serialNumber}" method="get" %}
[VoucherStatus.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/7t89zWEt8KImDWxj7P1z/VoucherStatus.yml)
{% endopenapi %}
### 8.2.5 VoucherCancellation
**Voucher\_Cancellation()**
Description This API will be called by the Source-BB to update the status of the voucher(s), in the case of cancellation, the status code 03 is sent to the relevant field of the instruction array.
The VoucherCancellation API is used by non-Payments Building Blocks in the GovStack Framework to cancel a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to cancel the voucher.
{% openapi src="/files/IUXMve3eLkypdGI3B2vz" path="/vouchers" method="post" %}
[VoucherCancellation.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/6zjVWFIFCCTjSfILpyHz/VoucherCancellation.yml)
{% endopenapi %}
***
**Voucher\_ Cancellation\_Response()**
Description Response API called by the Voucher Engine to confirm the cancellation of the voucher. The Payments Building Block will respond with a status of Cancelled, Already Cancelled, or Not Existing. The Voucher Cancellation will override the Blocked status and render the voucher permanently unusable.
{% openapi src="/files/eUVlXuWlhJvRaWpK2Spg" path="/vouchers/cancellation/confirmation" method="post" %}
[VoucherCancellationResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/XfcZugQAg2bTJUet4kYu/VoucherCancellationResponse.yml)
{% endopenapi %}
# 8.3 Person-to-Government APIs (P2G) Bill Payments
The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money and vouchers.
#### **8.3.1 billInquiryBiller**
This API is called to inquire about bill details from a Bill Aggregator or Govt Entity.
{% openapi src="/files/PansJNWk0m2kneSdMloT" path="/bills/{billId}" method="get" %}
[billInquiryRequest.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/e9aZJzdzzZemqJCuaU74/billInquiryRequest.yml)
{% endopenapi %}
#### **8.3.2 billrInquiryResponse**
The Payment BB updates the Bill Aggregator or government entity on the status of the Request to Pay.
{% openapi src="/files/wggw2fLjtpKLIbbjdKgw" path="/bills/{billId}" method="post" %}
[v1\_0\_1\_billInquiryResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/dTpeOBdwK4KQ3bCHlYar/v1_0_1_billInquiryResponse.yml)
{% endopenapi %}
#### **8.3.3 markBillPayment**
This API marks a bill as paid.
{% openapi src="/files/d9p4i8OugFALHuGESq2t" path="/billTransferRequests" method="post" %}
[markBillPpaymentRequest.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/ioJvhQKESLIqX6OOjol8/markBillPpaymentRequest.yml)
{% endopenapi %}
#### **8.3.4 billerRtpReq**
The Bill Aggregator or Govt Entity initiates a “Request to Pay” (RTP) through this API.
{% openapi src="/files/i2cjhDNnY6iHRVGsHAVW" path="/billTransferRequests" method="post" %}
[markBillPpaymentResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/nKpqRfpQusUHgX74btLv/markBillPpaymentResponse.yml)
{% endopenapi %}
#### **8.3.5 billerRtpReq**
{% openapi src="/files/Ijrsl5MigugoM6A2XV4N" path="/rtpUpdate" method="post" %}
[billerRtpResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/nRvLpPWoIKIW5VszsufP/billerRtpResponse.yml)
{% endopenapi %}
#### **8.3.6 rtpStatusUpdate**
This API allows the Biller or Aggregator to inquire about the status of its RTP.
{% openapi src="/files/P4TVnG2YVqyBlcRwRqtW" path="/transferRequests/{transferRequestId}" method="get" %}
[rtpStatusUpdateRequest.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/rLPX6shLi5XDm6FqjcmH/rtpStatusUpdateRequest.yml)
{% endopenapi %}
#### **8.3.7 rtpStatusUpdateResponse**
This API allows the Biller or Aggregator to receive the status of its RTP.
{% openapi src="/files/8vhgVuPX4Gnr4jkD75Dm" path="/transferRequests/{transferRequestId}" method="post" %}
[rtpStatusUpdateResponse.yml](https://content.gitbook.com/content/xHCzUyMiFANDxPl3gSMn/blobs/F6DRIj5zUG4GUtuyVZ1H/rtpStatusUpdateResponse.yml)
{% endopenapi %}
# 8.4 Government to Business (G2B) payments
For Government to Business (G2B) transactions the following existing APIs would need to be used:
* Register Beneficiary - The existing Register Beneficiary API detailed in [G2P payments ](/8-service-apis/8.1-government-to-person-g2p-payments)would be able to be used to register a business payment details in the ID Account Mapper, assuming a functional ID for a business can be allocated by the ID BB.
* Update Beneficiary - The existing Update Beneficiary API detailed in [G2P payments](/8-service-apis/8.1-government-to-person-g2p-payments) would be able to be used to update a registered Business payment details in the ID Account Mapper.
* Bulk Disbursement - The existing Bulk disbursement APIs detailed in [G2P payments](/8-service-apis/8.1-government-to-person-g2p-payments) would be able to be used to send a batch of credit instructions for businesses
# 8.5 Business to Government (B2G) payments
For Business to Government (B2G) transactions the following existing APIs would need to be used:
For Invoice Payments
* [billInquiryBiller](https://payments.govstack.global/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.1-billinquirybiller) - The existing API to retrieve invoice details detailed in the [P2G payments](/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used to get bill details from the Bill Aggregator or Govt Entity.
* [markBillPayment](https://payments.govstack.global/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.3-markbillpayment) - The existing API to bill payment detailed in the [P2G payments](/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used to mark the invoice as paid.
For RTP Payments
* [billerRtpReq](https://payments.govstack.global/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.4-billerrtpreq) - The existing API for to initiate a "Request to Pay" (RTP) as detailed in the [P2G Payments](/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used try the Bill Aggregator or Govt Entity to initiate the RTP.
* [markBillPayment](https://payments.govstack.global/8-service-apis/pages/oI4SYyoR2lszsNLkJwDT#id-8.3.3-markbillpayment) - The existing API to bill payment detailed in the [P2G payments](/8-service-apis/8.3-person-to-government-apis-p2g-bill-payments) would be used to mark the invoice as paid.
# 9 Internal Workflows
This section provides a detailed view of how the Payments Building Block will interact with other Building Blocks to support payments.
This section discusses the various processes involved in G2P disbursement, such as beneficiary onboarding into the Account Mapper, bulk disbursements to pre-registered financial addresses, and account pre-validation prior to bulk disbursement. This section includes considerations for a Multiple Independent Currency model.
The following sub-pages cover:
* **9.1** [**G2P Bulk Payment**](/9-internal-workflows/9.1-g2p-bulk-payment)
* **9.2** [**Voucher Payments**](/9-internal-workflows/9.2-voucher-payments)
* **9.3** [**P2G Bill Payments**](/9-internal-workflows/9.3-p2g-bill-payments)
* **9.4** [**G2B Bulk Payments**](/9-internal-workflows/9.4-government-to-business-g2b)
* **9.5** [**B2G Bill Payments**](/9-internal-workflows/9.5-business-to-government-b2g)
# 9.1 G2P Bulk Payment
This section discusses the various processes involved in G2P disbursement, such as beneficiary onboarding into the Account Mapper, bulk disbursements to pre-registered financial addresses, and account pre-validation prior to bulk disbursement. This section includes considerations for a Multiple Independent Currency model.
### 9.1.1 Beneficiary onboarding in Account Mapper
The workflow represents the process of onboarding beneficiaries in the ID Mapper as a prerequisite step before any payment processing can occur. This use case is triggered when a new G2P beneficiary has been onboarded by a G2P program, assigned a Functional ID, and verified as eligible for the social benefit program.
In the Multicurrency case the G2P program which is associated with a payment account in a currency must match the currency of the account the individual receives the payment in. Therefore Steps 1-3 in the below workflow are indicative of steps needed in the **Registration Building Block** to ensure this
{% @mermaid/diagram content="sequenceDiagram
note left of RBB: Functional ID is issued to Beneficiary, Request parameters can be json array for bulk onboarding
note left of RBB: Ascertain currency offered, decide Program ID based on currency and use it for onboarding\
RBB -->> IM: Register\_Beneficiary (Request ID, Source BB ID, Array of Beneficiaries)
IM -->> PBB: Register\_Beneficiary (Request ID, Source BB ID, Array of Beneficiaries)
note left of PBB: Validate parameters, Authenticate source Building Block exists
PBB -->> AM: Register\_Beneficiary (Request ID, Source BB ID, Array of Beneficiaries)
note left of AM: For each Payee Functional ID, Duplicate Check, Register in mapper
AM -->> PBB: Register\_Beneficiary\_Response(Request\_ID, Response Code, Array of Failed cases)
PBB -->> IM: Register\_Beneficiary\_Response(Request\_ID, Response Code, Array of Failed cases)
IM -->> RBB: Register\_Beneficiary\_Response(Request\_ID, Response Code, Array of Failed cases)" fullWidth="false" %}
1. *(Step needed for Multiple Independent Currencies Approach)* The requesting Building Block, ascertains the currency of the beneficiary from those offered by the government.
2. *(Step needed for Multiple Independent Currencies Approach)* The requesting Building Block decides the correct program ID based on the offered currency and the currency to be paid to the beneficiary (they must match)
3. *(Step needed for Multiple Independent Currencies Approach)* The requesting Building Block uses this program ID as the basis for following steps 4-11.
4. The requesting Building Block (RBB) sends a "Register\_Beneficiary" request to the Information Mediator (IM), containing the Request ID, Source Building Block (SBB) ID, and an array of beneficiaries with their Functional ID, Payment Modality, and Financial Address (if available).
5. IM forwards the "Register\_Beneficiary" request to the Payments Building Block (PBB) with the same parameters.
6. PBB validates the API parameters and checks if the Source Building Block is configured in the Payments BB as an acceptable source of the API call.
7. If the parameters are valid, PBB sends the "Register\_Beneficiary" request to the Account Mapper (AM) with the same parameters.
8. Account Mapper checks for duplicate Functional IDs registered by the same Source Building Block and registers the beneficiaries in the mapper if they are not already registered.
9. Account Mapper sends a "Register\_Beneficiary\_Response" to PBB, which contains the Request ID, response code, and an array of failed cases (if any) with descriptions.
10. PBB forwards the "Register\_Beneficiary\_Response" to IM, with the same parameters.
11. Finally, IM sends the "Register\_Beneficiary\_Response" to RBB, providing the final response code and the list of any failed cases with descriptions.
The workflow supports the addition of beneficiaries in the mapper in bulk. The source building block can use the same APIs for individual or bulk onboarding.
### 9.1.2 Pre-validation of accounts prior to bulk disbursement
This flow represents the pre-validation process of accounts in a bulk disbursement scenario. The process involves a Source BB (SBB), the Payments BB (PBB), a Payer Bank (PrBank), and Payee Bank (PyBank). To support multicurrency use cases, the currency parameter must be passed.
{% @mermaid/diagram content="sequenceDiagram
title Pre-validation of Accounts
note right of SBB: Prepare bulk disbursement instructions containing 1. Functional ID 2. Amount 3. Currency 4. Description/Narration 4. Instruction ID
SBB -> PBB: Prepayment\_Validation(Batch\_ID, Payment Instructions)
note left of PBB: 1. Debulking 2. Check each Payee Functional ID in mapper 3. Record Failed Instructions
loop Send Payee Bank wise sub-batches
PBB -> PrBank: Bulk\_ValidateAccount (Batch\_ID, Destination\_BIC, Payment Instructions)
PrBank -> PyBank: Account Validation Request as per Incumbent Scheme Norm
note left of PyBank: 1. Validate A/C exists 2. Validate it can receive Credit 3. Validate Credit limit won't exhaust
PyBank -> PrBank: Account Validation Response as per Incumbent Scheme Norm
PrBank -> PBB: BulkValidateAccount\_Response (Batch\_ID, Array of Failed Instructions)
end
PBB -> SBB: Prepayment\_Validation\_Response(Batch\_ID, Array of Failed Instructions)" fullWidth="false" %}
1. The process begins with the Source BB (SBB) preparing bulk disbursement instructions containing key information such as the Functional ID, amount, currency (for multicurrency), narration, and instruction ID.
2. SBB sends these instructions as a pre-payment validation request (Prepayment\_Validation) to Payments BB (PBB).
3. Upon receiving the request, PBB performs several actions, including debulking the instructions, checking each payee's Functional ID in the mapper, and recording any failed instructions.
4. PBB then sends payee bank-wise sub-batches for validation in a loop. For each sub-batch, PBB sends a bulk validate account request (Bulk\_ValidateAccount) to the Payer Bank (PrBank), including the batch ID, destination BIC, and payment instructions.
5. PrBank forwards the account validation request to the Payee Bank (PyBank) as per the incumbent scheme norm.
6. PyBank performs several validation checks, such as confirming the account exists, verifying that it can receive credit, and ensuring that the credit limit won't be exhausted.
7. PyBank sends an account validation response back to PrBank, adhering to the incumbent scheme norm.
8. PrBank then sends a bulk validate account response (BulkValidateAccount\_Response) to PBB, containing the batch ID and an array of any failed instructions.
9. Finally, PBB sends a prepayment validation response (Prepayment\_Validation\_Response) to SBB, including the batch ID and an array of any failed instructions.
This flow ensures that the accounts involved in a bulk disbursement transaction are valid and capable of receiving the specified credits before processing payments, reducing the risk of failed transactions and improving overall efficiency.
### **9.1.3** Bulk Disbursement into a Financial Address pre-registered in the Account Mapper
The workflow depicted below illustrates the process of bulk disbursement into financial addresses, such as bank accounts or mobile wallets, that are pre-registered in the [Account Mapper](/3-terminology#account-mapper-or-account-lookup-directory-service). This use case is triggered when the Source BB submits a batch for processing of payments to the Payments BB.
Pre-conditions: Functional IDs intended to be recipients of funds must be pre-registered in the Account Mapper. All the financial addresses must be validated before a payment is disbursed.
Data Inputs: Source BB provides relevant confirmation to the Payments BB to begin credit transfer for successfully pre-validated accounts.
{% @mermaid/diagram content="sequenceDiagram
title Bulk Disbursement into an online Financial Address
SBB ->> PBB: BulkPayment(Batch\_ID, Payment Instructions)
PBB ->> PrBank: getAuthorization()
PrBank ->> PBB: getAuthorization\_Response()
loop Send Payee Bank wise Sub-Batches
PBB ->> PrBank: BulkPayment\_ReceiverFI(Batch\_ID, Destination\_BIC, Payment Instructions)
end
note over PrBank: Payer Bank processes each Receiving FI Batch and processes instructions as batch or single instructions, depending on available transaction rails.
PrBank ->> PBB: BulkPayment\_StatusPush(BatchID, Credit Instructions)" fullWidth="false" %}
1. The process starts with Source Building Block (SBB) sending a BulkPayment request containing a Batch\_ID and a set of payment instructions to the Payment Building Block (PBB).
2. PBB checks if liquidity was provisioned before this batch is executed and if sufficient liquidity was provisioned. If this is the case, PBB proceeds to de-bulk crediting batches by the receiving institution.
3. PBB then requests authorization from the PrBank by sending a getAuthorization() message.
4. PrBank responds with a getAuthorization\_Response() message, granting the required authorization to PBB.
5. PBB begins sending payee bank-wise sub-batches to PrBank in a loop. For each sub-batch, PBB sends a BulkPayment\_ReceiverFI message containing the Batch\_ID, Destination\_BIC, and payment instructions.
6. The Payer Bank (PrBank) executes these batches through existing rails.
Exceptions: Some accounts might have been pre-validated or part of the crediting batch but cannot be credited by the payee bank for some reason. For such accounts, funds must be returned to the payer bank and credited back into the Source BB's Settlement Account through a separate process.
In order to facilitate the transfer of funds from the disbursement organisation (the payer) to the mobile money provider, the mobile money provider would need to be connected to the payment gateway/switch. Should this connection not be in place, the disbursement could be facilitated by a third-party aggregator or there would need to be a bilateral connection between the payer’s Financial Service Provider and the Mobile Money Provider.
# 9.2 Voucher Payments
The Voucher Management System supports three workflows for voucher payments:
1. administration (voucher provisioning and merchant registration),
2. voucher issuing (pre-activation and activation),
3. redemption use cases as shown in the diagram below.
These use cases and the relationship between each one of them are shown and further described below.
The use cases are described in the diagram below:
{% @mermaid/diagram content="graph TD
Voucher\_provisioning --> Voucher\_Printing --> Merchant\_Redemption
Voucher\_Printing --> Agent\_Cashout
Merchant\_Registration --> Merchant\_Redemption" fullWidth="false" %}
### **9.2.1 Voucher administration**
These processes are usually done prior to the issuance of the voucher to ensure a smooth flow at the point of issuance.
The Admin processes for the Voucher Management Server cover the lifecycle of the vouchers and are typically performed by a privileged user (this may be done through User Interface or an API). These processes include but are not limited to creating voucher groups, provisioning vouchers, suspending vouchers, un-suspending vouchers, validating vouchers, key management, and purging of used vouchers.
#### Voucher Provisioning
This function will be done by an administrator (privileged user). It will typically be triggered by the deposit of funds in a funding account, thus the source account. Voucher provisioning creates a conditional right to funds and an inventory of issued vouchers. Other processes related to this are voucher inventory management, voucher suspension, and voucher purging.
#### Merchant Registration
In order for efficient redemption of vouchers merchants MUST be registered in advance to create a network of trusted providers. This registration is assumed to be managed by the Registration Building Block, The account verification of the merchant can be done at registration or during redemption subject to a configuration.\
\
During the registration process, merchants MAY also be assigned to different voucher groups depending on the required function that has been implemented. For example, there may be a voucher group for schools. This implies that vouchers of this type can only be redeemed at schools. This also requires that the user flow system at which the voucher is issued is aware of these voucher groups and is able to send the appropriate request to the Voucher Management System.
#### Agent Registration
In markets where cashouts are being used, it is expected that the Registration Building Block will register agents in a similar way.
#### Voucher Groups
Depending on the requirement it should also be possible to set up multiple voucher groups. Vouchers in the same voucher group will have similar characteristics and are labeled with a specific voucher group name. During voucher provisioning, a voucher can be created and attached to a single voucher group. When a voucher is requested (using the pre-activation API) it is expected that the voucher group will be one of the parameters set.
#### Voucher Issuing
Voucher issuing is triggered by the Registration Building Block which will determine whether the conditions of issuance have been met. The calling Block will determine the denomination and voucher group of the voucher to be issued. The voucher number and the voucher serial number that is issued can be presented to the beneficiary in multiple ways including but not restricted to encoding in the form of QR codes, bar codes, printed vouchers, or even SMS. This is outside the scope of the Payments Building Block. It is expected that Building Blocks through which the voucher is redeemed will also be able to decode the voucher.
### **9.2.2 Voucher Activation workflow**
The voucher activation flow is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Activation v3
Source BB->Payment BB: Activate voucher
Payment BB-->Source BB: Voucher successfully activated
alt Error 400
Payment BB-->Source BB: Invalid request
end
alt Error 456
Payment BB-->>Source BB: Invalid voucher serial number
end
alt Error 460
Payment BB-->Source BB: GovStack Building Block does not exist
end
alt Error 455
Payment BB-->Source BB: Voucher group exhausted
end
alt Error 500
Payment BB-->Source BB: Internal Server Error
end
alt Error 503
Payment BB-->Source BB: Service Unavailable
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end" %}
#### Flow Description:
* An external Building Block may invoke the Payments Building Block API gateway to pre-activate API on the Voucher Management Server with the amount of the voucher, the voucher currency, and the voucher group. The calling Building Block may optionally send a comment. The comment will be stored by the voucher server. The voucher group will indicate that it is looking for a voucher from a specific voucher group. This API call will be made through the Payments orchestrator.
* The voucher group is typically used for conditional social transfer (e.g. for school fee payment). If any voucher can be used for any purpose, then all vouchers should be created with a generic voucher group (e.g. “GENERAL-PURPOSE”).
* The API returns to get a voucher number, the voucher serial number, and its expiry date. At this point, the voucher will be flagged as Pre-Activated.
* The calling Building Block may render the voucher as a QR code, as a barcode, or even as an SMS text. It is recommended that the voucher should include supplementary data of the recipient. It is also recommended that this data should also be printed in human-readable form so that the recipient can verify the data on the voucher. This data can also be verified at the point of redemption.
* Once the calling API successfully prints/issues the QR code, the voucher can then be activated using the activation API. It is assumed that there will not be a substantial delay between pre-activation and activation to necessitate the need for multiple expiry periods.
#### Alternative:
The voucher could be activated immediately on being requested. This could be controlled at the Payments Orchestrator.
#### Preconditions:
* The calling registration block will determine that all the necessary preconditions are met.
* The most critical precondition is the prefunding which will be done manually at the voucher provisioning stage. Other options that could be prefunding triggered by activation or at redemption are not considered because they are considerably more complex and create additional failure points in the activation of the vouchers.
#### Assumptions/Queries
* It is assumed that only one currency will be used.
* A zero-trust architecture.
* The transaction is not reversible.
#### Post-Condition
The calling Building Block may invoke another payment Building Block API, e.g. initiating an incentive payment for the agent.
### **9.2.3 Voucher redemption workflow**
The voucher redemption process is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Redemption
Source BB (Merchant Interface) ->> Merchant registry: Submit voucher details
Merchant registry -->> Source BB (Merchant Interface): Merchant name and payment details
Source BB (Merchant Interface) ->> Payment BB: Submit voucher and merchant details
alt Error 400
Payment BB-->>Source BB (Merchant Interface): Invalid request
end
Payment BB ->> Payment BB: Check Voucher
alt Error 458
Payment BB-->>Source BB (Merchant Interface): Voucher number already used
end
alt Error 461
Payment BB-->>Source BB (Merchant Interface): Invalid voucher number
end
Payment BB->>FSP: Debit request
alt Error 599
Payment BB-->>Source BB (Merchant Interface): Network connection error
end
FSP->Funding A/c: Debit request
Funding A/c -->> FSP: Debit successful
alt Error 462
FSP -->> Payment BB: Insufficient funds
Payment BB -->> Source BB (Merchant Interface): Insufficient funds
end
FSP->Merchant A/c: Credit Request
Merchant A/c -->> FSP: Credit Request successful
alt Error 463
FSP -->> Payment BB: Cannot credit merchant
Payment BB -->> Source BB (Merchant Interface): Cannot credit merchant
end
Payment BB ->> Payment BB: Consume Voucher
Payment BB ->> Source BB (Merchant Interface): Amount credited to merchant account and voucher is consumed" fullWidth="false" %}
#### Flow Description:
* At redemption, the beneficiary shows the voucher to the merchant or agent.
* The merchant/agent will scan and interpret the medium in which the voucher is presented (this could be a QR code or a barcode or an SMS or even a printed number).
* Voucher redemption Validation: The details presented MAY allow the merchant/agent to authenticate/validate the owner of the voucher.
* The agent will then initiate the redemption process which will call the Payment Building Block API Management Gateway.
* The API Management Gateway will validate the voucher and initiate the payment through the payment gateway.
* If specific voucher groups have been set up, voucher usage may be restricted to specific merchants. An override parameter should also be provided that will allow a Voucher of any voucher group to be redeemed at any merchant.
* Once the payment to the merchant/agent is successful the Payment gateway will inform the API Management Gateway.
* The API Management Gateway will then instruct the VMS API to flag the voucher as consumed.
#### Alternatives:
* Payments could be made through a switch in which case there would be no need for prefunding accounts in each financial institution.
#### Preconditions:
* The merchant must have been registered possibly by the Registration Building Block with their preferred payment method.
* The merchant must have a mechanism (e.g. a mobile APP, USSD app, or SMS option) to verify the beneficiary prior to redemption.
#### Assumptions:
* The app for reading the QR code and redemption is not part of the scope of the Payment Building Block.
* The entire voucher amount is consumed. Partial redemption will not be allowed.
* The amount that is paid to the merchant or agent is debited from a prefunded account.
#### Sample Redemption:
.png)
{% hint style="info" %}
In the case of a physical voucher, the voucher number or the secret number is hidden behind some material that must be scratched away to see the number. The voucher number is also commonly known as the PIN.
{% endhint %}
### **9.2.4 Voucher cancellation workflow**
The voucher cancellation flow is shown in the diagram below.
{% @mermaid/diagram content="sequenceDiagram
title Voucher Cancellation
Source BB -> Payment BB: Cancel Voucher
Payment BB-->Source BB: Voucher Cancelled
alt Error 499
Payment BB-->Source BB: Invalid Request
end
alt Error 463
Payment BB-->Source BB: Invalid Voucher
end
alt Error 464
Payment BB-->Source BB: Voucher is already cancelled
end
alt Error 599
Payment BB-->Source BB: Network connection timeout error
end
" %}
#### Flow Description:
* The calling Building Block will request the API Management Gateway to cancel a Voucher.
* The API Management Gateway will invoke the VMS API to cancel the Voucher.
* The Vaucher Management System (VMS) API interface will check if the Voucher is valid and then cancel the Voucher.
* The VMS API interface will confirm that the Voucher has been canceled.
#### Alternatives:
* If the Voucher does not exist, the VMS API will respond that the Voucher does not exist.
* If the Voucher is already consumed, the VMS API will respond that the Voucher is already consumed.
* If the Voucher is already canceled the VMS API will respond that the Voucher is already canceled.
* If the Voucher is suspended the VMS API will respond that the Voucher is suspended.
* All calls from external parties (e.g. Registration Building Block) to the voucher management system will be initiated through the API management gateway.
* The payment orchestration module may direct transitions between the various functions.
* The discovery service could be called by other building blocks to determine where bank accounts/wallets sit.
* The only function that speaks to the DFS is the payment gateway. Any function that needs to speak to the DFS goes through the Payment gateway.
* The Payment gateway may need to speak to a Number Portability provider.
* Audit trails (transaction logs) capture each event as it happens and are to be used for queries, analysis, and reconciliation.
* Event logs will capture specific events that happen at each node.
# 9.3 P2G Bill Payments
The following types of P2G payments are considered.
* Bill payments such as utilities
* Payments for government services (for example application for a birth certificate)
The following is assumed for bill payment with the Payments BB
* The Bill ID generation or distribution scenario of a jurisdiction is already decided and in place.
* Depending upon the applicable scenario all relevant billers, aggregators or bill payment systems responsible for distributing the Bill IDs to consumers, are also registered with the Payments BB.
* The Settlement of bill amounts is carried out by the relevant payers and payee FSPs.
* The Payments BB will generate a report or allow a data extract that would contain the log of transactions that would be used for settlement of the transactions between the Payer FSP and the Billers or Aggregators FSPs
In order to support multicurrency payments, currency is an important consideration to ensure that bills are paid in the currency raised, as such currency would need to be indicated on bills and payments as indicated in the diagram in section 9.3.3.
The following processes are involved in government bill payments:
### **9.3.1 Biller onboarding**
The biller onboarding would be a one–time prerequisite activity required to be carried out before consumers could pay bills to them.
The main function of Payment BB in this case is allocating unique IDs to the registering entity and ensuring that all Bill Payment related queries are routed to these registered entities.
The relationship between billers and aggregators and how they identify specific bills from the consumers numbers is their responsibility, and is out-of-scope for Payments BB.
Biller/Aggregator Onboarding
#### Pre-conditions:
* The structure of the unique ID is defined including, the length of the unique ID and whether the ID is simply a sequential number or if each digit of the ID identifies any unique entity/actions.
The incoming biller/ aggregator has the required infra to support continuous requests and updates.
#### Flow description:
* Onboarding Request: This step could be a manual process where a representative gathers all the required information from the billers and aggregators and enters it into the system via a UI-based form/ table. (This process may go through the make checker process)
* Unique IDs and Prefixes are generated by the system for each direct biller or aggregator (depending upon the billing ecosystem model). The entire information is saved in the system in the ‘Billers Table’.
* The billers and aggregators are returned a unique ID and prefix allocated to them.
* The billers and aggregators concatenate the unique ID and prefix before the Bill IDs that they generate and share with their consumers.
### **9.3.2 Payer Financial Institution – PBB Linking for Bill Payments**
The Payer FI – PBB linking is a one–time prerequisite activity required before consumers can request bill payment over the Payments BB. Setting up of the front end, UI to take the requests from the consumers would fall under the responsibility of the Payer FI only and would be out of the scope of payments BB
#### Pre-conditions:
* The Payer FSP is enabled for Interbank Funds Transfer (for settlement) – Out of Scope of PBB
* The Payer FSP is equipped with the right infrastructure to communicate with the PBB
#### Flow description:
Payer FSP – PBB Linking would be an offline process comprising formal agreements and the following activities to ensure proper functioning:
* PBB shares the list of Billers and the unique IDs allotted to them with the Payer FSP
* PBB shares its endpoints and required API contracts that need to be setup at the FSP;
* PBB shares the *required* Bank and Account Details of each registered Biller with the FSP for carrying out financial transactions and settlement activities. The biller details could be either manually configured by the Payer FSP at their end or Payments BB could prepare a file and keep it at a central location for Payer FSP to download/ upload it (as decided).
#### Post-conditions:
Once the Payer FSP is setup with PBB for Bill Payment Services then it is expected that it:
* Would be able to accept from its customers Bill IDs of different Billers.
* Would be able to differentiate at its end the exact biller/ aggregator for which the customer has entered the Bill ID.
* Would be able to credit the respective account of the biller based on the account information shared by PBB at the time of linking.
* Would duly notify the PBB of the final status of the Bill Payment Request (successful debit/ Failed debit)
### **9**.3.3 Bill Inquiry & Bill Payment Update via Payment BB
After the completion of the prerequisite setups, the Payment BB is ready to accept requests from the Payer FSPs and retrieve information from and communicate with the Billers, Aggregators, and Government Entities.
#### Main responsibilities of Payment BB in the flow:
1. The PBB would receive the Bill Inquiry as a result of Pay Bill request at a Payer FI – Payer end.
2. PBB would validate the sender of request and send it on to the respective Biller or Govt. Entity to fetch bill.
3. The Payer FSP would then either perform payment confirmation or abort the transaction – in either case it would notify the PBB of the Payment Status
4. Receiving the Payment Status Update the PBB would forward the Payment confirmation to Biller or Govt. Entity
5. PBB sends Mark Bill Paid Advice to the Biller or Govt Entity until a response is received from that site.
6. Upon receiving a response from the Biller or Aggregator, the PBB would notify the Payer FSP of the response.
7. The Government Agency sends an invoice to the payer, detailing the amount owed.
8. The Government Agency also sends a copy of the invoice to the designated Bill Aggregator.
9. The Bill Aggregator then sends the invoice reference number to the Payments Building Block .
10. The payer, upon receiving the invoice, provides the invoice reference number to their preferred Collection Financial Service Provider (Collection Financial Services Provider).
11. The Collection Financial Services Provider (FSP) requests transaction details, including the amount to be paid, currency (for multicurrency) from the Payments Building Block using the invoice reference number.
12. The Payments Building Block, in turn, requests the transaction details from the Bill Aggregator.
13. The Bill Aggregator provides the requested transaction details to the Payments Building Block.
14. The Payments Building Block forwards the transaction details to the Collection FSP.
15. The Collection FSP executes the payment based on the transaction details provided.
16. After completing the payment, the Collection FSP sends the payment reference to the Payments Building Block.
17. The Payments Building Block forwards the payment reference to the Bill Aggregator.
18. Finally, the Bill Aggregator sends the payment reference to the Government Agency, confirming the completion of the payment.
{% @mermaid/diagram content="sequenceDiagram
title Push Payment Flow with Bill Inquiry
title P2G Bill Payment via RTP
participant "Payer FI" as PayerFI
participant PaymentsBB
participant ALS
participant "Bill Aggregator GovtEntity" as BillAggregator
```
BillAggregator->>PaymentsBB: 1. billerRtpReq (txnID, rtpId, billId, requestType, aliasID (C))
PaymentsBB-->>BillAggregator: billerRtpReq (Ack)
alt RTP Type = 00
note over PaymentsBB: Jump to "SEND RTP TO PAYER FI" Step
else RTP Type = 01
PaymentsBB->>* ALS: Bill ID is routed to lookup service.
ALS->>PaymentsBB: Returns back with Payer FI details.
note over PaymentsBB: Jump to "SEND RTP TO PAYER FI" Step
end
note over PaymentsBB, PayerFI: SEND RTP TO PAYER FI
PaymentsBB->>PayerFI: 2. payerRtpReq (txnId, billId, [Bill Details])
PayerFI-->>PaymentsBB: payerRtpResp (Ack)
note over PayerFI: Initiate "RTP Notification Sequence - Customer<->FSP"
PayerFI->>PaymentsBB: 3. payerRtpResp(txnId, referenceId)
PaymentsBB-->>PayerFI: payerRtpResp (Ack)
PaymentsBB->>BillAggregator: 4. billerRtpResp (txnId, paymentStatus, referenceId)
BillAggregator-->>PaymentsBB: billerRtpResp (Ack)
opt If BillAggregator requires status update
BillAggregator->>PaymentsBB: rtpStatusUpdate (txnId, rtpID)_Req
PaymentsBB-->>BillAggregator: rtpStatusUpdate (Status Code)_Resp
end
note over PayerFI, BillAggregator: BILL PAYMENT STATUS STAGE
note over PayerFI: Initiate "LEG2:PayBill Sequence - Customer/FSP"
PayerFI->>PaymentsBB: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Req
PaymentsBB-->>PayerFI: paymentStatusUpdate(Ack)
note over PaymentsBB, BillAggregator: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB->>BillAggregator: markBillPaid(Bill ID, ReceiptNum, PaymentStatus)_Req
note right of PaymentsBB: Payments BB keeps sending Bill Payment Advice to BillAggregator until Response received from BillAggregator
end
BillAggregator-->>PaymentsBB: markBillPaid (Ack)
BillAggregator->>PaymentsBB: markBillPaid(MarkStatus, RespCode(C))_Resp
PaymentsBB->>PayerFI: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Resp
PayerFI-->>PaymentsBB: paymentStatusUpdate(Ack)" fullWidth="false" %}
```
#### 1. Bill inquiry stage
* **Payer FI** initiates the process by querying bill details.
* **Payer FI** requests bill inquiry using `billInq(Txn ID, Bill ID)_Req`.
* **PaymentsBB** validates the request, performing security checks and registration status verification.
* If validations fail, **PaymentsBB** sends an error response to **Payer FI**.
* If validations succeed, **PaymentsBB** identifies the biller and moves to the next step.
#### 2. Biller discovery
* **PaymentsBB** identifies the biller by querying the **Billers Table** using `IdentifyBiller(Prefix)`.
* **Billers Table** provides **PaymentsBB** with the Biller's endpoint information.
* **PaymentsBB** then proceeds to fetch the bill from the **Bill Aggregator/Government Entity**.
#### 3. Fetch Bill
* **PaymentsBB** requests bill details from **Bill Aggregator or Government Entity** using `billInqBiller(Bill ID)`.
* **Bill Aggregator or Government Entity** performs internal checks (e.g., payment status, expiry) and responds with bill details.
* **PaymentsBB** forwards bill details to **Payer FI** for review.
#### 4. Bill Payment Status
* **Payer FI** reviews the bill details and initiates the payment sequence.
* **Payer FI** updates the payment status using `paymentStatusUpdate(Payment Status, Txn ID, RespCode)`.
* **PaymentsBB** acknowledges the update and marks the bill as "PAID" in the request sequence.
* **PaymentsBB** sends payment advice to **Bill Aggregator or Government Entity** until a response is received.
* Once confirmed, **Bill Aggregator or Government Entity** acknowledges the payment and updates the status.
* Finally, **PaymentsBB** notifies **Payer FI** of the successful payment update
### 9.3.4 Payer FI – Customer Bill Payment Flow
{% @mermaid/diagram content="sequenceDiagram
title PayBill Sequence - Customer/FSP
participant Payer as Payer
participant PayerFI as Payer FI
```
note over Payer, PayerFI: LEG 1: BILL PAYMENT REQUEST
Payer->>PayerFI: Pay_Bill_Req (Bill ID)
note right of PayerFI: Forwards billInquiry (Bill ID)_Req to PBB
note left of PayerFI: Receives billInquiry_Resp from PBB
PayerFI->>Payer: Pay_Bill_Resp (Biller Name, Due Date Amount, Currency, Bill Status )
note over Payer, PayerFI: LEG 2: BILL PAYMENT CONFIRMATION
Payer-->>PayerFI: Confirms Bill Payment
PayerFI->>PayerFI: Performs Account Validations Identifies the Biller Account
note over PayerFI: Logs Txn_Success_Ref ID OR Txn_Fail_Ref ID
alt If Validations OK
PayerFI->>PayerFI: Debits Payer's Account
PayerFI->>Payer: Sends Payment Receipt (Txn_Success_Ref ID)
PayerFI->>Payer: Account/Wallet Debited - Bill Paid (Txn_Success_Ref ID)
Note right of PayerFI: Initiates: "(PBB) BILL PAYMENT STATUS STAGE" Calls PAYER BB API -> paymentStatusUpdate
else If Validations KO
PayerFI->>PayerFI: No Debit
PayerFI->>Payer: Sends Txn Failure Message (Txn_Fail_Ref ID)
note right of PayerFI: Bill Paid Status (Txn_Fail_Ref ID)
```
end" fullWidth="false" %}
### 9.3.5 P2G bill payment via request to pay flow
{% @mermaid/diagram content="sequenceDiagram
title P2G Bill Payment via RTP
participant PayerFI as Payer FI
participant PaymentsBB as PaymentsBB
participant ALS as ALS
participant BillAggregator as Bill Aggregator GovtEntity
BillAggregator->>PaymentsBB: 1. billerRtpReq (txnID, rtpId, billId, requestType, aliasID (C))
PaymentsBB-->>BillAggregator: billerRtpReq (Ack)
alt RTP Type = 00
PaymentsBB->>PayerFI: Jump to "SEND RTP TO PAYER FI" Step
else RTP Type = 01
PaymentsBB->>+ALS: Bill ID is routed to lookup service.
ALS->>PaymentsBB: Returns back with Payer FI details.
PaymentsBB->>PayerFI: Jump to "SEND RTP TO PAYER FI" Step
end
Note over PaymentsBB, PayerFI: SEND RTP TO PAYER FI
PaymentsBB->>PayerFI: 2. payerRtpReq (txnId, billId, \[Bill Details])
PayerFI-->>PaymentsBB: payerRtpResp (Ack)
Note over PayerFI: Initiate "RTP Notification Sequence - Customer<->FSP"
PayerFI->>PaymentsBB: 3. payerRtpResp (txnId, referenceId)
PaymentsBB-->>PayerFI: payerRtpResp (Ack)
```
PaymentsBB->>BillAggregator: 4.billerRtpResp (txnId, paymentStatus, referenceId)
BillAggregator-->>PaymentsBB: billerRtpResp (Ack)
opt If BillAggregator requires status update
BillAggregator->>PaymentsBB: rtpStatusUpdate (txnId, rtpID)_Req
PaymentsBB-->>BillAggregator: rtpStatusUpdate (Status Code)_Resp
end
Note over PayerFI, BillAggregator: BILL PAYMENT STATUS STAGE
Note over PayerFI: Initiate "LEG2:PayBill Sequence - Customer FSP"
PayerFI->>PaymentsBB: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Req
PaymentsBB-->>PayerFI: paymentStatusUpdate(Ack)
Note over PaymentsBB, BillAggregator: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB->>BillAggregator: markBillPaid(Bill ID, ReceiptNum, PaymentStatus)_Req
BillAggregator-->>PaymentsBB: markBillPaid (ack)
end
BillAggregator->>PaymentsBB: markBillPaid(MarkStatus, RespCode(C))_Resp
PaymentsBB->>PayerFI: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Resp
PayerFI-->>PaymentsBB: paymentStatusUpdate(Ack)" fullWidth="false" %}
```
### 9.3.6 P2G bill payment with voucher
{% @mermaid/diagram content="sequenceDiagram
title Payment By Voucher
```
participant Payer FI as PR
participant PaymentsBB as PBB
participant Voucher Engine as V
participant Biller as Biller
note over PR: Bill Inquiry is Done - For Bill Payment "Voucher" is chosen as option
note over Payer FI, Biller: BILL PAYMENT STATUS STAGE
PR ->> PBB: voucherRedemptionforBillPayment (BillInquiryCorrelationID, Bill Details, Voucher Secret Code)
note over PBB: PBB receives API Call with Voucher as well as Bill Details.
PBB ->> V: VOUCHER REDEMPTION
note over PBB,V: PAYBB checks that Voucher is valid, Voucher Amount and Bill Amount are same
PBB ->> V: VoucherInquiry(Secret Code)
V -->> PBB: VoucherInquiry_Response
note over PBB: Check Voucher Value, Bill Value, Check Compatibility. If Okay, Redeem. Else, Cancel
PBB ->> V: redemptionWithoutAuthentication_Request
V -->> PBB: redemptionWithoutAuthentication_Response
PBB --x V: destroy V
PBB -->> PR: voucherRedemptionforBillPayment(Status)_Resp
note over PBB, Biller: Mark Bill == "PAID" Req Sequence
loop Mark Bill Payment Advice via SAF
PaymentsBB ->> Biller: markBillPaid(Bill ID, ReceiptNum, PaymentStatus)_Req
note right of PaymentsBB: Payments BB keeps sending Bill Payment Advice to Biller until Response received from Biller
end
Biller -->> PaymentsBB: markBillPaid(ack)
Biller -->> PaymentsBB: markBillPaid(MarkStatus, RespCode(C))_Resp
PaymentsBB ->> PR: paymentStatusUpdate(Payment Status, Txn ID, RespCode)_Resp
Payer FI -->> PaymentsBB: paymentStatusUpdate(ack)" fullWidth="false" %}
```
# 9.4 Government to Business (G2B)
### 9.4.1 Generic G2B Workflow for Registration and Payment
The following diagram shows a happy path generic workflow for Registration and Payments for a G2B scheme:
#### **Assumptions:**
* That the Government Registration Program is a BB such as the [Registration](https://registration.govstack.global/) BB
* KYC - “Know your Customer” is inclusive of KYB “Know your Business”
* All interactions with the Payment BB will go via the [Information Mediator](https://mediator.govstack.global/) BB as per GovStack specification even where not shown for clarity in the workflow
* [Messaging](https://messaging.govstack.global/) or [Scheduler](https://scheduler.govstack.global/) BB’s could be used when defined for notifications
#### **Workflow covers:**
* Registration Flow and storing of Payment Details
* Payment flows
#### **Workflow excludes:**
* Audit
* Unhappy path flows
#### **Key callouts:**
* There may need to be 2 ID’s verified, that of the Business and that of the Individual acting on behalf of the business (TO BE EXPLORED).
* [Identity](https://identity.govstack.global/) BB currently only considered individual ID therefore this has an impact on the current [Identity](https://identity.govstack.global/) BB specification
* Currently in the workflow existing Pay-BB API definitions can be used
### 9.4.2 Example workflow for **Government to Business loan**
In this example the government has a scheme where they provide loans to small businesses on preferential terms to encourage small business development. This example could also apply to small business loans needed for disaster recovery (The UK offered such loans during Covid19).
#### **Assumptions:**
* That the loan scheme is not part of the Payments BB (could be an independent system or BB that is yet to be defined)
* KYC - “Know your Customer” is inclusive of KYB “Know your Business”
* This is giving an example loan scheme but is not inclusive of all steps within that as we are not defining the loan-scheme in this BB
* This example covers a normal Business type loan, it is not intended for guarantee loans where the Government is not the loan provider
* All interactions with the Payment BB will go via the [Information Mediator](https://mediator.govstack.global/) BB as per GovStack specification even where not shown for clarity in the workflow
* [Messaging](https://messaging.govstack.global/) or [Scheduler](https://scheduler.govstack.global/) BB’s could be used when defined for notifications and loan schedules
#### **Workflow covers:**
* Loan Setup and Payment
#### **Workflow excludes:**
* Loan Repayment flows these would be a B2G flow
* Audit
* Unhappy path flows
* Detail of Loan system internal flows
#### **Key Callouts:**
* There may need to be 2 ID’s verified, that of the Business and that of the Individual acting on behalf of the business (TO BE EXPLORED).
* [Identity](https://identity.govstack.global/) BB currently only considered individual ID therefore this has an impact on the current identity BB specification
* Currently in the workflow existing Payments BB API definitions can be used (needs to continue to be assessed with any changes)
# 9.5 Business to Government (B2G)
### 9.5.1 Example workflow of a business paying for government services and refuse collection
In this example the local Government provides a refuse collection service to local businesses this consists of both regular collections and the ability to request additional collections. These services are chargeable by the local Government to the local businesses.
If we look at the existing Person to Government (P2G) payment use-case we see that within this the flows are agnostic of if the Payer is an individual or a business and the ID of the Payer is not within the flows or APIs resolving the concerns that arise in G2B payments that need changes to cater for business scenarios.
[Final Versions of Key Documents | P2G v16Oct23](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/490962995/Final+Versions+of+Key+Documents#P2G-v16Oct23)
Hence we can conclude the following flows would be used:
For the regular bills these would follow the Bill Generation and Bill Inquiry workflows with Bills being sent from the Billing Entity to the Payer who would pay with the reference supplied enabling the Payment BB to reconcile the payments to the Billing table.
For the one off charges this would follow a one-time Request to Pay workflow from the Billing entity to the Payer.
The use of a billing aggregator could also be supported for G2B payments without any adjustments foreseen.
\
# 10 Other Resources
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
### 10.1 Key Decision Log
[A historical log of key decisions regarding this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183435345/Key+Decision+Log+Payments).
### 10.2 Future Considerations
[A list of topics that may be relevant to future versions of this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183402524/Future+Considerations+Payments).
### 10.3 Out-of-Scope Assumptions
[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/6ERMn830).
# Government to Business (G2B) Use Case
#### Overview:
The broad definition of this scenario is payments made to a business from a Government, these are assumed to be single currency. These can be narrowed down to a set of high-level areas:
* Loans – Where the Government makes a payment to a business with an expectation of repayment in whole or in parts with or without interest.
* Allowances- Where the Government makes a conditional payment to a business. E.g. Agriculture allowance.
* Unconditional Payments- Where the Government makes an unconditional payment to a business. E.g. disaster relief.
* Rebates and Repayments – Where the Government makes a payment based on payments previously having been received, e.g. tax refunds.
* Payments for Services - Where the Government pays a business for a service or work done.
* Financial Aid to NGOs - Where the Government pays an NGO financial aid
* Subsidies - This could be considered similar to Allowances but may bring in a dimension of being ringfenced in what it can be spent on or which merchants it can be spent with. This may bring in an element of Vouchers for consideration.
#### Example 1: Agriculture Subsidies
In a country the government wants to encourage responsible farming and water management practices to produce a sustainable agricutural industry in the country. As such Farmer may register for a Subsidie (Grant) payable to help them with the costs of this transformation. This grant is paid out monthly for registered farmers.
When the farmer applies to the grant program they do so through the Government Registration Portal which captures key information such as name of farm, address of farm, size of farm to establish the payments are valid.
At the end of the registration process the Registration portal working with the ID BB creates a functional ID for the farmer and captures the payments details which are passed and stored in the Payments BB ID account Mapper.
{% hint style="warning" %}
Note currently the ID BB only covers Individual Identities rather than legal entity identities, this functionality is on the ID BB roadmap
{% endhint %}
At the end of the month the Government Agriculture Subsidy program sends a bulk file to the payments building block with the Functional ID of each farmer to be paid and the amount to be paid.
The Payments building block process's this bulk disbursement in a similar fashion to a G2P bulk disbursement. Using the ID Account Mapper to look up the relevant financial details for each Functional ID, validating sufficient funds exist in the government account and then sending financial transaction instructions to the Government Bank Core Banking System in appropriate sized batches. The status of each transaction is returned to the Payments Building Block which can then be investigated by the Government systems if needed to understand the status of batches, sub-batches and individual transactions.
#### Key Points:
The existing Payments Building Block Functional requirements for G2P can be used for a G2B use case along with associated APIs
# Business to Government (B2G) Use Case
#### Overview:
The broad definition of this scenario is payments made from a business to a Government. These can be narrowed down to a set of high-level areas:
* Loan Repayments – Where the Business makes a repayment to a Government either in whole or in parts with or without interest.
* Taxation – Where the Business makes a payment to the Government to cover a taxation obligation either one off or regular.
* Services - Where the Business makes a payment to the Government for a service either one off or regular such as refuse collection.
* Fines - Where the Business makes a payment to the Government to cover a fine
* Customs Duties - Where a Business needs to pay customs duties (this scenario really opens up consideration of cross border and forex)
It may be important to consider cross-border/multi-currency payments depending on if the business is in the same country/region as the government.
#### Example 1: Business Tax Payments
In a country the government has an online tax program where business's complete their tax returns digitally.
Once the tax submission has been made by the business it calculates the Tax due and offers the business 2 ways to pay.
1. Pay in a Single Installment online
2. Pay in multiple instalments over a period of time.
For option 1. the Government tax system invokes the payment Building Block with and RTP (Request to Pay) instruction. The Payments BB then allows for immediate payment via the Businesses FSP (Financial Service Provider) and reconciles the payment with the Government Tax system
For option 2. the Goverment tax system splits the payment due into a number of payments and issues a number of bills with a unique reference number consisting of the biller identifier and a unique ID, using the Bill Generation workflow. As each payment is made by the business the Business FSP makes these payments by using the Bill Inquiry and payment workflows
The Payments building block process's these Bill Payments works in a similar fashion to a P2G functionality.
#### Key Points:
The existing Payments Building Block Functional requirements for P2G can be used for a B2G use case along with associated APIs
.png?alt=media)
.png?alt=media)
.png?alt=media)
%20(1).png?alt=media)
.png?alt=media)
.png)
