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 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.

8.1 Government to Person (G2P) 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.

8.1.1 Collaboration with G2PConnect

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.

8.1.2 Beneficiary Onboarding - Account Mapper APIs

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

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

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

a) Register Beneficiary Request()

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

Register beneficiaries into the ID Mapper.

POST/identityAccountMapper/beneficiary

Authorization

BeneficiaryOnboardingAuth

Header parameters

Body

application/json

RequestIDstring

Beneficiariesarray of object

Response

200400

Successfully received request.

Body

application/json

responseCodestring

responseDescriptionstring

requestIDstring

Request

JavaScriptCurlPython

const response = await fetch('/identityAccountMapper/beneficiary', {
    method: 'POST',
    headers: {
      "X-Callback-URL": "text",
      "X-Registering-Institution-ID": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

b) Register Beneficiary Response() - Callback

This is the API that is called back by the Pay-BB to notify the Source BB via the IM BB that all or selected beneficiaries have been uploaded into the ID Mapper.

Notify the onboarding status of beneficiaries.

POST/callback

Body

application/json

requestID*string

registerRequestID*string

numberFailedCases*integer

failedCasesarray of object

Response

200202

Callback successfully received.

Request

JavaScriptCurlPython

const response = await fetch('/callback', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestID": "text",
      "registerRequestID": "text"
    }),
});
const data = await response.json();

8.1.3 Update Beneficiary Details

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

a) Update Beneficiary Request()

This interface is to be called by the Registry BB (also referred to as Source BB) when an update to either the Payment Modality or Financial Address is required. Payee Functional ID is not updateable and is only part of this call to identify the individual record that needs updating.

Update the beneficiary payment modality or financial address.

PUT/identityAccountMapper/beneficiary

Body

application/json

requestID*string

sourceBBID*string

beneficiaries*array of object

Response

200

Beneficiary update successfully received.

Body

application/json

responseCode*string

responseDescription*string

requestID*string

Request

JavaScriptCurlPython

const response = await fetch('/identityAccountMapper/beneficiary', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestID": "text",
      "sourceBBID": "text",
      "beneficiaries": [
        {
          "payeeIdentity": "text"
        }
      ]
    }),
});
const data = await response.json();

Response

200

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

b) Update Beneficiary Response()

This is the API that is called back by the Pay-BB to notify the Source BB via the IM BB that all or selected beneficiaries have been successfully uploaded into the ID Mapper.

Callback to notify beneficiary upload status.

POST/callback

Body

application/json

requestID*string

registerRequestID*string

numberFailedCases*integer

failedCasesarray of object

Response

200

Callback successfully received.

Body

application/json

responseCode*string

responseDescription*string

requestID*string

Request

JavaScriptCurlPython

const response = await fetch('/callback', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "requestID": "text",
      "registerRequestID": "text"
    }),
});
const data = await response.json();

Response

200

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

8.2.4 Bulk disbursement APIs

a) Bulk Payment()

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

Error with https://3117601045-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7nOi3dgSgDbiYpJaFDBN%2Fuploads%2Fgit-blob-e73fd4ddb8e454fcfb6074db3b4e48718065750e%2FBulkPayment%20(1).yml?alt=media: Failed to parse YAML: Map keys must be unique; "parameters" is repeated

b) BulkPayment_StatusPush()

This API is expected to be invoked by Payer Bank to the Payments BB to provide updates status of a batch or individual credit instructions. This API is a callback. This API will also serve BulkPayment_Status_Update() from Payments BB to Source BB If the callback fails, the same response can be obtained by directly calling this API ( with case 2 endpoint)

c) Payment_Status_Check Request()

This API is to be invoked by the Source BB to the Payments BB in case the Source BB (SBB) does not receive some completed transactions in bulk payment status updates callback or batch by batchId polling from the Payments BB. Then SBB can run a query for a single beneficiary payment status check.

8.2 Voucher Management APIs

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

8.2.1 VoucherPreActivation

a) VoucherPreActivation()

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.

Create vouchers in the Voucher Engine.

POST/vouchers

Header parameters

Body

application/json

Details required for voucher creation.

requestIDstring

Globally unique ID.

batchIDstring

BatchID for batch.

voucherInstructionsarray of object

Response

200

Response from the Voucher Engine.

Body

application/json

ResponseCodestring

Status code of the response.

ResponseDescriptionstring

Detailed response description.

RequestIDstring

Echoed from Request.

Request

JavaScriptCurlPython

const response = await fetch('/vouchers', {
    method: 'POST',
    headers: {
      "X-Callback-URL": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "ResponseCode": "text",
  "ResponseDescription": "text",
  "RequestID": "text"
}

b) Create_Vouchers_Response()

Description This is the API called by the Voucher Engine to return Voucher Details once vouchers have been created in the Voucher Engine.

Return created vouchers' details from Voucher Engine.

POST/voucher-details-return

Body

application/json

Details of the created vouchers.

requestIDstring

Globally unique ID.

batchIDstring

BatchID for batch.

voucherInstructionsarray of object

Response

200202

Voucher details successfully received by Source BB.

Request

JavaScriptCurlPython

const response = await fetch('/voucher-details-return', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

8.2.2 VoucherActivation

a) Voucher_Activation()

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.

Update the status of vouchers.

PUT/vouchers

Query parameters

Body

application/json

Details of the vouchers to be updated.

RequestIDstring

Globally unique ID.

BatchIDstring

BatchID for batch.

VoucherInstructionsarray of object

Response

200

Voucher status successfully updated by Voucher Engine.

Body

application/json

ResponseCodestring

Response code (00 for success, 01 for failure).

ResponseDescriptionstring

Description of the response.

RequestIDstring

Echoed from Request.

Request

JavaScriptCurlPython

const response = await fetch('/vouchers?command=text', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "ResponseCode": "text",
  "ResponseDescription": "text",
  "RequestID": "text"
}

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

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

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

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

b) Voucher_Activate_Response()

Description This is the response API called by the Voucher Engine to confirm the status of batch activation back to the calling BB.

Confirm the status of batch activation.

POST/callback-url

Body

application/json

Activation status details.

requestIDstring

Globally unique ID.

registerRequestIDstring

Echo the ID of the original Voucher_Activate API call.

numberFailedCasesinteger

Number of failed activation cases.

failedCasesarray of object

Response

200202

Activation confirmation successfully received by Source BB.

Body

application/json

statusenum

Status of the confirmation reception.

successfailed

Request

JavaScriptCurlPython

const response = await fetch('/callback-url', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "status": "success"
}

8.2.3 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).

Redeem a voucher.

POST/vouchers

Authorization

bearerAuth

Query parameters

Body

application/json

Voucher redemption details.

requestIDstring

Globally unique ID.

voucherSerialNumberstring

Voucher Serial Number.

agentIDstring

Agent or Merchant ID.

voucherSecretNumberstring

Voucher secret number for redemption.

Response

200

Voucher redemption details.

Body

application/json

statusinteger

Redemption status (0 for failure, 1 for success).

messagestring

Narration from the Voucher Engine.

serialNumberstring

Serial number of the redeemed voucher.

valuenumber (float)

Amount of the redeemed voucher.

timestampstring (date-time)

Redemption timestamp.

transactionIdstring

Unique transaction ID.

Request

JavaScriptCurlPython

const response = await fetch('/vouchers?command=cancel', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "message": "text",
  "serialNumber": "text",
  "value": 0,
  "timestamp": "2024-11-05T08:29:58.997Z",
  "transactionId": "text"
}

8.2.4 VoucherStatus

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.

Retrieve voucher status.

GET/vouchers/{serialNumber}

Authorization

bearerAuth

Path parameters

serialNumber*string

Unique Reference Number assigned to the voucher.

Query parameters

Response

200400

Voucher status details.

Body

application/json

statusinteger

Voucher status (from 01 to 06, and 9 for error).

serialNumberstring

Serial number of the voucher.

valuenumber (float)

Amount of the voucher.

Request

JavaScriptCurlPython

const response = await fetch('/vouchers/{serialNumber}?fields=status', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

200400

{
  "serialNumber": "text",
  "value": 0
}

8.2.5 VoucherCancellation

Voucher_Cancellation()

Description This API will be called by the Source-BB to update the status of the voucher(s), in the case of cancellation, the status code 03 is sent to the relevant field of the instruction array.

The VoucherCancellation API is used by non-Payments Building Blocks in the GovStack Framework to cancel a voucher. The calling Building Block will capture the voucher number and send it to the Payments Building Block to cancel the voucher.

Cancel a voucher.

POST/vouchers

Authorization

bearerAuth

Query parameters

Body

application/json

Voucher details to be cancelled.

requestIDstring

Globally unique ID.

batchIDstring

Batch ID for the batch.

voucherInstructionsarray of object

Response

200

Voucher cancellation processed.

Body

application/json

responseCodestring

Response code indicating success or failure.

responseDescriptionstring

Description of the response.

requestIDstring

Echoed Request ID.

Request

JavaScriptCurlPython

const response = await fetch('/vouchers?command=cancel', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

---

Voucher_ Cancellation_Response()

Description Response API called by the Voucher Engine to confirm the cancellation of the voucher. The Payments Building Block will respond with a status of Cancelled, Already Cancelled, or Not Existing. The Voucher Cancellation will override the Blocked status and render the voucher permanently unusable.

Confirm voucher cancellation.

POST/vouchers/cancellation/confirmation

Authorization

bearerAuth

Body

application/json

Voucher cancellation confirmation details.

requestIDstring

Globally unique ID.

registerRequestIDstring

Echo the ID of the original Voucher_Cancellation API call.

numberFailedCasesinteger

The number of cases failed.

failedCasesarray of object

Response

200202

Voucher cancellation confirmation processed successfully.

Request

JavaScriptCurlPython

const response = await fetch('/vouchers/cancellation/confirmation', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

8.3 Person-to-Government APIs (P2G) Bill Payments

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

8.3.1 billInquiryBiller

This API is called to inquire about bill details from a Bill Aggregator or Govt Entity.

Retrieve bill information.

GET/bills/{billId}

Authorization

PayerFIAuth

Path parameters

billId*string

ID of the specific Bill invoice

Query parameters

Header parameters

Body

application/json

requestIdstring

billIdstring

Response

202400

Accepted

Body

application/json

responseCodestring

reasonstring

requestIdstring

Request

JavaScriptCurlPython

const response = await fetch('/bills/{billId}?fields=inquiry', {
    method: 'GET',
    headers: {
      "X-CorrelationID": "text",
      "Platform-TenantId": "text",
      "PayerFI-Id": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

202400

{
  "responseCode": "text",
  "reason": "text",
  "requestId": "text"
}

8.3.2 billrInquiryResponse

The Payment BB updates the Bill Aggregator or government entity on the status of the Request to Pay.

Send bill inquiry response.

POST/bills/{billId}

Authorization

PayerFIAuth

Header parameters

Body

application/json

requestIdstring

codeenum

01

reasonstring

billIdstring

billDetailsobject

Response

200400

Successful Response

Body

application/json

responseCodestring

reasonstring

requestIDstring

Request

JavaScriptCurlPython

const response = await fetch('/bills/{billId}', {
    method: 'POST',
    headers: {
      "X-CorrelationID": "text",
      "Platform-TenantId": "text",
      "PayerFI-Id": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.3 markBillPayment

This API marks a bill as paid.

Mark a specific bill as paid.

POST/billTransferRequests

Authorization

PaymentsBBAuth

Header parameters

Body

application/json

requestIDstring

billIdstring

PaymentReferenceIDstring

Response

202400

Request Accepted

Body

application/json

responseCodestring

reasonstring

requestIDstring

Request

JavaScriptCurlPython

const response = await fetch('/billTransferRequests', {
    method: 'POST',
    headers: {
      "X-CorrelationID": "text",
      "X-Platform-TenantId": "text",
      "X-Payer FI-ID": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

202400

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.4 billerRtpReq

The Bill Aggregator or Govt Entity initiates a “Request to Pay” (RTP) through this API.

Update Payments BB with the status of a Bill Payment Notification.

POST/billTransferRequests

Authorization

BillerAuth

Header parameters

Body

application/json

requestIdstring

billIdstring

statusenum

ACKRJC

rejectReasonenum

DefDupUnd

Response

202400

Request Accepted

Body

application/json

responseCodestring

reasonstring

requestIDstring

Request

JavaScriptCurlPython

const response = await fetch('/billTransferRequests', {
    method: 'POST',
    headers: {
      "X-CorrelationID": "text",
      "X-Platform-TenantId": "text",
      "X-Payer FI-ID": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

202400

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.5 billerRtpReq

Update the Biller on the RTP response.

POST/rtpUpdate

Authorization

PaymentsBBAuth

Header parameters

Body

application/json

requestIdstring

rtpIdinteger

billIdstring

rtpStatusenum

0001

rejectReasonenum

REW

Response

200

RTP Update Acknowledged

Body

application/json

responseCodestring

responseDescriptionstring

requestIDstring

Request

JavaScriptCurlPython

const response = await fetch('/rtpUpdate', {
    method: 'POST',
    headers: {
      "X-CorrelationID": "text",
      "X-Platform-TenantId": "text",
      "X-billerId": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "responseCode": "text",
  "responseDescription": "text",
  "requestID": "text"
}

8.3.6 rtpStatusUpdate

This API allows the Biller or Aggregator to inquire about the status of its RTP.

Inquire about the status of RTP.

GET/transferRequests/{transferRequestId}

Authorization

PaymentsBBAuth

Path parameters

transferRequestId*string

Transfer request ID

Header parameters

Body

application/json

RequestIdstring

rtpIdinteger

Response

202400

Request accepted.

Body

application/json

responseCodestring

reasonstring

requestIDstring

Request

JavaScriptCurlPython

const response = await fetch('/transferRequests/{transferRequestId}', {
    method: 'GET',
    headers: {
      "X-CorrelationID": "text",
      "X-Platform-TenantId": "text",
      "X-billerId": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

202400

{
  "responseCode": "text",
  "reason": "text",
  "requestID": "text"
}

8.3.7 rtpStatusUpdateResponse

This API allows the Biller or Aggregator to receive the status of its RTP.

RTP Status Response.

POST/transferRequests/{transferRequestId}

Authorization

PaymentsBBAuth

Path parameters

transferRequestId*string

Transfer request ID

Header parameters

Body

application/json

rtpIdinteger

RequestIdstring

requestStatusenum

COMPNDEXPCANRJC

PaymentReferenceIDstring

lastUpdateDateinteger

Response

202400

Request accepted.

Body

application/json

ResponseCodestring

reasonstring

requestIDstring

Request

JavaScriptCurlPython

const response = await fetch('/transferRequests/{transferRequestId}', {
    method: 'POST',
    headers: {
      "X-CorrelationID": "text",
      "X-Platform-TenantId": "text",
      "X-billerId": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

202400

{
  "ResponseCode": "text",
  "reason": "text",
  "requestID": "text"
}