API Create Transaction

This is the first call you make in order to initiate a transaction.

POST /bluebox/secure/createTx HTTP/1.1

Create Request Parameters

callbackUrlstringThis is the URL that the consumer will be redirected to once the transaction is complete.Up to 400 characters
amountnumberThe amount for the transaction being performed
referencestringMerchant reference and must be unique for every transaction.1 to 45 characters is permitted
requestShippingbooleanIt is used to determine if the merchant wants to request shipping or not during the transaction.
rrn2stringThis is a secondary RRN in cases where merchants require an additional RRN value passed back besides the bank RRNMust be 12 characters left filled with zeroes
terminalIdstringIt allows an additional terminal id or application id to be sent on the purchase transaction to the acquirer.Up to 40 characters
subMerchantNamestringTo 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 acquirerUp to 40 characters
mccintegerThis is the merchant category code for the transacting merchantMust be 4 numeric digits
cartItems[]ArrayAllows you to pass in cart items that can they be used for limit checking

Create Response Parameters

referencestringThis is the reference echoed back as per the reference used in the CreateTx request
redirectUrlstringThis the URL that the merchant must redirect to after the CreateTx request has been done
statusstringThis is a status to confirm that the CreateTx request has been successfully processed and a redirectUrl has been returned for the merchant to use. Values returned:



If FAILED redirectUrl will not be returned

Sample Requests and Responses

createTx sample request without additional cart items

    "callbackUrl": "",
    "amount": 10.00,
    "reference": "c7206a87-5f31-49f5-9a6b-7638b079644c",
    "description": "My Basket of goods",
    "requestShipping": "false"

createTx sample response


createTx sample request with additional cart items

    "callbackUrl": "",
    "amount": 10.00,
    "reference": "a3f7b4e7-6702-480b-accf-84d89f58f432",
    "cartItems": [

            "description": "USB Mouse",
            "quantity": "1",
            "value": 50.00,
            "imageURL": "https://Masterpasstest.oltio.co.za/item1.png"
            "description": "Airtime Purchase",
            "quantity": "1",
            "value": 30.00,
            "imageURL": "https://Masterpasstest.oltio.co.za/item2.png",
            "destination": "27831234567",
            "itemType": "AIRTIME"
        }, {
            "description": "Bundle Purchase",
            "quantity": "1",
            "value": 100.00,
            "imageURL": "https://Masterpasstest.oltio.co.za/item3.png",
            "destination": "27821234567",
            "itemType": "AIRTIME_BUNDLE"
    "description": "My Basket of goods",
    "productType": "web",
    "requestShipping": "true"