Provision vouchers by API
While tenants can use the voucher admin portal to create voucher programmes and provision vouchers they can also call a simple API to provision vouchers. This covers the common use case where tenants want to sell vouchers directly from their own platforms.
Note
This scenario covers the provision of vouchers from a funded voucher organisation wallet. The tenant can also utilise Eclipse to collect funds for the payment of vouchers use the range of Eclipse payment capability. For more information please refer to Acquiring Use Cases.
Prerequisites
- Tenants needs to be onboarded as a Scan To Pay voucher partner and be added as an admin user to the Scan To Pay Voucher portal - contact your account manager for more details.
- JWT issued using the Scan To Pay Voucher portal admin user credentials.
- The following tenant configs must be set:
- allowVoucherWallet - must be set to true
- source.wallet.config.STP_VOUCHER.{orgId} - must be set to the wallet ID of the wallet from which voucher funds will be disbursed.
- oltio.config.{orgId}.username - must be set the oltio config for the specific organization if not specified then it will pick tenant level config.
- oltio.config.{orgId}.password- must be set the oltio config for the specific organization if not specified then it will pick tenant level config.
- mustache.app.notification.body.{orgId}.program.{programId}- Required to send the notification and it will be configured on tenant level.
- mustache.app.notification.title.{orgId}.program.{programId} - Required to send the notification and it will be configured on tenant level.
- mustache.sms.{orgId}.program.{programId} - Required to send the notification and it will be configured on tenant level.
To provision a voucher, tenants just need to call the POST wallets endpoint for wallet type STP_VOUCHER and pass in the following additional information:
Field | Description |
---|---|
tenantId | Scan To Pay Vouchers sandbox tenantId=11131, Scan To Pay Vouchers production tenantId=13561 |
organisationId | The ID assigned to your voucher organisation. Request this from [email protected] or your account manager |
voucherProgramme | This is the ID assigned to your voucher programme. Request this from [email protected] or your account manager |
voucherValue | The value of the voucher to provision, e.g. R100 |
voucherPhoneNumber | The phone number to provision the voucher against |
walletTypeId | This specifies the type of voucher to be provisioned. For generic, Scan To Pay vouchers use sandbox STP_VOUCHER walletTypeId=7264, production STP_VOUCHER walletTypeId=208 |
createVoucherPin | By default, this will generate a 16-digit voucher PIN if not passed or passed as true. If you do not want to create a voucher PIN, set the createVoucherPin attribute to false. Voucher PIN creation and readability can be controlled through the following permissions. If these permissions are not set, the default behavior is to allow both actions: Create Permission: Wallet.VoucherPin.WalletType{WalletTypeID}.CREATE.Allowed Read Permission: Wallet.VoucherPin.WalletType{WalletTypeID}.READ.Allowed |
provisionStpVoucher | Applicable for the case of STP vouchers for PNP and ATM, provisionStpVoucher field needs to be set as true OR false. Creating a wallet with "provisionStpVoucher" set to false creates a wallet in Eclipse, and funds it, but it does not create a card in STP and does not send a notification. Creating a wallet with "provisionStpVoucher" set to true creates a wallet, links a card in STP, and sends a notification as normal. |
Example request:
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisactionId}/wallets
{
"configuration": [
{
"att": "voucherProgramme",
"val": "123445343"
},
{
"att": "voucherValue",
"val": "10"
},
{
"att": "voucherPhoneNumber",
"val": "27727863453"
},
{
"att": "programId",
"val": "{programId}"
}
],
"description": "STP Voucher Wallet 1",
"externalUniqueId": "123456789013543533534534",
"name": "STP Voucher Wallet 1",
"status": "ACTIVE",
"walletTypeId": 7264
}
Note
A provisioned voucher creates a wallet on Eclipse as well as provisions the voucher to Scan to Pay user identified by phone number so that is it available for use in the STP App. In some scenarios tenants may only want to create wallets in Eclipse and then use voucher pin for redemption. In these scenarios wallet attribute provisionStpVoucher can be included and set to false and the voucherPhoneNumber attribute is then optional.
Updated 3 days ago