Integration Guides
Start typing to search…

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

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    BigDecimal
  </td>

  <td>
    This is mandatory. To use a variable amount use 0 as the amount. The currency is tied to the merchant setup.
  </td>
</tr>

<tr>
  <td>
    merchantReference
  </td>

  <td>
    String
  </td>

  <td>
    This is a mandatory merchant reference. Use this to link this code to a transaction.
  </td>
</tr>

<tr>
  <td>
    expiryDate
  </td>

  <td>
    Long
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    useOnce
  </td>

  <td>
    Boolean
  </td>

  <td>
    This is optional. Default is true. If you want to reuse the same code multiple times set this to false.
  </td>
</tr>

<tr>
  <td>
    limitBasket
  </td>

  <td>
    String
  </td>

  <td>
    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}]
  </td>
</tr>

<tr>
  <td>
    shortDescription
  </td>

  <td>
    String
  </td>

  <td>
    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
  </td>
</tr>

<tr>
  <td>
    requestPartialPayment
  </td>

  <td>
    Boolean
  </td>

  <td>
    This is an optional parameter. If present the consumer will be allowed to edit the amount before payment.
  </td>
</tr>

<tr>
  <td>
    requestTip
  </td>

  <td>
    Boolean
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    subMerchantName
  </td>

  <td>
    String
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    terminalId
  </td>

  <td>
    String
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    smsNotify
  </td>

  <td>
    String
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    emailNotify
  </td>

  <td>
    String
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    rrn2
  </td>

  <td>
    String
  </td>

  <td>
    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.
  </td>
</tr>
Parameter
amount

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

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    This is the result code
  </td>
</tr>

<tr>
  <td>
    expiryDate
  </td>

  <td>
    Long
  </td>

  <td>
    Date until the code is valid. This is in epoch time.
  </td>
</tr>
Parameter
code

Sample Requests

{
code: 8227541409,
expiryDate: 1375293705000
}

Errors

  <th>
    Description
  </th>
</tr>

  <td>
    Missing parameter or not valid JSON.
  </td>
</tr>

<tr>
  <td>
    403
  </td>

  <td>
    Invalid merchant login details or merchant suspended.
  </td>
</tr>

<tr>
  <td>
    440
  </td>

  <td>
    Validation error.
  </td>
</tr>

<tr>
  <td>
    500
  </td>

  <td>
    General system error.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General system error.
  </td>
</tr>
Http Response
400

Query Code

Delete a code that has been created

URL STRUCTURE /code/{code}
METHOD DELETE

Parameters

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    The code that is being deleted.
  </td>
</tr>
Parameter
\{code}

Returns – HTTP 200

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    This is the formatted amount with the currency symbol or blank/null if variable amount.
  </td>
</tr>

<tr>
  <td>
    currency
  </td>

  <td>
    String
  </td>

  <td>
    This is the currency for the amount. Eg. ZAR
  </td>
</tr>

<tr>
  <td>
    merchantReference
  </td>

  <td>
    String
  </td>

  <td>
    The merchant supplied reference.
  </td>
</tr>

<tr>
  <td>
    expiryDate
  </td>

  <td>
    Long
  </td>

  <td>
    Date until the code is valid. This is in epoch time.
  </td>
</tr>

<tr>
  <td>
    useOnce
  </td>

  <td>
    Boolean
  </td>

  <td>
    Indicates if this code is reusable.
  </td>
</tr>

<tr>
  <td>
    merchantName
  </td>

  <td>
    String
  </td>

  <td>
    The merchant name.
  </td>
</tr>

<tr>
  <td>
    ShortDescription
  </td>

  <td>
    String
  </td>

  <td>
    A short description of the product.
  </td>
</tr>

<tr>
  <td>
    productURL
  </td>

  <td>
    String
  </td>

  <td>
    The product URL. This is optional.
  </td>
</tr>
Parameter
amountString

Sample Requests

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

Errors

  <th>
    Description
  </th>
</tr>

  <td>
    The code does not exist.
  </td>
</tr>

<tr>
  <td>
    439
  </td>

  <td>
    The code is not valid code.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General System Error.
  </td>
</tr>
Http Response
431

Delete Code

Query a code that has been created.

URL STRUCTURE /code/{code} '
METHOD GET

Parameters

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    The code that is being queried.
  </td>
</tr>
Parameter
\{code}

Returns – HTTP 200

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>
Parameter 
  </td>

  <td>

  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    amountString
  </td>

  <td>
    String
  </td>

  <td>
    This is the formatted amount with the currency symbol or blank/null if variable amount.
  </td>
</tr>

<tr>
  <td>
    currency
  </td>

  <td>
    String
  </td>

  <td>
    This is the currency for the amount. Eg. ZAR
  </td>
</tr>

<tr>
  <td>
    merchantReference
  </td>

  <td>
    String
  </td>

  <td>
    The merchant supplied reference.
  </td>
</tr>

<tr>
  <td>
    expiryDate
  </td>

  <td>
    Long
  </td>

  <td>
    Date until the code is valid. This is in epoch time.
  </td>
</tr>

<tr>
  <td>
    useOnce
  </td>

  <td>
    Boolean
  </td>

  <td>
    Indicates if this code is reusable.
  </td>
</tr>

<tr>
  <td>
    merchantName
  </td>

  <td>
    String
  </td>

  <td>
    The merchant name.
  </td>
</tr>

<tr>
  <td>
    ShortDescription
  </td>

  <td>
    String
  </td>

  <td>
    A short description of the product.
  </td>
</tr>

<tr>
  <td>
    productURL
  </td>

  <td>
    String
  </td>

  <td>
    The product URL. This is optional.
  </td>
</tr>

Errors

  <th>
    Description
  </th>
</tr>

  <td>
    The code does not exist.
  </td>
</tr>

<tr>
  <td>
    439
  </td>

  <td>
    The code is not valid code.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General System Error.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General system error.
  </td>
</tr>
Http Response
431

Update Code

Update a previously created code. The changes will take effect immediately.

URL STRUCTURE /code/{code}
METHOD PUT

Parameters

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>
Parameter 
  </td>

  <td>

  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    Amount
  </td>

  <td>
    BigDecimal
  </td>

  <td>
    This is optional. If it is left blank the code will have a variable amount
  </td>
</tr>

<tr>
  <td>
    merchantReference
  </td>

  <td>
    BigDecimal
  </td>

  <td>
    This is a mandatory merchant reference. Use this to link this code to a transaction in the merchant system.
  </td>
</tr>

<tr>
  <td>
    expiryDate
  </td>

  <td>
    Long
  </td>

  <td>
    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.
  </td>
</tr>

<tr>
  <td>
    useOnce
  </td>

  <td>
    Boolean
  </td>

  <td>
    This is optional. Default is true. If you want to reuse the same code multiple times set this to false.
  </td>
</tr>

<tr>
  <td>
    shortDescription
  </td>

  <td>
    String
  </td>

  <td>
    This is a mandatory short description. This must be 5 to 45 in length.
  </td>
</tr>

<tr>
  <td>
    productURL
  </td>

  <td>
    String
  </td>

  <td>
    This is an optional product URL. This must be the full URL starting with http or https.
  </td>
</tr>

Returns – HTTP 200

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    This is the formatted amount with the currency symbol or blank/null if variable amount.
  </td>
</tr>

<tr>
  <td>
    currency
  </td>

  <td>
    String
  </td>

  <td>
    This is the currency for the amount. Eg. ZAR
  </td>
</tr>

<tr>
  <td>
    merchantReference
  </td>

  <td>
    String
  </td>

  <td>
    The merchant supplied reference.
  </td>
</tr>

<tr>
  <td>
    expiryDate
  </td>

  <td>
    Long
  </td>

  <td>
    Date until the code is valid. This is in epoch time.
  </td>
</tr>

<tr>
  <td>
    useOnce
  </td>

  <td>
    Boolean
  </td>

  <td>
    Indicates if this code is reusable.
  </td>
</tr>

<tr>
  <td>
    merchantName
  </td>

  <td>
    String
  </td>

  <td>
    The merchant name.
  </td>
</tr>

<tr>
  <td>
    ShortDescription
  </td>

  <td>
    String
  </td>

  <td>
    A short description of the product.
  </td>
</tr>

<tr>
  <td>
    productURL
  </td>

  <td>
    String
  </td>

  <td>
    The product URL. This is optional.
  </td>
</tr>

<tr>
  <td>
    limitBasket
  </td>

  <td>
    String
  </td>

  <td>
    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.
  </td>
</tr>
Parameter
amountString

Sample Requests

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

Errors

  <th>
    Description
  </th>
</tr>
Http Response 
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    400
  </td>

  <td>
    Missing parameter or not valid JSON.
  </td>
</tr>

<tr>
  <td>
    403
  </td>

  <td>
    Invalid merchant login details or merchant suspended.
  </td>
</tr>

<tr>
  <td>
    440
  </td>

  <td>
    Validation Error.
  </td>
</tr>

<tr>
  <td>
    500
  </td>

  <td>
    General System Error.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General System Error.
  </td>
</tr>

<tr>
  <td>
    513
  </td>

  <td>
    The code does not belong to the merchant requesting the delete.
  </td>
</tr>

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

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    The code that is being blocked.
  </td>
</tr>
Parameter
\{code}

Sample Requests

Errors

  <th>
    Description
  </th>
</tr>

  <td>
    The code does not exist.
  </td>
</tr>

<tr>
  <td>
    439
  </td>

  <td>
    The code is not valid code.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General System Error.
  </td>
</tr>

<tr>
  <td>
    513
  </td>

  <td>
    General System Error.
  </td>
</tr>
Http Response
431

Unblock Code

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

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

Parameters

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    The code that is being unblocked.
  </td>
</tr>
Parameter
\{code}

Sample Requests

Errors

  <th>
    Description
  </th>
</tr>

  <td>
    The code does not exist.
  </td>
</tr>

<tr>
  <td>
    439
  </td>

  <td>
    The code is not valid code.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General System Error.
  </td>
</tr>

<tr>
  <td>
    513
  </td>

  <td>
    General System Error.
  </td>
</tr>
Http Response
431

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

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    String
  </td>

  <td>
    The code that is being unblocked.
  </td>
</tr>

<tr>
  <td>
    amount
  </td>

  <td>
    BigDecimal
  </td>

  <td>
    The new amount for that code
  </td>
</tr>

<tr>
  <td>
    expiryDate
  </td>

  <td>
    Long
  </td>

  <td>
    This is optional. If this is empty the code will by default expire in 30 minutes from issue. This time is specified in epoch.
  </td>
</tr>
Parameter
\{code}

Sample Requests

{
amount: 20.5
}

Errors

  <th>
    Description
  </th>
</tr>

  <td>
    The code does not exist.
  </td>
</tr>

<tr>
  <td>
    439
  </td>

  <td>
    The code is not valid code.
  </td>
</tr>

<tr>
  <td>
    512
  </td>

  <td>
    General System Error.
  </td>
</tr>

<tr>
  <td>
    513
  </td>

  <td>
    The code does not belong to the merchant requesting the delete.
  </td>
</tr>
Http Response
431

Updated 11 days ago