search
All SpecificationsGovStack Website
githubEdit

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

The GovStack non-functional requirements documentarrow-up-right 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 repositoryarrow-up-right.

hashtag
8.1 Payment Orchestration

The payments BB APIs are listed below

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.

hashtag
8.1 Person-to-Government APIs (P2G)

The implementation will be such that a “Request to Pay” API is exposed and the Government Ministry (entity) is treated as a type of Biller.

hashtag
8.1.1 Government Initiated P2G payment

This API is designed for the government entity to initiate a request to the Financial Service Provider (FSP) and will be credited when the payer approves the request.

hashtag
8.1.2 P2G Bill Payments

The Bill Payments APIs allow government entities to accept bill payments from persons on digital platforms like mobile money.

hashtag
8.2 Government to Person payments

These APIs link Source BB to the Payments Building Block for bulk payment processing, identity verification, and bank/wallet mapping. Third-party providers may add extra APIs depending on the country's payment landscape.

hashtag
Collaboration with G2PConnect on G2P Payments

GovStack is collaborating with G2P Connect to make it easier for countries to understand, find, and implement the optimal tools for executing digital payments for the aim of sustainable development. For those familiar with the GovStack initiative, it is no surprise we are collaborating with G2P Connect, as we share a common mission (to provide the technological tools to facilitate sustainable development) and similar methods (developing technical specifications and guidance).

G2P Connect is an open-source effort to enable G2P digital payments, built with interoperable standards and design templates. It offers a technology blueprint with a plug-and-play architecture with built in privacy and security; a set of integration specifications to ensure interoperability across the systems supporting G2P delivery; and an integration sandbox to support the development of solutions adhering to the blueprint and specifications.

As G2PConnect is focused exclusively on G2P payments, this is a cogent area of collaboration for the GovStack Payments building block workstream. Our joint objective is to develop synergies with specific use cases for G2P digital payments so that these use cases can also be implemented using GovStack APIs and building blocks. We will share best practices and lessons learned through defining the technical specifications and architecture components for G2P payments use cases. We will also integrate and test the APIs for G2P payments use cases in an integrated sandbox adhering to the G2P Connect and GovStack Payments building block specifications.

These valuable resources will then enable any country to implement G2P payments with digital sovereignty and minimal effort. Countries can choose to use our open specifications to make existing systems compatible, procure an open-source DPG, or even a proprietary solution compliant with the specifications. This approach gives countries agency, allowing them to constantly improve their solutions according to evolving needs.

hashtag
8.2.1 Beneficiary Onboarding API

Once a new G2P beneficiary is onboarded by a G2P Program and assigned a Functional ID, they can be added to the Account Mapper in Payments BB after their eligibility for the social benefit program has been verified.

As the number of beneficiaries can be large, the API supports the addition of beneficiaries in the mapper in bulk. This allows for efficient onboarding and management of multiple beneficiaries at once, streamlining the process and reducing the time required for handling individual beneficiary registrations.

The Register Beneficiary API is invoked by the Information Mediator BB, which is triggered when the Registration BB is registering beneficiaries into the Payments BB's ID Mapper.

hashtag
Request Parameters

Field
Type
Required
Description

RequestID

String (12)

Yes

Globally unique ID

SourceBBID

String (12)

Yes

To identify the origination of the request.

Beneficiaries

Object

Yes

JSON Array

PayeeFunctionalID

String (20)

Yes

The functional ID of the beneficiary.

PaymentModality

String (2)

No

00 for Bank Account, 01 for Mobile Money, 02 for Voucher, 03 for Digital Wallet, 04 for Proxy

FinancialAddress

String (30)

No

Destination Account Number, ideally an IBAN if available, otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.

hashtag
Register a beneficiary

post
Body
RequestIDstring · min: 12 · max: 12Optional
SourceBBIDstring · min: 12 · max: 12Optional
Responses
chevron-right
200

Successful response

application/json
ResponseCodestring · min: 2 · max: 2Optional
ResponseDescriptionstring · max: 200Optional
RequestIDstring · min: 12 · max: 12Optional
post
/register-beneficiary

hashtag
Response Parameters

Field
Type
Required
Description

ResponseCode

String (2)

Yes

00 – Success, 01 – Failure

ResponseDescription

String (200)

Yes

RequestID

String (12)

Yes

Echoed from Request

hashtag
8.2.2 Update Beneficiary Details API

This is the API that is called by the Information Mediator BB when the Registration BB in turn calls its API for registering beneficiaries into the ID Mapper of the Payments BB.

hashtag
Request Parameters

Field
Type
Required
Description

RequestID

String (12)

Yes

Globally unique ID

SourceBBID

String (12)

Yes

To identify the origination of the request.

Beneficiaries

Object

Yes

JSON Array

PayeeFunctionalID

String (20)

Yes

The functional ID of the beneficiary.

PaymentModality

String (2)

No

00 for Bank Account, 01 for Mobile Money, 02 for Voucher, 03 for Digital Wallet, 04 for Proxy

FinancialAddress

String (30)

No

Destination Account Number, ideally an IBAN if available, otherwise wallet destination accounts could be phone numbers as well, other Financial Addresses such as Aliases etc.

hashtag
Response Parameters

Field
Type
Required
Description

ResponseCode

String (2)

Yes

00 – Success, 01 – Failure

ResponseDescription

String (200)

Yes

RequestID

String (12)

Yes

Echoed from Request

hashtag
8.2.2 Pre Payment Validation API

This API is to be exposed by the Payments BB; the prepayment validation API, called by Source BB, retrieves eligible Functional IDs from the account mapper for credit transfers.

hashtag
Request Parameters

Field
Type
Required
Description

RequestID

String (12)

Yes

Globally unique ID

SourceBBID

String (12)

Yes

To identify the origination of the request.

BatchID

String (12)

Yes

BatchID for batch submitted by the Source BB.

CreditInstructions

Object

Yes

JSON Array

InstructionID

String (16)

Yes

Individual ID for each instruction in the Credit Batch

PayeeFunctionalID

String (20)

Yes

The functional ID of the beneficiary.

Amount

Float

Yes

Amount to be Credited

Currency

String (3)

Yes

Transaction Currency Code

Narration

String (50)

No

Description of Payment

hashtag
Pre-payment validation

post
Body
RequestIDstring · min: 12 · max: 12Optional
SourceBBIDstring · min: 12 · max: 12Optional
BatchIDstring · min: 12 · max: 12Optional
Responses
chevron-right
200

Successful response

application/json
ResponseCodestring · min: 2 · max: 2Optional
ResponseDescriptionstring · max: 200Optional
RequestIDstring · min: 12 · max: 12Optional
post
/prepayment-validation
200

Successful response

Field
Type
Required
Description

ResponseCode

String (2)

Yes

00 – Success, 01 – Failure

ResponseDescription

String (200)

Yes

RequestID

String (12)

Yes

Echoed from Request

hashtag
8.2.2 Bulk disbursement APIs

This API is to be exposed by the Payments BB; it will be called by the Source BB to handover a batch of credit instructions to be processed.

hashtag
Request Parameters

Field
Type
Required
Description

RequestID

String (12)

Yes

Globally unique ID

SourceBBID

String (12)

Yes

To identify the origination of the request.

BatchID

String (12)

Yes

BatchID for batch submitted by the Source BB.

CreditInstructions

Object

Yes

JSON Array

InstructionID

String (16)

Yes

Individual ID for each instruction in the Credit Batch

PayeeFunctionalID

String (20)

Yes

The functional ID of the beneficiary.

Amount

Float

Yes

Amount to be Credited

Currency

String (3)

Yes

Transaction Currency Code

Narration

String (50)

No

Description of Payment

hashtag
Bulk payment processing

post
Body
RequestIDstring · min: 12 · max: 12Optional
SourceBBIDstring · min: 12 · max: 12Optional
BatchIDstring · min: 12 · max: 12Optional
Responses
chevron-right
200

Successful operation

application/json
ResponseCodestring · min: 2 · max: 2Optional
ResponseDescriptionstring · max: 200Optional
RequestIDstring · min: 12 · max: 12Optional
post
/bulk-payment

hashtag
Response Parameters

Field
Type
Required
Description

ResponseCode

String (2)

Yes

00 – Success, 01 – Failure

ResponseDescription

String (200)

Yes

RequestID

String (12)

Yes

Echoed from Request

hashtag
8.6 Voucher APIs/Voucher Management

The first API in the section below is used to request for a voucher with a specific value, currency, and purpose. The server responds with a voucher number, serial number, and expiry date. The second call activates the pre-activated voucher. The third call processes voucher redemption, crediting the merchant if valid. A fourth API enables batch voucher activation through encrypted files. Additional APIs allow for voucher status checks and cancellations.

hashtag
8.6.1 VoucherPreActivation API

The VoucherPreActivation API is used by non-Payment Building Blocks in the GovStack Framework to request for a voucher to be used. This call reserves the voucher (for a period, which is to be implemented). This API requests a single voucher from the voucher server that can be used for a future redemption process. The caller sends an amount, a voucher group (depending on the use case), the currency, and the name of the calling GovStack Building Block. If the API call is successful, the Payment Building Block will respond with a voucher number, a voucher serial number, and an expiry date.

post
/vouchers/voucher_preactivation

Requests for voucher number, voucher serial number and expiry date by sending voucher group, amount and currency

Authorizations
appidstringRequired

API key to authorize request

Header parameters
X-Callback-URLstring · uriOptional

The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.

Example: https://myserver.com/send/callback/here
X-Datestring · date-timeOptional

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.

X-CorrelationIDstringOptional

Header parameter to uniquely identify the request. Must be supplied as a UUID.

Pattern: ^[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}$
X-API-KeystringOptional

Used to pass pre-shared client's API key to the server.

X-User-BearerstringOptional

Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.

X-Client-Idstring · max: 256Optional

Used to pass pre-shared client's identifier to the server.

X-Content-HashstringOptional

SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.

X-User-Credential-1stringOptional

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.

X-User-Credential-2stringOptional

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.

X-Channelstring · max: 256Optional

String containing the channel that was used to originate the request. For example USSD, Web, App.

Body
voucher_amountstring · min: 1 · max: 23RequiredExample: 15.21Pattern: ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[0-9])?$
voucher_currencystring · enumRequiredPossible values:
voucher_groupstringRequired
Gov_Stack_BBstringRequired
voucher_commentstringOptional
Responses
chevron-right
200

Successfully pre-activated voucher

application/json
voucher_numberstring · min: 16 · max: 25Required

This is a random secret number that uniquely identifies the value and validity of the voucher.

voucher_serial_numberstring · min: 16 · max: 25Required

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.

expiry_date_timestring · date-timeRequired
post
/vouchers/voucher_preactivation

hashtag
8.6.2 VoucherActivation API

The VoucherActivation API is used by non-Payments Building Blocks in the GovStack Framework to activate a pre-activated voucher. This second function call is intended to ensure that the voucher is only activated when it is disbursed. This API requests for the activation of a voucher when the caller sends the voucher number to be activated. If the API call is successful, the activation is confirmed, and the voucher can now be used by the beneficiary.

patch
/vouchers/voucher_activation

Request for voucher activation by sending the voucher serial number

Authorizations
appidstringRequired

API key to authorize request

Header parameters
X-Callback-URLstring · uriOptional

The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.

Example: https://myserver.com/send/callback/here
X-Datestring · date-timeOptional

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.

X-CorrelationIDstringOptional

Header parameter to uniquely identify the request. Must be supplied as a UUID.

Pattern: ^[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}$
X-API-KeystringOptional

Used to pass pre-shared client's API key to the server.

X-User-BearerstringOptional

Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.

X-Client-Idstring · max: 256Optional

Used to pass pre-shared client's identifier to the server.

X-Content-HashstringOptional

SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.

X-User-Credential-1stringOptional

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.

X-User-Credential-2stringOptional

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.

X-Channelstring · max: 256Optional

String containing the channel that was used to originate the request. For example USSD, Web, App.

Body
voucher_serial_numberinteger · int64Required
Gov_Stack_BBstringRequired
Responses
chevron-right
200

Successfully activated voucher

application/json
result_statusstringRequired
patch
/vouchers/voucher_activation

hashtag
8.6.3 BatchVoucherActivation API

The BatchVoucherActivation API is used by a calling Building Block to activate vouchers in bulk. This may be used for bulk social cash transfers where the recipients receive benefits by vouchers. The calling Building Block is responsible for generating the beneficiary file as well as dispensing the vouchers. The Payments Building Block is responsible for generating and redeeming the voucher codes. Both BBs will have had to have exchanged encryption keys during the implementation phase.

The file provided by the calling Building Block (typically the Scheduler Building Block) will typically contain a unique identifier, the amount of the voucher required, the currency of the voucher, and the voucher group. While the file format may vary, the recommended file format is an encrypted JSON file.

If the file is properly formatted, the Payments Building Block will respond with a file that contains the unique ID that was sent, the status, the voucher number, the voucher serial number, and the expiry date of the voucher. The response file will also be an encrypted file to ensure the appropriate security of the voucher number.

The calling building block will dispense the vouchers as needed using an appropriate delivery mechanism. The calling Building Block will also be responsible for any verification of the beneficiary during the redemption process. The description of the dispensing of the vouchers once the calling block has received it is outside the scope of the Payments Building Block.

hashtag
8.6.4 VoucherRedemption

The VoucherRedemption API is used by non-Payment Building Blocks in the GovStack Framework to redeem a voucher. The calling Building Block will capture the voucher number and the voucher serial number from the merchant point. The external Building Block will also acquire the merchant name and payment details from the merchant registry. The calling Building Block will then send the voucher number, the voucher serial number, the merchant’s name, and payment details. The Payment Building Block will verify that the voucher has been activated and has not been used or blocked or canceled. If so, the Payment Building Block will then send a payment request to the funding agency/Financial Services Provider. The Payment Gateway of the Payments Building Block will facilitate the debit of the funding account, and the credit of the merchant as well as handle any intermediary fees. Once the payment has been successfully done the Payment Building Block will mark the voucher as consumed and notify the merchant (and beneficiary if possible).

post
/vouchers/voucher_redeemption

Request for voucher redemption by sending the voucher number, the merchant name and merchant payment details

Authorizations
appidstringRequired

API key to authorize request

Header parameters
X-Callback-URLstring · uriOptional

The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.

Example: https://myserver.com/send/callback/here
X-Datestring · date-timeOptional

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.

X-CorrelationIDstringOptional

Header parameter to uniquely identify the request. Must be supplied as a UUID.

Pattern: ^[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}$
X-API-KeystringOptional

Used to pass pre-shared client's API key to the server.

X-User-BearerstringOptional

Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.

X-Client-Idstring · max: 256Optional

Used to pass pre-shared client's identifier to the server.

X-Content-HashstringOptional

SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.

X-User-Credential-1stringOptional

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.

X-User-Credential-2stringOptional

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.

X-Channelstring · max: 256Optional

String containing the channel that was used to originate the request. For example USSD, Web, App.

Body
voucher_numberinteger · int64Required
Gov_Stack_BBstringRequired
merchant_namestringRequired
merchant_bank_detailsstringRequired
merchant_voucher_groupstringRequired
overridebooleanRequired
Responses
chevron-right
200

Voucher is successfully redeemed

application/json
result_statusstringRequired
post
/vouchers/voucher_redeemption

hashtag
8.6.5 VoucherStatus API

The VoucherStatus API is used by non-Payment Building Blocks in the GovStack Framework to check the status of a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to determine the status of a voucher. The Payments Building Block will respond with one of the statuses of Pre-Activated, Activated, Suspended, Blocked, or Not Existing.

get
/vouchers/voucherstatuscheck/{voucherserialnumber}

Check the status of the Voucher. The API will respond with Not Preactivated, Preactivated, Activated, Active, Consumed, Blocked, Suspended and Purged.

Authorizations
appidstringRequired

API key to authorize request

Path parameters
voucherserialnumberstringRequired

Voucher serial number to check status of

Header parameters
X-Callback-URLstring · uriOptional

The URL supplied by the client that will be used to return the callback in the form of a HTTP PUT.

Example: https://myserver.com/send/callback/here
X-Datestring · date-timeOptional

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.

X-CorrelationIDstringOptional

Header parameter to uniquely identify the request. Must be supplied as a UUID.

Pattern: ^[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}$
X-API-KeystringOptional

Used to pass pre-shared client's API key to the server.

X-User-BearerstringOptional

Used to pass user’s access token when OAuth 2.0/OIDC authorisation framework is used for end-user authentication.

X-Client-Idstring · max: 256Optional

Used to pass pre-shared client's identifier to the server.

X-Content-HashstringOptional

SHA-256 hex digest of the request content (encrypted or plain). Applicable only if basic data integrity checking is to be performed.

X-User-Credential-1stringOptional

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.

X-User-Credential-2stringOptional

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.

X-Channelstring · max: 256Optional

String containing the channel that was used to originate the request. For example USSD, Web, App.

Responses
chevron-right
200

Voucher status

application/json
voucher_statusstring · enumOptionalPossible values:
voucher_amountstringOptional
get
/vouchers/voucherstatuscheck/{voucherserialnumber}

hashtag
8.6.6 VoucherCancellation API

The VoucherCancellation API is used by non-Payments Building Blocks in the GovStack Framework to cancel a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to cancel the voucher. The Payments Building Block will respond with a status of Cancelled, Already Cancelled, or Not existing. The Voucher Cancellation will override the Blocked status and render the voucher permanently unusable.

Last updated

Was this helpful?