Example Implementation for the USCT disbursement

Owned by Kibuuka, Arnold
Last updated: May 12, 2023
4 min read

Use Case Step

USE CASE: Unconditional Social Cash Transfer

STEP:

TYPE: USCT disbursement

Preconditions

 

Terms and definitions:

Registration BB = The GovStack BB that enrolls and validates beneficiary lists, populates the Account Mapper Module within the Pay-BB with Beneficiary Functional ID and Financial Address Pair.

Disburing Entity = The Social Ministry or Government Entity or any Private Entity which is using the Registeration BB to onboard, verify and disburse payments to beneficiaries.

Beneficiary = Ultimate benefactor of payments. First enrolled by the Disburing Entity in the Reg-BB. Beneficiary functional ID and Financial Addresses are populated in the Account Mapper.

Payments BB = The Pay-BB which comprises of 3 core sub-modules.

  1. The Account Mapper which is a database of beneficiary data (Functional ID and Financial Address).

  2. The Payments Hub which is the payment orchestration and bulk processing engine.

  3. The Voucher Engine which is the Voucher Management Module that issues, authorizes and redeems vouchers

Preconditions:

  • A beneficiary is enrolled to the G2P programme and assigned a unique Functional ID

  • Their eligibility for the social benefit program is confirmed

  • Payment conditions and calculations are managed by external systems

  • Communication occurs through the Information Mediation block

  • The Security block provides authentication for involved government entities and users

  • Either a national-level Payment System handles fund clearance and settlement or a bilateral payment channel between the different FSPs, this assumption is for this particular use case but may not always be the case.

  • The Functional ID is issued to the beneficiary

  • The source building block (payer) is registered in the Payments Building Block (PBB), this may be a onetime manual configuration.

  • Batch file is created and authorised by the Source Building Block.(SBB)

  • Payments Building Block Bulk Payment API is called in which the instructions from the batch file are passed for processing. (the Pay-BB is designed to take input in the form of a JSON array in the Bulk Payments API. It does take a csv or likewise file for processing).

  • There must be maker-checker flows and thus actors in the Reg BB which eventually leads to calling the Pay-BB API with Payment Instructions against functional IDs.

 

Data inputs

  • Beneficiary Functional ID

  • Programme ID

  • Programme name

  • Array of beneficiaries with their:

    • Functional ID,

Actors

(the people, organization, computer systems - hardware and software, and building blocks that participate in the activity)

Human: 

  • Beneficiary

  • Maker and checker(refer to preconditions)

System:

  • Source Building Block (SBB)

  • Information Mediator (IM)

  • Payments Building Block (PBB)

  • Messaging BB

  • Payer Bank (PrBank)

  • Payee Bank (PyBank)

Normal Course (what happens if the event is triggered and the preconditions have been met)

Provides a step-by-step description of the normal flow of the implementation of a UCST payment:

Step 1: Beneficiary onboarding to the account mapper

The normal course of this use case step describes the process of onboarding beneficiaries in the Account Mapper, which is a prerequisite step before any payment processing can occur. The workflow represents the interactions between the Source Building Block (SBB), Information Mediator (IM), Payments Building Block (PBB), and Account Mapper (AM) during the beneficiary onboarding process.

  1. SBB sends "Register_Beneficiary" request to IM (Request ID, SBB ID, beneficiary details)

    • API documentation

  2. IM forwards request to PBB (same parameters)

    • API documentation

  3. PBB validates API parameters, checks SBB configuration in Payments BB

    • API documentation

  4. PBB sends valid "Register_Beneficiary" request to AM (same parameters)

    • API documentation

  5. AM checks for duplicate Functional IDs, registers unique beneficiaries

    • API documentation

  6. AM sends "Register_Beneficiary_Response" to PBB (Request ID, response code, failed cases)

    • API documentation

  7. PBB forwards response to IM (same parameters)

    • API documentation

  8. IM sends response to SBB (final response code, list of failed cases)

    • API documentation

Step 2: Pre-validation of Accounts prior to Bulk Disbursement

The normal course of this use case step describes the pre-validation process of accounts in a bulk disbursement scenario. The workflow represents the interactions between the Source Building Block (SBB), Payments Building Block (PBB), Payer Bank (PrBank), and Payee Bank (PyBank) to ensure that accounts involved in a bulk disbursement transaction are valid and capable of receiving the specified credits before processing payments.

  1. SBB prepares bulk disbursement instructions (Functional ID, amount, description, instruction ID)

    • API documentation

  2. SBB sends prepayment validation request (Prepayment_Validation) to PBB

    • API documentation

  3. PBB debulks instructions, checks payee's Functional ID, records failed instructions

    • API documentation

  4. PBB sends bank-wise sub-batches for validation (Bulk_ValidateAccount) to PrBank (batch ID, destination BIC, payment instructions)

    1. PrBank forwards account validation request to PyBank (incumbent scheme norm)

    2. PyBank performs validation checks (account existence, credit reception, credit limit)

    3. PyBank sends account validation response to PrBank (incumbent scheme norm)

    4. PrBank sends bulk validate account response (BulkValidateAccount_Response) to PBB (batch ID, failed instructions)

  5. PBB sends prepayment validation response (Prepayment_Validation_Response) to SBB (batch ID, failed instructions)

    • API documentation

Step 3: Disbursement into a Financial Address pre-registered in the Account Mapper

The normal course of this use case step describes the process of disbursement into financial addresses, such as bank accounts or mobile wallets, that are pre-registered in the Account Mapper.

  1. SBB sends BulkPayment request to PBB (Batch_ID, payment instructions)

    • API documentation

  2. PBB checks liquidity provision and debulks crediting batches by receiving institution

  3. PBB requests authorization from PrBank (getAuthorization() message)

    1. PrBank grants authorization to PBB (getAuthorization_Response() message)

    2. PBB sends payee bank-wise sub-batches to PrBank in loop (BulkPayment_ReceiverFI message, Batch_ID, Destination_BIC, payment instructions)

    3. PrBank executes batches through existing rails

  4. PBB sends BulkPayment_StatusPush(BatchID, Credit Instructions) to the Source building block which will show status of the transactions.

Alternative Course

(links to other use cases in case there are different ways how to solve the same use case)

Description of alternate paths or flows that may be needed for this example implementation. These alternates should include links to test files, APIs, and data structures as well

Data output

Register_Beneficiary_Response containing:

  • Request ID,

  • Response code,

  • Array of failed cases (if any) with descriptions.

Prepayment_Validation_Response containing:

  • Batch ID

  • Array of any failed instructions.

Post-Conditions (the success criteria)

 

Exceptions

(error situations)

  • Duplicate Functional IDs registered by the same SBB.

  • Invalid API parameters.

  • SBB not configured in the Payments BB as an acceptable source of the API call.

Related BBs

(working groups related to this implementation example)

  • Identity BB

  • Consent BB

  • Registration BB

  • Digital Registries BB

Sequence Diagram

Links to Code

Provide any links to relevant code that has been developed for automated tests or example implementations