Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
Authorization
The permission given by the Payer or entity to make a Payment.
Beneficiary
Non referring to a payee of a program.
Bulk Payments
A Payment from a single Payer to multiple Payees, for example, cash transfer programs from a government or non-governmental organization to a set of beneficiaries.
End User
The customer of a digital financial services provider. The customer may be a consumer, a merchant, a government, or another form of enterprise.
Financial Management Information System
The budget management system of the government treasury which ensures that government (Ministries, Departments, Agencies) payments are processed within the approved budget and releases.
Financial Services Providers (FSPs)
A financial services provider refers to one that is licensed by a regulatory authority to provide transaction accounts that hold customer funds and are used to make and receive payments. Digital Financial Services Providers (DFSPs) have relationships with consumers, merchants, and other enterprises, and provide digital financial services to End Users.
Interoperability
The ability of DFSPs participating in a payment Scheme to exchange Transactions with each other. The term may also be used when two systems interconnect.
Account Mapper or Account Lookup Directory Service
A dynamic directory matching beneficiaries’ unique identifier and their account numbers enable multiple programs to direct payments to the same account and beneficiaries to switch payment service providers. The identifier can be a national ID, phone number, or other number or alias that can uniquely identify individuals across social protection and financial sector databases.
Mobile Money (MoMo)
A mobile money service includes transferring money and making and receiving payments using a mobile phone. The service must be available to the unbanked, e.g. people who do not have access to a formal account at a financial institution. The service must offer a network of physical transactional points which can include agents, outside of bank branches and ATMs, that make the service widely accessible. Mobile banking or payment services (such as Apple Pay and Google Wallet) that offer the mobile phone as just another channel to access a traditional banking product are not included.
Mobile Money Services Provider
A category of DFSPs that use mobile phones as the access method to provide transaction Accounts to End Users.
Payee
The recipient of funds in a payment transaction.
Payer
The person/organization whose account is debited in a payment transaction.
Payment
Exchange of funds, credentials, and other necessary information to complete an obligation between End Users. A transfer is an example of a payment.
Payment Alias/Payment address
An alias may include phone numbers, email addresses, or other handles. They may include globally unique URIs and may be chosen by the user. These are increasingly seen in new payment systems. Within systems, the payment alias points to an underlying payment account address, specifically and uniquely located within a payment scheme. A payment address may be different from the underlying account address, depending on the payment scheme rules but is often the same thing.
Quick-Response (QR) Code
A method of encoding and visualization of data, which are machine-readable. There are multiple QR models.
Routing
The process by which a route to a payment address is determined. The mechanism of sending payment information across different systems. This is sometimes used interchangeably with addressing.
Transaction
A reference to the entirety of the exchange, including a Payment but may also include information between the Payer’s DFSP and the Payee’s DFSP.
Treasury Single Account
A Treasury Single Account (TSA) is a unified structure of government bank accounts that gives a consolidated view of government cash resources. Based on the principle of unity of cash and the unity of treasury, a TSA is a bank account or a set of linked accounts through which the government transacts all its receipts and payments. The principle of unity follows from the fungibility of all cash irrespective of its end use. While it is necessary to distinguish individual cash transactions for control and reporting purposes, this purpose is achieved through the accounting system and not by holding/depositing cash in transaction-specific bank accounts. This enables the treasury to delink management of cash from control at a transaction level.
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.
This section links to any external documents that may be relevant, such as standards documents or other descriptions of this Building Block that may be useful.
A historical log of key decisions regarding this Building Block.
A list of topics that may be relevant to future versions of this Building Block.
A list of functions out of the scope of this Building Block.
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)
This section provides information on the core data structures/data models that are used by this Building Block.
Fields:
Fields:
Fields:
Fields:
Fields:
Fields:
Fields:
Fields:
Name | Type | Description | |
---|---|---|---|
Name | Type | Description | |
---|---|---|---|
Name | Type | Description | Notes |
---|---|---|---|
Name
Type
Description
Notes
voucher_amount
Integer
Denomination of the voucher required
Input
voucher_currency
String
The currency of the voucher (ISO 4217 Standard)
Input
voucher_group
String
The group of the voucher
Input
voucher_number
Integer: 64-bit
The voucher number (PIN). This is the secret number of the voucher.
Output
voucher_serial_number
Integer: 64-bit
The voucher serial number
Output
expiry_date
String: date-time
The expiry date of the voucher
Output
status
String
The status of the process: SUCCESSFUL or FAILED
Output
Merchant_group
String
The group of the merchant is captured in the registry
Input
Gov_Stack_BB
String
Calling GOV Stack Building Block
Input
merchant_bank_details
String
Merchant/agent payment details
Input
merchant_name
String
Merchant name
Input
Override
Boolean
Override
Input
Result_Status
String
Result of the process
Output
Name
Type
Description
Notes
RequestID
String
Globally unique ID
SourceBBID
String
To identify the origination of the request.
Beneficiaries
Object
JSON Array
PayeeFunctionalID
String
The functional Id of the beneficiary.
PaymentModality
String
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
FinancialAddress
String
Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
Name
Type
Description
Notes
RequestID
String
Globally unique ID
SourceBBID
String
To identify the origination of the request.
Beneficiaries
Object
JSON Array
PayeeFunctionalID
String
The functional Id of the beneficiary.
PaymentModality
String
00 for Bank Account
01 for Mobile Money
02 for Voucher
03 for Digital Wallet
04 for Proxy
FinancialAddress
String
Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
Name
Type
Description
Notes
RequestID
String
Globally unique ID
SourceBBID
String
To identify the origination of the request.
BatchID
String
BatchID for batch that is submitted by the Source Building Block.
CreditInstructions
Object
JSON Array
InstructionID
String
Individual ID for each instruction in the Credit Batch
PayeeFunctionalID
String
The functional Id of the beneficiary.
Amount
Float
Amount to be Credited
Currency
String
Transaction Currency Code
Narration
String
Description of Payment
Name
Type
Description
Notes
RequestID
String
Globally unique ID
SourceBBID
String
To identify the origination of the request.
BatchID
String
BatchID for batch that is submitted by the Source Building Block.
CreditInstructions
Object
JSON Array
InstructionID
String
Individual ID for each instruction in the Credit Batch.
PayeeFunctionalID
String
The functional Id of the beneficiary.
Amount
Float
Amount to be Credited.
Currency
String
Transaction Currency Code.
Narration
String
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
Name
Type
Description
Notas
transactionReference
string
Unique reference for the transaction. This is returned in the response by Financial Service Provider.
requestingOrganisationTransactionReference
string
A reference provided by the requesting organisation that is to be associated with the transaction.
originalTransactionReference
string
For reversals and refunds, this field indicates the transaction which is the subject of the reversal.
creditParty
array
A series of key/value pairs that enable the credit party to be identified. Keys include Mobile Station Integrated Services Digital Network (MSISDN) and Wallet Identifier.
debitParty
array
A collection of key/value pairs that enable the debit party to be identified. Keys include MSISDN and Wallet Identifier.
type
string
The harmonised Transaction Type (not required if passed in the URL)
subType
string
A non-harmonised sub-classification of the type of transaction. Values are not fixed, and usage will vary according to Provider.
transactionStatus
string
Indicates the status of the transaction as stored by the API provider.
amount
string
The transaction amount.
currency
string
Currency of the transaction amount.
descriptionText
string
Free format text description of the transaction provided by the client. This can be provided as a reference for the receiver on a notification SMS and on an account statement.
fees
array
Allows the passing and/or returning of all fees pertaining to the transaction.
geoCode
string
Indicates the geographic location from where the transaction was initiated.
oneTimeCode
string
A one-time code that can be supplied in the request or can be generated in the response depending upon the use case. An authorisation code can be supplied in this field for requests that have been pre-authorised.
requestingOrganisation
object
The originating organisation of the request.
servicingIdentity
string
The field is used to identify the servicing identity for transactions, e.g. till, Point of Service (POS) ID, assistant ID.
transactionReceipt
string
Transaction receipt number as notified to the parties. This may differ from the Transaction Reference.
creationDate
date-time
Date and time when the transaction was created by the API Provider.
modificationDate
date-time
Date and time when the transaction was modified by the API Provider.
requestDate
date-time
The creation date and time of the transaction as supplied by the client.
customData
string
A collection of key/value pairs that can be used for provider specific fields.
metadata
array
A collection of key/value pairs. These can be used to populate additional transaction fields.
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.
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)
6.15.2 Interaction with Other Building Blocks (REQUIRED)
The diagram below shows the interaction with the registries Building Blocks.
At a high level, the payment components used for bulk payments are shown in the figure below.
Figure: Key digital requirements of Bulk Payments expressed as a high-level block diagram. Dotted line for required components.
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.
The version history table describes the major changes to the specifications between published versions.
Version | Authors | Comment |
---|
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.
That said, today, with over 1.2 billion global accounts, transacting an average of over $2 billion per day, mobile money has grown to become the leading payment platform in a growing number of emerging markets. Today, there are more mobile money accounts in Sub-Saharan Africa than there are bank accounts. Indeed, during the pandemic, demand for mobile money services increased among businesses, governments, and new services that previously relied on cash or other payment channels.
There are currently active discussions in many markets that need the integration of mobile money into existing national infrastructure. While the integration of mobile money into existing schemes and infrastructure has the potential to create value for all stakeholders in the ecosystem, many legacy payment systems may not be suitable for mobile money integration in their current state. As an example, many existing interbank switches do not support mobile money as a core feature because of legacy technical architecture. What is often missing is the essential capability of the switch to handle high-volume, low-value flows with the mobile number (Mobile Station Integrated Services Digital Network) as identifier for routing and address resolution hence the need for integration. Recent industry developments offer solutions designed to solve many of the issues around the switching of mobile money.
Mobile money providers, regulators, infrastructure providers, and other financial system players should seek to engage in any potential interoperability initiatives from an early stage to ensure optimal payment system design for all parties. Should existing infrastructure be used, a thorough assessment should be conducted, with input from all parties, to ensure appropriate governance, commercial, and technical standards are incorporated. Mandating interoperability within a short time frame removes opportunities for a thoughtful and holistic analysis of commercial sustainability. Requiring immediate interoperability can also delay or hamper the uptake of interoperable transactions, and mobile money services altogether. This is a particular risk in contexts where regulators or governments impose immediate connections to a centralized hub. Mobile money providers should be encouraged to connect when their service is ready. However alternative modalities of payment such as cash vouchers can also be considered in scenarios of low-resource regions that lack modern infrastructure and a volume of mobile phone users. Also, in countries where mobile money providers are not connected to a payment switch, aggregators can enable the flow of funds between multiple financial service providers including banks and non-banks. While aggregators may not be as efficient and scalable as switches, they can help solve interoperability issues in the short and medium term.
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.
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.
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
Payments for government services (application for a birth certificate)
There are two possible scenarios that can be supported:
a) P2G payment is initiated by the Payer
b) P2G payment is initiated by the Payee (USSD push payment for example)
Scenario a) can also be implemented using QR code.
Flow Description:
Upon registration for a government service, the Registration Building Block sends transaction details to the Payments Building Block which creates and returns a unique payment reference for the payer of the service.
The Registration Building Block sends the unique reference number to the payer.
After entering their account the payer would invoke a bill payment to a selected service (in this case paying for the registration service). The payer would need to enter the payment reference which would prompt the retrieval of the payment details from the Registration Building Block in real time. If the payment details are correct, the payer is prompted to enter their mobile money pin to authorize the payment.
Upon authorisation, the payer’s account is debited and the government’s connected account is credited in real time. The Financial Service Provider, in this case, the mobile money provider would then notify the success status of the Payments Building Block.
For this type of payment, as the payment reference is needed to validate the payment, this can be done by any mobile money account holder.
Notes:
The above model requires that the payer must provide two pieces of information through their USSD, STK, or mobile app:
A merchant ID. Typically the government would be given a special merchant ID. The payer should be able to select which government service they would be paying for through the mobile money interface.
A reference ID: this is unique and time bound for each transaction.
As the bill payment is invoked by inputting the reference number which prompts the retrieval of the payment details in real-time from the registration building block, a failed transaction could be triggered by a session time-out or a wrong PIN. In both cases, the payer would have to re-initiate the transaction.
In the P2G payment in the flow above, the government holds an account with the Financial Services Provider which would collect the payments on the government's behalf and transfer them to the single treasury account on a defined timeline (i.e. daily) in an aggregated way. For reconciliation purposes, the Registration Building Block would need to notify the government of a successful/unsuccessful payment.
Flow Description:
Upon registration for a government service, the registration building sends transaction details to the Payments Building Block which sends a payment request to the payer through their mobile money provider (Unstructured Supplementary Service Data prompt).
The payer will see a request coming for the specific service requested with payment details, prompting them to authorize the payment by entering the pin code.
Upon authorisation, the payer’s account is debited and the government’s connected account is credited in real time.
The Financial Services Provider, in this case, the mobile money provider would then notify the success status to the Payments Building Block.
This payment differs from the previous P2G mobile money payment as the payment is not initiated by the payer by invoking a bill payment but is initiated by a merchant (in this case the government agency providing the service). Therefore the payer is requested to pay for the service immediately.
Notes:
There can be no error in the above as both the merchant number and the payment reference are pushed to the phone.
The only risk here is a timeout on the Unstructured Supplementary Service Data or the user keying in the wrong PIN which may require the transaction to be reinitiated.
Notes:
There is small room for error in reading a QR code (unless the payer scans the wrong code).
All mobile operators and banking apps need to be able to read the reference in the same way for this to work meaning that a standardised/interoperable QR code needs to be in place at a country level. While this is in place in some Asian countries (i.e. Indonesia, Sri Lanka) where there is widespread adoption of QR codes, In Africa the uptake of QR codes is significantly lower and standardisation is typically not in place at a country level.
During registration, the Registration Building Block will generate transaction details including the amount to be paid by the payer and transaction ID, and send them to the Payments Building Block.
The Payments Building Block will use the transaction details to initiate a request to pay to the Financial Service Provider.
The QR payment widget displayed to the payer will have the following different attributes: payment_entity_id, amount, currency, transaction_id
The payer scans the QR code to approve/reject the payment.
The Financial Service Provider sends a notification of the status of the transaction to the Payments Building Block and the payer.
Transaction status is sent to the Registration Building Block on completion of payments.
The Messaging Building Block sends a transaction confirmation message to the payer.
The P2G Bill Payments flow diagram illustrates the steps involved in processing bill payments between individuals and government agencies
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 (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.
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.
Payment for registrations. (In the case of the use case)
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
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 |
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 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.
The payments BB APIs are listed below
The implementation will be such that a “Request to Pay” API is exposed and the Government Ministry (entity) is treated as a type of Biller.
This API is designed for the government entity to initiate a request to the Financial Service Provider (FSP) and will be credited when the payer approves the request.
The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money.
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. This approach gives countries agency, allowing them to constantly improve their solutions according to evolving needs.
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.
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.
This API is to be exposed by the Payments BB; the prepayment validation API, called by Source BB, retrieves eligible Functional IDs from the account mapper for credit transfers.
This API is to be exposed by the Payments BB; it will be called by the Source BB to handover a batch of credit instructions to be processed.
The first API in the section below is used to request for a voucher with a specific value, currency, and purpose. The server responds with a voucher number, serial number, and expiry date. The second call activates the pre-activated voucher. The third call processes voucher redemption, crediting the merchant if valid. A fourth API enables batch voucher activation through encrypted files. Additional APIs allow for voucher status checks and cancellations.
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.
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.
The BatchVoucherActivation API is used by a calling Building Block to activate vouchers in bulk. This may be used for bulk social cash transfers where the recipients receive benefits by vouchers. The calling Building Block is responsible for generating the beneficiary file as well as dispensing the vouchers. The Payments Building Block is responsible for generating and redeeming the voucher codes. Both BBs will have had to have exchanged encryption keys during the implementation phase.
The file provided by the calling Building Block (typically the Scheduler Building Block) will typically contain a unique identifier, the amount of the voucher required, the currency of the voucher, and the voucher group. While the file format may vary, the recommended file format is an encrypted JSON file.
If the file is properly formatted, the Payments Building Block will respond with a file that contains the unique ID that was sent, the status, the voucher number, the voucher serial number, and the expiry date of the voucher. The response file will also be an encrypted file to ensure the appropriate security of the voucher number.
The calling building block will dispense the vouchers as needed using an appropriate delivery mechanism. The calling Building Block will also be responsible for any verification of the beneficiary during the redemption process. The description of the dispensing of the vouchers once the calling block has received it is outside the scope of the Payments Building Block.
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.
The VoucherCancellation API is used by non-Payments Building Blocks in the GovStack Framework to cancel a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to cancel the voucher. The Payments Building Block will respond with a status of Cancelled, Already Cancelled, or Not existing. The Voucher Cancellation will override the Blocked status and render the voucher permanently unusable.
Field | Type | Required | Description |
---|---|---|---|
Field | Type | Required | Description |
---|---|---|---|
Field | Type | Required | Description |
---|---|---|---|
Field | Type | Required | Description |
---|---|---|---|
Field | Type | Required | Description |
---|---|---|---|
Field | Type | Required | Description |
---|---|---|---|
Field | Type | Required | Description |
---|---|---|---|
Field | Type | Required | Description |
---|---|---|---|
1
make_G2P_payment (Payer ID, Payee ID, Amounts, Currency, [Modality], Date)
make_G2P_payment (PayerID: 12345,
Payee ID: ABCD, Amounts: 100, Currency: USD, [Modality: MoMo], Date: 12/06/2022)
Returns success code after payment confirmation or else returns failure status with error code
2
Create_transaction (Payer ID, Payee ID, BillReferenceID, Amount, Currency, Date)
create_transaction (PayerID: 12345, Payee ID: ABCD, BillReferenceID: 0001243, Amount: 10, Currency: USD, Date: 12/06/2022)
Returns success code after payment confirmation or else returns failure status with error code
3
view_transaction(PayerID, PayeeID, FromDate, ToDate, [status]).
view_transaction(PayerID: 12345, PayeeID: ABCD, FromDate: 01/01/2022, ToDate: 01/06/2022, [status]).
Returns success code along with payments history or else returns failure status with error code.
4
register_beneficiary(payee_functionalID, Modality, fsp_id, account_info)
Returns success code after creating entry along with mapperID.
5
update_beneficiary(payee_functionalID, Modality, fsp_id, account_info)
Returns success code after updating entry along with new mapperID.
6
get_paymentaccount_info(payee_functionalID)
Returns success code along with mapperID in tokenised format.
7
VoucherPreactivation (InstructionID, amount, Group_Code, currency, Expiry_DTTM, FunctionalID, Description)
Returns success code with voucher number, voucher serial number and expiry date.
8
VoucherActivation(voucher_number)
Returns success code. After this point the voucher may be redeemed.
9
VoucherRedemption(voucher_number, voucher_serial_number,[OC1] )
Returns success code and payment reference from the payment gateway. After this point the voucher CANNOT be used again as the system will fail it.
10
VoucherStatusCheck(serial_number)
Returns success code with the status of the voucher which may be either of Pre-Activated, Activated, Suspended, Blocked or Not Existing
11
VoucherCancellation(voucher_serial_number)
Returns a success code if the voucher has been successfully cancelled.
RequestID
String (12)
Yes
Globally unique ID
SourceBBID
String (12)
Yes
To identify the origination of the request.
Beneficiaries
Object
Yes
JSON Array
PayeeFunctionalID
String (20)
Yes
The functional ID of the beneficiary.
PaymentModality
String (2)
No
00 for Bank Account, 01 for Mobile Money, 02 for Voucher, 03 for Digital Wallet, 04 for Proxy
FinancialAddress
String (30)
No
Destination Account Number, ideally an IBAN if available, otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
ResponseCode
String (2)
Yes
00 – Success, 01 – Failure
ResponseDescription
String (200)
Yes
RequestID
String (12)
Yes
Echoed from Request
RequestID
String (12)
Yes
Globally unique ID
SourceBBID
String (12)
Yes
To identify the origination of the request.
Beneficiaries
Object
Yes
JSON Array
PayeeFunctionalID
String (20)
Yes
The functional ID of the beneficiary.
PaymentModality
String (2)
No
00 for Bank Account, 01 for Mobile Money, 02 for Voucher, 03 for Digital Wallet, 04 for Proxy
FinancialAddress
String (30)
No
Destination Account Number, ideally an IBAN if available, otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.
ResponseCode
String (2)
Yes
00 – Success, 01 – Failure
ResponseDescription
String (200)
Yes
RequestID
String (12)
Yes
Echoed from Request
RequestID
String (12)
Yes
Globally unique ID
SourceBBID
String (12)
Yes
To identify the origination of the request.
BatchID
String (12)
Yes
BatchID for batch submitted by the Source BB.
CreditInstructions
Object
Yes
JSON Array
InstructionID
String (16)
Yes
Individual ID for each instruction in the Credit Batch
PayeeFunctionalID
String (20)
Yes
The functional ID of the beneficiary.
Amount
Float
Yes
Amount to be Credited
Currency
String (3)
Yes
Transaction Currency Code
Narration
String (50)
No
Description of Payment
ResponseCode
String (2)
Yes
00 – Success, 01 – Failure
ResponseDescription
String (200)
Yes
RequestID
String (12)
Yes
Echoed from Request
RequestID
String (12)
Yes
Globally unique ID
SourceBBID
String (12)
Yes
To identify the origination of the request.
BatchID
String (12)
Yes
BatchID for batch submitted by the Source BB.
CreditInstructions
Object
Yes
JSON Array
InstructionID
String (16)
Yes
Individual ID for each instruction in the Credit Batch
PayeeFunctionalID
String (20)
Yes
The functional ID of the beneficiary.
Amount
Float
Yes
Amount to be Credited
Currency
String (3)
Yes
Transaction Currency Code
Narration
String (50)
No
Description of Payment
ResponseCode
String (2)
Yes
00 – Success, 01 – Failure
ResponseDescription
String (200)
Yes
RequestID
String (12)
Yes
Echoed from Request
Successful operation
Successful response
Successful response
Request for voucher activation by sending the voucher serial number
The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.
"https://myserver.com/send/callback/here"
Header parameter to indicate the date and time that the message was originated. It is used for basic message integrity checks, to ensure the request is not stale. Note that the header was previously referenced as 'Date' in version 1.0 of the Mobile Money API.
Header parameter to uniquely identify the request. Must be supplied as a UUID.
^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
Used to pass pre-shared client's API key to the server.
Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.
Used to pass pre-shared client's identifier to the server.
SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.
The end-users encrypted security credential. Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
The end-users encrypted security credential Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
String containing the channel that was used to originate the request. For example USSD, Web, App.
Successfully activated voucher
Check the status of the Voucher. The API will respond with Not Preactivated, Preactivated, Activated, Active, Consumed, Blocked, Suspended and Purged.
Voucher serial number to check status of
The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.
"https://myserver.com/send/callback/here"
Header parameter to indicate the date and time that the message was originated. It is used for basic message integrity checks, to ensure the request is not stale. Note that the header was previously referenced as 'Date' in version 1.0 of the Mobile Money API.
Header parameter to uniquely identify the request. Must be supplied as a UUID.
^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
Used to pass pre-shared client's API key to the server.
Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.
Used to pass pre-shared client's identifier to the server.
SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.
The end-users encrypted security credential. Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
The end-users encrypted security credential Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
String containing the channel that was used to originate the request. For example USSD, Web, App.
Voucher status
Request for voucher redemption by sending the voucher number, the merchant name and merchant payment details
The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.
"https://myserver.com/send/callback/here"
Header parameter to indicate the date and time that the message was originated. It is used for basic message integrity checks, to ensure the request is not stale. Note that the header was previously referenced as 'Date' in version 1.0 of the Mobile Money API.
Header parameter to uniquely identify the request. Must be supplied as a UUID.
^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
Used to pass pre-shared client's API key to the server.
Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.
Used to pass pre-shared client's identifier to the server.
SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.
The end-users encrypted security credential. Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
The end-users encrypted security credential Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
String containing the channel that was used to originate the request. For example USSD, Web, App.
Voucher is successfully redeemed
Requests for voucher number, voucher serial number and expiry date by sending voucher group, amount and currency
The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.
"https://myserver.com/send/callback/here"
Header parameter to indicate the date and time that the message was originated. It is used for basic message integrity checks, to ensure the request is not stale. Note that the header was previously referenced as 'Date' in version 1.0 of the Mobile Money API.
Header parameter to uniquely identify the request. Must be supplied as a UUID.
^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
Used to pass pre-shared client's API key to the server.
Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.
Used to pass pre-shared client's identifier to the server.
SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.
The end-users encrypted security credential. Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
The end-users encrypted security credential Should only be used when OAuth 2.0/OIDC authorisation framework has not been implemented by the API Provider.
String containing the channel that was used to originate the request. For example USSD, Web, App.
"15.21"
^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[0-9])?$
Successfully pre-activated voucher
This is a random secret number that uniquely identifies the value and validity of the voucher.
This is a sequential number that is used to identify a voucher without necessarily revealing the voucher secret number. There is no relationship between the voucher serial number and the voucher number.
Error with https://github.com/GovStackWorkingGroup/bb-payments/blob/1.0-QA/api/UpdateBeneficiary.yaml: Failed to parse YAML: All collection items must start at the same column