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

Parameter	Type	Description	Size
callbackUrl	string	This is the URL that the consumer will be redirected to once the transaction is complete.	Up to 400 characters
amount	number	The amount for the transaction being performed
reference	string	Merchant reference and must be unique for every transaction.	1 to 45 characters is permitted
requestShipping	boolean	It is used to determine if the merchant wants to request shipping or not during the transaction.
rrn2	string	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
terminalId	string	It allows an additional terminal id or application id to be sent on the purchase transaction to the acquirer.	Up to 40 characters
subMerchantName	string	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	Up to 40 characters
mcc	integer	This is the merchant category code for the transacting merchant	Must be 4 numeric digits
cartItems[]	Array	Allows you to pass in cart items that can they be used for limit checking
cartItems[].description	string
cartItems[].quantity	string
cartItems[].value	string
cartItems[].imageURL	string
cartItems[].destination	string
cartItems[].itemType	string

Create Response Parameters

Parameter	Type	Description
reference	string	This is the reference echoed back as per the reference used in the CreateTx request
redirectUrl	string	This the URL that the merchant must redirect to after the CreateTx request has been done
status	string	This 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: SUCCESS FAILED [FAIL REASON] If FAILED redirectUrl will not be returned

Parameter

Type

Description

reference

string

This is the reference echoed back as per the reference used in the CreateTx request

redirectUrl

string

This the URL that the merchant must redirect to after the CreateTx request has been done

status

string

This 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:

SUCCESS
FAILED [FAIL REASON]

If FAILED redirectUrl will not be returned

Sample Requests and Responses

createTx sample request without additional cart items

{
    "callbackUrl": "http://127.0.0.1:8080/ostore/callback",
    "amount": 10.00,
    "reference": "c7206a87-5f31-49f5-9a6b-7638b079644c",
    "description": "My Basket of goods",
    "requestShipping": "false"
}

createTx sample response

{
    "ref":"56c5181a-4485-4805-9925-ac6e22e9d4f5",
    "redirectUrl":"https://Masterpasstest.oltio.co.za/bluebox/public/redirect/91f8f61d58fa8dd3",
    "status":"SUCCESS"
}

createTx sample request with additional cart items

{
    "callbackUrl": "http://127.0.0.1:8080/ostore/callback",
    "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"
}