Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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
Technical Reviewers: Tony Shannon, Saša Kovačević, Riham Moawad, Riham Fahmi, Aare Laponin, Manish Srivastava, Palab Saha, Surendra Singh Sucharia, Arvind Gupta, Gayatri. P., Shivank Singh Chauhan, Gavin Lyons
Initial version
0.9.3
Vijay Mauree, Arnold Kibuuka, Francesco Pasti, James Dailey, Oscar Correia, Dr. P. S. Ramkumar, Khuram Farooq
Reviewers: Sasa Kovacevic, Aare Lapõnin, Anita Mitta, Amy Darling
Feedback incorporated from Technical Advisory Committee review
1.0
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
Terminology used within this specification.
Several elements of the glossary are based on the terminology defined by the level one project and ITU DFS Glossary
| 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.
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 (https://www.leveloneproject.org/wp-content/uploads/2020/07/L1P_Guide_2019_Final.pdf).
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.
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)
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.
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.
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.
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.
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).
The Payments Building Block should provide a payment gateway which allows different (digital) Financial Service Providers (FSPs) to interoperate.
The Payments Building Block should provide a Payment Portal which allows users to manage thje full lifecycle of sending and receiving payments
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.
The Payments Building block must implement functionality that provides both internal and external reconciliation services.
The Payments Building Block should provide batch processing services
The Payments Building Block should provide scheduling services to perform tasks on a regular or repeated basis
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.
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:
The Building Block should provide reporting services, which may consist of dashboards or analytics reports. These reports should be configurable based on user needs.
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.
The Payments Building Block must provide bulk payment services. This bulk payment service is invoked in the case of G2P bulk disbursement.
This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block.
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.
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.
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.
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.
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.
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.
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.
Normally, verification of eligibility of beneficiaries for the service should be done in another Block.
Budget availability must be checked before voucher creation is requested.
Calculations of payments may depend on several attributes laid down by a specific program.
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.
Settlement (gross or net) must be handled externally to this Building Block.
The Payments Building Block must meet the security requirements described in the Security Building Block.
The Payments Building Block should meet the mechanisms for consuming and publishing APIs as described in the Information Mediator Building Block.
The Payments Building Block must meet the requirements described in the Architecture Building Block.
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.
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.
The following standards are applicable to data structures in the Payments Building Block:
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 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.
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.
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)
People to Government (P2G)
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.
The implementation of the Payments Building Block should adhere to the following principles, particularly as it relates to Government-to-Person (G2P) payments:
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.
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 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.
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.
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.
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.
Regional Switch (or a switch of switches) connects financial service providers including banks and non-banks.
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.
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”.
Government should leverage third-party aggregators to enable payment use cases to reach mobile money providers
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.
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.
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.
, 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.
Payment where the payer is a government and the payee is an individual e.g. Social benefits disbursement, government salary payments, Conditional and ).
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, payment of school fees, driving license, utility payments).
The can be mapped to the Payments Building Block capabilities as follows.
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 |
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). |
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 | Payment - registration of birth (Postpartum and Infant Care) | Mobile Money. |
This section lists the technical capabilities of this Building Block.
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)
The voucher management system is responsible for prectivation, storage, activation, redemption, validation, suspension, unsuspension, purging, and reporting on vouchers.
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.
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)
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)
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.
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)
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.
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)
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)
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)
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.
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)
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)
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)
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)
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)
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)
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)
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.
The bulk payment service is invoked in the case of G2P bulk disbursement and should provide the following functionality:
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)
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.
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
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:
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.
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 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.
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.
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.
Once a new G2P beneficiary is onboarded by a G2P Program and assigned a Functional ID, they can be added to the Account Mapper in Payments BB after their eligibility for the social benefit program has been verified.
As the number of beneficiaries can be large, the API supports the addition of beneficiaries in the mapper in bulk. This allows for efficient onboarding and management of multiple beneficiaries at once, streamlining the process and reducing the time required for handling individual beneficiary registrations.
The Register Beneficiary API is invoked by the Information Mediator BB, which is triggered when the Registration BB is registering beneficiaries into the Payments BB's ID Mapper.
a) Register Beneficiary Request()
This is the API that is called by the Information Mediator BB when the Registration BB in turn calls its API for registering beneficiaries into the ID Mapper of the Payments BB.
b) Register Beneficiary Response() - Callback
This is the API that is called back by the Pay-BB to notify the Source BB via the IM BB that all or selected beneficiaries have been uploaded into the ID Mapper.
This is the API that is called by the Information Mediator BB when the Registration BB in turn calls its API for registering beneficiaries into the ID Mapper of the Payments BB.
a) Update Beneficiary Request()
This interface is to be called by the Registry BB (also referred to as Source BB) when an update to either the Payment Modality or Financial Address is required. Payee Functional ID is not updateable and is only part of this call to identify the individual record that needs updating.
b) Update Beneficiary Response()
This is the API that is called back by the Pay-BB to notify the Source BB via the IM BB that all or selected beneficiaries have been successfully uploaded into the ID Mapper.
a) Bulk Payment()
This API is to be exposed by the Payments BB and Payer FSP; it will be called by the Source BB or Payments BB to handover a batch of credit instructions to be processed.
b) BulkPayment_StatusPush()
This API is expected to be invoked by Payer Bank to the Payments BB to provide updates status of a batch or individual credit instructions. This API is a callback. This API will also serve BulkPayment_Status_Update() from Payments BB to Source BB If the callback fails, the same response can be obtained by directly calling this API ( with case 2 endpoint)
c) Payment_Status_Check Request()
This API is to be invoked by the Source BB to the Payments BB in case the Source BB (SBB) does not receive some completed transactions in bulk payment status updates callback or batch by batchId polling from the Payments BB. Then SBB can run a query for a single beneficiary payment status check.
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.
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.
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.
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.
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.
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).
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.
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.
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.
The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money and vouchers.
This API is called to inquire about bill details from a Bill Aggregator or Govt Entity.
The Payment BB updates the Bill Aggregator or government entity on the status of the Request to Pay.
This API marks a bill as paid.
The Bill Aggregator or Govt Entity initiates a “Request to Pay” (RTP) through this API.
This API allows the Biller or Aggregator to inquire about the status of its RTP.
This API allows the Biller or Aggregator to receive the status of its RTP.
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.
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.
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).
IM forwards the "Register_Beneficiary" request to the Payments Building Block (PBB) with the same parameters.
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.
If the parameters are valid, PBB sends the "Register_Beneficiary" request to the Account Mapper (AM) with the same parameters.
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.
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.
PBB forwards the "Register_Beneficiary_Response" to IM, with the same parameters.
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.
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).
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.
SBB sends these instructions as a prepayment validation request (Prepayment_Validation) to Payments BB (PBB).
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.
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.
PrBank forwards the account validation request to the Payee Bank (PyBank) as per the incumbent scheme norm.
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.
PyBank sends an account validation response back to PrBank, adhering to the incumbent scheme norm.
PrBank then sends a bulk validate account response (BulkValidateAccount_Response) to PBB, containing the batch ID and an array of any failed instructions.
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.
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.
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).
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.
PBB then requests authorization from the PrBank by sending a getAuthorization() message.
PrBank responds with a getAuthorization_Response() message, granting the required authorization to PBB.
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.
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.
The Voucher Management System supports three workflows for voucher payments:
administration (voucher provisioning and merchant registration),
voucher issuing (pre-activation and activation),
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:
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.
The voucher activation flow is shown in the diagram below.
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.
The voucher redemption process is shown in the diagram below.
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
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.
The voucher cancellation flow is shown in the diagram below.
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.
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:
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.
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.
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)
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
The PBB would receive the Bill Inquiry as a result of Pay Bill request at a Payer FI – Payer end.
PBB would validate the sender of request and send it on to the respective Biller/ Govt. Entity to fetch bill.
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
Receiving the Payment Status Update the PBB would forward the Payment confirmation to Biller/ Govt. Entity
PBB sends Mark Bill Paid Advice to the Biller/ Govt Entity until a response is received from that site.
Upon receiving a response from the Biller/ Aggregator, the PBB would notify the Payer FSP of the response.
The Government Agency sends an invoice to the payer, detailing the amount owed.
The Government Agency also sends a copy of the invoice to the designated Bill Aggregator.
The Bill Aggregator then sends the invoice reference number to the Payments Building Block .
The payer, upon receiving the invoice, provides the invoice reference number to their preferred Collection Financial Service Provider (Collection Financial Services Provider).
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.
The Payments Building Block, in turn, requests the transaction details from the Bill Aggregator.
The Bill Aggregator provides the requested transaction details to the Payments Building Block.
The Payments Building Block forwards the transaction details to the Collection FSP.
The Collection FSP executes the payment based on the transaction details provided.
After completing the payment, the Collection FSP sends the payment reference to the Payments Building Block.
The Payments Building Block forwards the payment reference to the Bill Aggregator.
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
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.
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
This section provides information on the core data structures/data models that are used by this Building Block.
| Fields/ Records | Description | Provided/ Generated By |
|---|---|---|
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.
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
Field
Type
M/O
Description
batchId
String(50)
M
BatchID for sub-batch that is being dispatched to this specific receiving bank.
destinationDFSPID
String (11)
M
BIC of the receiving bank.(Payee)
creditInstructions
Object
M
JSON Array of all instructions that require to be credited after pre-validation has occurred.
instructionID
String (16)
M
Individual ID for each instruction in the Credit Batch generated by the Payments Building Block
financialAddress
String (20)
M
Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well. (Payee Identifier)
amount
Float
O
Amount to be Credited
currency
String (3)
O
Transaction Currency Code
narration
String (50)
O
Description of Payment
Name
Type
Description
Notes
Vouchers ID
Int64
Unique voucher identifier
Voucher_Number
Varchar
Secret voucher number
Voucher_serial_no
Varchar
Unique voucher identifier for external parties
Currency
Varchar
Voucher currency
Create_date
Date
Date when the voucher was created
Activate_date
Date
Date when the voucher was activated
Expiry_date
Date
Date when voucher will expire
Voucher_group
Varchar
Voucher group
Status
Varchar
Status of the voucher (e.g. ACTIVATED, SUSPENDED, CONSUMED, etc.)
Value
Double
Value of the Voucher
Name
Type
Description
Notes
Vouchers ID
Int64
Unique voucher group identifier
Voucher_group
Varchar
Voucher group short code
Voucher_group_desc
Varchar
Voucher description
Field
Type
M/O
Description
requestId
String (2)
M
00 – Success
01 – Failure
code
String (200)
M
reason
String (12)
M
Echoed from Request
billID
String (20)
M
Echoed from Request
billDetails
Object
M
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.
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
In case a Government Entity has specific budget account for a Program.
ID of the Issuing Agency, used for validation and data scoping.
URL on which the result is published.
Details required for voucher creation.
Globally unique ID.
BatchID for batch.
Individual ID for each instruction.
Transaction Currency Code.
Amount to be Credited.
Functional Id of the beneficiary.
Description of Payment.
Response from the Voucher Engine.
Status code of the response.
Detailed response description.
Echoed from Request.
Beneficiary update successfully received.
URL on which the result is published
Unique ID to identify the Source Ministry/Organization that registered the beneficiary.
Successfully received request.
Callback successfully received.
Callback successfully received.
Details of the created vouchers.
Globally unique ID.
BatchID for batch.
Individual ID for each instruction.
Voucher Serial Number.
Encrypted Voucher Number.
Transaction Currency Code.
Amount to be Credited.
Description of Payment.
Voucher details successfully received by Source BB.
Command for the action.
Voucher redemption details.
Globally unique ID.
Voucher Serial Number.
Agent or Merchant ID.
Voucher secret number for redemption.
Voucher redemption details.
Redemption status (0 for failure, 1 for success).
Narration from the Voucher Engine.
Serial number of the redeemed voucher.
Amount of the redeemed voucher.
Redemption timestamp.
Unique transaction ID.
Activation status details.
Globally unique ID.
Echo the ID of the original Voucher_Activate API call.
Number of failed activation cases.
Serial Number of the voucher.
Reason why the voucher failed to activate.
Activation confirmation successfully received by Source BB.
Status of the confirmation reception.
For this use case, the value of the command is activate.
Details of the vouchers to be updated.
Globally unique ID.
BatchID for batch.
Voucher Serial Number for activation.
Voucher status successfully updated by Voucher Engine.
Response code (00 for success, 01 for failure).
Description of the response.
Echoed from Request.
Unique Reference Number assigned to the voucher.
Query parameter to retrieve status.
Voucher status details.
Voucher status (from 01 to 06, and 9 for error).
Serial number of the voucher.
Amount of the voucher.
Voucher cancellation confirmation details.
Globally unique ID.
Echo the ID of the original Voucher_Cancellation API call.
The number of cases failed.
Serial Number of the voucher.
Reason for failure.
Voucher cancellation confirmation processed successfully.
Operation command.
Voucher details to be cancelled.
Globally unique ID.
Batch ID for the batch.
Serial Number of the voucher.
Voucher cancellation processed.
Response code indicating success or failure.
Description of the response.
Echoed Request ID.
Globally unique requestId/ client correlation Id
Tenant Id for Data scoping
Payer FI ID initiating the original bill inquiry/ payment sequence
Request Accepted
Globally unique requestId/ client correlation Id
Tenant Id for Data scoping
Payer FI ID initiating the original bill inquiry/ payment sequence
Request Accepted
ID of the specific Bill invoice
Specific fields for inquiry
Globally unique requestId/ client correlation Id
Tenant Id for Data scoping
Payer FI ID initiating the original bill inquiry/ payment sequence
Accepted
Globally unique requestId/ client correlation Id
Tenant Id for Data scoping
Payer FI ID initiating the original bill inquiry/ payment sequence
Successful Response
Transfer request ID
Globally unique requestId/ client correlation Id
Tenant Id for Data scoping
ID of the institution requesting the transaction Update
Request accepted.
Globally unique requestId/ client correlation Id
Tenant Id for Data scoping
ID of the institution initiating the RTP
RTP Update Acknowledged
Transfer request ID
Globally unique requestId/ client correlation Id
Tenant Id for Data scoping
ID of the institution requesting the transaction Update
Request accepted.
Error with https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-e73fd4ddb8e454fcfb6074db3b4e48718065750e%2FBulkPayment%20(1).yml?alt=media: Failed to parse YAML: Map keys must be unique; "parameters" is repeated