Code Management

Description

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
}

With limit Basket and Sub-Merchant

{
amount: 1000,
merchantReference:  TestMerchRef10, shortDescription: Basket of Goods, expiryDate: 0,
subMerchantName: The Shop, terminalId: 0000KFB1, requestPartialPayment:  true, requestTip: true,
useOnce: false, limitBasket:
[
{destination:27832006283, itemType:AIRTIME, amount: 500.00
}
]
}

With extra notifications and Sub-Merchant

{
amount: 10,
merchantReference:  TestMerchRef11, shortDescription: Basket of Goods, expiryDate: 0,
subMerchantName: The Shop, terminalId: 0000KFB1,
smsNotify: [27832006283,27832229174],
emailNotify: [[email protected], [email protected]], useOnce: false
}

Returns – HTTP 200

Parameter	Type	Description
code	String	This is the result code
expiryDate	Long	Date until the code is valid. This is in epoch time.

Sample Requests

{
code: 8227541409,
expiryDate: 1375293705000
}

Errors

Http Response	Description
400	Missing parameter or not valid JSON.
403	Invalid merchant login details or merchant suspended.
440	Validation error.
500	General system error.
512	General system error.

Query Code

Delete a code that has been created

URL STRUCTURE /code/{code}
METHOD DELETE

Parameters

Parameter	Type	Description
{code}	String	The code that is being deleted.

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.

Sample Requests

{
amountString: R 10.50, merchantReference: t0002, expiryDate: 1375293705000, useOnce: true,
merchantName: Merchant One, shortDescription: Samsung Galaxy S4, productURL: null,
extra: null
}

Errors

Http Response	Description
431	The code does not exist.
439	The code is not valid code.
512	General System Error.

Delete Code

Query a code that has been created.

URL STRUCTURE /code/{code} '
METHOD GET

Parameters

Parameter	Type	Description
{code}	String	The code that is being queried.

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.

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.

Sample Requests

{
amount: 10.5, merchantReference: t0002, expiryDate: 1375293705696, useOnce: true,
shortDescription: Samsung Galaxy S4
}

Errors

Http Response	Description

400	Missing parameter or not valid JSON.
403	Invalid merchant login details or merchant suspended.
440	Validation Error.
500	General System Error.
512	General System Error.
513	The code does not belong to the merchant requesting the delete.

Block Code

This is an API call to temporarily block a code. This prevents purchases on the code.

URL STRUCTURE /code/{code}/block
METHOD PUT

Parameters

Parameter	Type	Description
{code}	String	The code that is being blocked.

Sample Requests

Errors

Http Response	Description
431	The code does not exist.
439	The code is not valid code.
512	General System Error.
513	General System Error.

Unblock Code

This unblocks a blocked code. This call enables future purchases on that code.

URL STRUCTURE /code/{code}/unblock
METHOD PUT

Parameters

Parameter	Type	Description
{code}	String	The code that is being unblocked.

Sample Requests

Errors

Http Response	Description
431	The code does not exist.
439	The code is not valid code.
512	General System Error.
513	General System Error.

Update Code Amount

This updates only the amount for a given code. This is done generally when the code is static

URL STRUCTURE /code/{code}/amount
METHOD PUT

Parameters

Parameter	Type	Description
{code}	String	The code that is being unblocked.
amount	BigDecimal	The new amount for that code
expiryDate	Long	This is optional. If this is empty the code will by default expire in 30 minutes from issue. This time is specified in epoch.

Sample Requests

{
amount: 20.5
}

Errors

Http Response	Description
431	The code does not exist.
439	The code is not valid code.
512	General System Error.
513	The code does not belong to the merchant requesting the delete.