7 Data Structures

This section provides information on the core data structures/data models that are used by this Building Block.

7.1 Resource Model

Voucher Resource Model

7.2 Data Structures

7.2.1 Voucher provisioning

Fields:

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

7.2.2 Register Beneficiary

Fields:

Name	Type	Description	Notes
RequestID	String	Globally unique ID
SourceBBID	String	To identify the origination of the request.
Beneficiaries	Object	JSON Array
PayeeFunctionalID	String	The functional Id of the beneficiary.
PaymentModality	String	00 for Bank Account 01 for Mobile Money 02 for Voucher 03 for Digital Wallet 04 for Proxy
FinancialAddress	String	Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.

7.2.3 Update Beneficiary details

Fields:

Name	Type	Description
Name	Type	Description	Notes
RequestID	String	Globally unique ID
SourceBBID	String	To identify the origination of the request.
Beneficiaries	Object	JSON Array
PayeeFunctionalID	String	The functional Id of the beneficiary.
PaymentModality	String	00 for Bank Account 01 for Mobile Money 02 for Voucher 03 for Digital Wallet 04 for Proxy
FinancialAddress	String	Destination Account Number, ideally an IBAN if available otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.

7.2.4 Prepayment validation

Fields:

Name	Type	Description
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

7.2.5 Bulk payment

Fields:

Name	Type	Description	Notes
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.

7.2.6 Minimum Required Data

Fields:

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

7.2.7 Voucher Groups

Fields:

Name	Type	Description	Notes
Vouchers ID	Int64	Unique voucher group identifier
Voucher_group	Varchar	Voucher group short code
Voucher_group_desc	Varchar	Voucher description

7.2.8 Incoming Government Payments Resource

Fields:

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.