Generate a transactional code that can then be paid for by a cardholder. This code can be represented as a QR code, transferred using NFC or manually entered into a device. The code can also be used as part of an In App payment.
URL STRUCTURE /code/create METHOD POST
Parameters
Parameter
Type
Description
amount
BigDecimal
This is mandatory. To use a variable amount use 0 as the amount. The currency is tied to the merchant setup.
merchantReference
String
This is a mandatory merchant reference. Use this to link this code to a transaction.
expiryDate
Long
This is optional. If this is empty the code will by default expire in 30 minutes from issue. If this value is 0 the code will never expire. This time is specified in epoch.
useOnce
Boolean
This is optional. Default is true. If you want to reuse the same code multiple times set this to false.
limitBasket
String
This is an optional parameter. It also allows limits to be checked if the destination msisdn and item type is specified. The itemType can be either AIRTIME or AIRTIME_BUNDLE. The merchant account needs to be enabled to allow limits to be checked. This parameter cannot be used with a variable amount or if useOnce is true or with partial payments. If cartItems is used then the parameters to be used is as follows:[{description:USB Mouse, quantity:1,value:50.00,imageURL:https://ragstest.oltio.co. za/item1.png}],[{description:Airtime Purchase,quantity:1, value:30.00,imageURL: https://ragstest.oltio.co.za/item2.png,destination:2783123456 7,itemType:AIRTIME}],[{description:Bundle Purchase,quantity:1, value:100.00,imageURL: https://ragstest.oltio.co.za/item3.png,destination:2782123456 7,itemType:AIRTIME_BUNDLE}]
shortDescription
String
This is a mandatory parameter. This will be displayed to the consumer at the time a code is scanned. Length is 5 to 45 characters
requestPartialPayment
Boolean
This is an optional parameter. If present the consumer will be allowed to edit the amount before payment.
requestTip
Boolean
This is an optional parameter. If present the consumer will be prompted to enter a tip amount. In order to use the requestTip function requestPartialPayment must also be set to true.
subMerchantName
String
This is an optional parameter. To be used if there is a sub-merchant linked to the original merchant. This will be displayed on the consumer's bank statement if supported by the merchant's acquirer.
terminalId
String
This is an optional parameter. It allows an additional terminal id or application id to be sent on the purchase transaction to the acquirer. Please note this terminal id will replace the terminal id used in the original merchant configuration and could therefore cause bank settlement issues.
smsNotify
String
This is an optional parameter. It allows SMS notifications to be sent at code level. A maximum of 3 msisdns (mobile numbers) is permitted and must be sent in international format. Must be comma separated.
emailNotify
String
This is an optional parameter. It allows email notifications to be sent at code level. A maximum of 5 email addresses is permitted. Must be comma separated.
rrn2
String
This is an optional parameter. This is a secondary RRN in cases where merchants require an additional RRN value passed back besides the bank RRN. Must be 12 characters left filled with zeroes.
Sample Requests
Basic
{
amount: 10,
merchantReference: TestMerchRef12, shortDescription: Basket of Goods
}
This is the formatted amount with the currency symbol or blank/null if variable amount.
currency
String
This is the currency for the amount. Eg. ZAR
merchantReference
String
The merchant supplied reference.
expiryDate
Long
Date until the code is valid. This is in epoch time.
useOnce
Boolean
Indicates if this code is reusable.
merchantName
String
The merchant name.
ShortDescription
String
A short description of the product.
productURL
String
The product URL. This is optional.
Errors
Http Response
Description
431
The code does not exist.
439
The code is not valid code.
512
General System Error.
512
General system error.
Update Code
Update a previously created code. The changes will take effect immediately.
URL STRUCTURE /code/{code}
METHOD PUT
Parameters
Parameter
Type
Description
Amount
BigDecimal
This is optional. If it is left blank the code will have a variable amount
merchantReference
BigDecimal
This is a mandatory merchant reference. Use this to link this code to a transaction in the merchant system.
expiryDate
Long
This is optional. If this is empty the code will by default expire in 30 minutes from issue. If this value is 0 the code will never expire. This time is specific in epoch.
useOnce
Boolean
This is optional. Default is true. If you want to reuse the same code multiple times set this to false.
shortDescription
String
This is a mandatory short description. This must be 5 to 45 in length.
productURL
String
This is an optional product URL. This must be the full URL starting with http or https.
Returns – HTTP 200
Parameter
Type
Description
amountString
String
This is the formatted amount with the currency symbol or blank/null if variable amount.
currency
String
This is the currency for the amount. Eg. ZAR
merchantReference
String
The merchant supplied reference.
expiryDate
Long
Date until the code is valid. This is in epoch time.
useOnce
Boolean
Indicates if this code is reusable.
merchantName
String
The merchant name.
ShortDescription
String
A short description of the product.
productURL
String
The product URL. This is optional.
limitBasket
String
This is an optional parameter. It allows limits to be applied to the basket when sent on the request for airtime and bundles. This parameter comprises of destination which is the mobile number for which the top-up will be done; amount for each basket item and itemType referes to either AIRTIME or AIRTIME_BUNDLE. It can only be used if useOnce is true.
