LogoLogo
Give FeedbackGovStack Home
23Q4
23Q4
  • Payments
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
    • 8.1 Government to Person (G2P) payments
    • 8.2 Voucher Management APIs
    • 8.3 Person-to-Government APIs (P2G) Bill Payments
  • 9 Internal Workflows
  • 10 Other Resources
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF
  1. 8 Service APIs

8.2 Voucher Management APIs

Last updated 2 months ago

Was this helpful?

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.

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.

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.

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.

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

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.

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.


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.

Return created vouchers' details from Voucher Engine.

post
Body
requestIDstring · max: 12Optional

Globally unique ID.

batchIDstring · max: 12Optional

BatchID for batch.

Responses
200
Voucher details successfully received by Source BB.
202
Voucher details acceptance is acknowledged and will be processed by Source BB.
post
POST /voucher-details-return HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "requestID": "text",
  "batchID": "text",
  "voucherInstructions": [
    {
      "instructionID": "text",
      "serialNumber": "text",
      "voucherNumber": "text",
      "currency": "text",
      "amount": null,
      "narration": "text"
    }
  ]
}

No content

Create vouchers in the Voucher Engine.

post
Header parameters
X-Program-Idstring · max: 20Optional

In case a Government Entity has specific budget account for a Program.

X-Registering-Institution-Idstring · max: 20Optional

ID of the Issuing Agency, used for validation and data scoping.

X-Callback-URLstring · max: 100Required

URL on which the result is published.

Body
requestIDstring · max: 12Optional

Globally unique ID.

batchIDstring · max: 12Optional

BatchID for batch.

Responses
200
Response from the Voucher Engine.
application/json
post
POST /vouchers HTTP/1.1
Host: 
X-Callback-URL: text
Content-Type: application/json
Accept: */*
Content-Length: 183

{
  "requestID": "text",
  "batchID": "text",
  "voucherInstructions": [
    {
      "instructionID": "text",
      "groupCode": "text",
      "currency": "text",
      "amount": null,
      "payeeFunctionalID": "text",
      "narration": "text"
    }
  ]
}
200

Response from the Voucher Engine.

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

Retrieve voucher status.

get
Authorizations
Path parameters
serialNumberstring · max: 20Required

Unique Reference Number assigned to the voucher.

Query parameters
fieldsstring · enumRequired

Query parameter to retrieve status.

Possible values:
Responses
200
Voucher status details.
application/json
400
Bad request (invalid voucher serial number).
application/json
get
GET /vouchers/{serialNumber}?fields=status HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
{
  "status": 1,
  "serialNumber": "text",
  "value": 1
}

Confirm voucher cancellation.

post
Authorizations
Body
requestIDstring · max: 12Optional

Globally unique ID.

registerRequestIDstring · max: 12Optional

Echo the ID of the original Voucher_Cancellation API call.

numberFailedCasesintegerOptional

The number of cases failed.

Responses
200
Voucher cancellation confirmation processed successfully.
202
Voucher cancellation confirmation received and is being processed.
post
POST /vouchers/cancellation/confirmation HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "requestID": "text",
  "registerRequestID": "text",
  "numberFailedCases": 1,
  "failedCases": [
    {
      "serialNumber": "text",
      "failureReason": "text"
    }
  ]
}

No content

Confirm the status of batch activation.

post
Body
requestIDstring · max: 12Optional

Globally unique ID.

registerRequestIDstring · max: 12Optional

Echo the ID of the original Voucher_Activate API call.

numberFailedCasesintegerOptional

Number of failed activation cases.

Responses
200
Activation confirmation successfully received by Source BB.
application/json
202
Activation confirmation acknowledged and is under process by Source BB.
post
POST /callback-url HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "requestID": "text",
  "registerRequestID": "text",
  "numberFailedCases": 1,
  "failedCases": [
    {
      "serialNumber": "text",
      "failureReason": "text"
    }
  ]
}
{
  "status": "success"
}

Cancel a voucher.

post
Authorizations
Query parameters
commandstring · enumRequired

Operation command.

Possible values:
Body
requestIDstring · max: 12Optional

Globally unique ID.

batchIDstring · max: 12Optional

Batch ID for the batch.

Responses
200
Voucher cancellation processed.
application/json
post
POST /vouchers?command=cancel HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "requestID": "text",
  "batchID": "text",
  "voucherInstructions": [
    {
      "serialNumber": "text"
    }
  ]
}
200

Voucher cancellation processed.

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

Redeem a voucher.

post
Authorizations
Query parameters
commandstring · enumRequired

Command for the action.

Possible values:
Body
requestIDstring · max: 12Optional

Globally unique ID.

voucherSerialNumberstringOptional

Voucher Serial Number.

agentIDstring · max: 10Optional

Agent or Merchant ID.

voucherSecretNumberstring · max: 6Optional

Voucher secret number for redemption.

Responses
200
Voucher redemption details.
application/json
post
POST /vouchers?command=cancel HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "requestID": "text",
  "voucherSerialNumber": "text",
  "agentID": "text",
  "voucherSecretNumber": "text"
}
200

Voucher redemption details.

{
  "status": 1,
  "message": "text",
  "serialNumber": "text",
  "value": 1,
  "timestamp": "2025-05-13T17:48:59.276Z",
  "transactionId": "text"
}
  • 8.2.1 VoucherPreActivation
  • POSTCreate vouchers in the Voucher Engine.
  • POSTReturn created vouchers' details from Voucher Engine.
  • 8.2.2 VoucherActivation
  • PUTUpdate the status of vouchers.
  • POSTConfirm the status of batch activation.
  • 8.2.3 VoucherRedemption
  • POSTRedeem a voucher.
  • 8.2.4 VoucherStatus
  • GETRetrieve voucher status.
  • 8.2.5 VoucherCancellation
  • POSTCancel a voucher.
  • POSTConfirm voucher cancellation.

Update the status of vouchers.

put
Query parameters
commandstringRequired

For this use case, the value of the command is activate.

Body
RequestIDstring · max: 12Optional

Globally unique ID.

BatchIDstring · max: 12Optional

BatchID for batch.

Responses
200
Voucher status successfully updated by Voucher Engine.
application/json
put
PUT /vouchers?command=text HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "RequestID": "text",
  "BatchID": "text",
  "VoucherInstructions": [
    {
      "serialNumber": "text"
    }
  ]
}
200

Voucher status successfully updated by Voucher Engine.

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