REST API Requests

Generate Transaction Id

This request looks up any QR code/value supported by Scan to Pay related to the payment and returns a transactionId which must then be used on the purchaseTransactionId request to complete the payment.

METHOD: POST
ENDPOINT: /generateTransactionId

Parameter	Type	Description
value	String	The QR value that represents the details required to complete the payment. This can be the 10 digit code, the URL that represents the QR code, the Scan to Pay QR code (tag length specification value). (Mandatory parameter – Max Length ..512ANS)
msisdn	String	MSISDN (mobile number) of the consumer in international format (Mandatory parameter – Max Length 15N)

Returns - HTTP 200

Parameter	Type	Description
status	String	The status of the request. Will always be sent.
value	String	The Scan to Pay QR value that represents the details required to complete the payment. This value must always be used on the purchase request as it could differ from the value on the original lookup request. (Length – 10N)
merchantName	String	The name of the merchant including the sub merchant name if present (Max Length – 100ANS)
data	String	A JSON object representing the below parameters in blue
amount	BigDecimal	The amount related to the value. 0 amount indicates that the value is a variable amount and the actual amount must be sent on the purchase request
currency	String	The currency related to the payment (e.g. R for Rands) (Length – 1ANS)
shortDescription	String	A description of the payment being completed. This should be displayed to the consumer at the time of payment (Max Length – 50ANS)
partialPayment	Boolean	Will be true if the value allows a partial payment and amount must be sent on the purchase request
tipRequired	Boolean	Will be true if a tip is required or false if no tip is required on the purchase request. If true, the tip must be sent on the purchase request
tipFixed	BigDecimal	Will be returned if a tip with a fixed amount is required
tipPercentage	Double	Will be returned if a tip with a percentage is required
contactRequired	Boolean	Will be true if the purchase request requires contact information
shippingRequired	Boolean	Will be true if the purchase request requires shipping information
billingRequired	Boolean	Will be true if the purchase request requires billing information
extraInputRequired	Boolean	Will be true if the purchase request requires an extra input. If true, the extraInput field will be populated with the prompt to be shown to the user
secureCodeMerchantId	String	The merchant id to be used on the ACS call for 3D-Secure (Max Length 50AN)
secureCodeUrl	String	The 3D-Secure URL that will be used to initiate the 3DS process on the MPI Lookup request along with the 3dsMerchantId, 3dsProcessorId and 3dsPassword
secureCodeProcessorId	String	The processor id to be used on the MPI Lookup request
		(Max Length 20AN)
secureCodePassword	String	The password that is to be used with the 3dsMerchantId, 3dsProcessorId and 3dsUrl on the MPI Lookup request (Max Length 50AN)
acceptedCards	String	Returns a comma-separated string value for the accepted card types by association/brand for the merchant requesting payment; can be a combination of the following: master visa maestro diners amex cup
acceptedPaymentMethods	String	Returns a comma-separated string vale describing the payment methods supported for this transactions; can be a combination of the following:
poi	String	Relates to the point of initiation method and whether the data is static or dynamic. The poi is 11 for static QR codes and 12 for dynamic QR codes. Typically, 11 is used when the same QR code can be used for more than one transaction and 12 is used when a new QR code is generated for every transaction.
transactionId	Long	A transaction id related to the purchase transaction, if already generated
originalQrDetail	String	A JSON object showing the breakdown of the Scan to Pay QR code if a supported Scan to Pay QR code was scanned (tag length value QR)
webhook	String	A URL that transaction information be sent to regarding the outcome of a transaction (Optional parameter – Max Length 100AN)
inputsRequired	String	A JSON object representing the below parameters in green. This denotes additional inputs required from the consumer and will need to be used in accordance with the VAS menu. This will only be displayed if additional inputs are required from the app/wallet
ref	String	A reference value that is used to identify the input that is required from the consumer.
title	String	This is the title to be displayed to the consumer in the app/wallet to prompt for the input. @NotNull, @Size(max = 20)
type	String	This represents the type of input required from the consumer. It can be one of the following: TEXT, NUMBER, EMAIL, DROPDOWN. @NotNull
defaultValue		A default value related to the ref input required. @Size(max = 45)
regex	String	Short for regular expression. A sequence of characters that allows the app/wallet to help validate the text/input required as per the type mentioned above. @Size(max = 45)
regexErrorMessage	String	An error message related to the regex value. This can be displayed in the app/wallet should the regex validation fail. @Size(max = 45)

📘
Note
See section 2.2 for non-HTTP 200 responses and errors

Sample Request

Basic Lookup

{
 "msisdn": "27832006283",
 "value": "8656849931"
}

Lookup Requiring Input

{
 "msisdn": "27832006283",
 "value": "https://payat.io/qr/11669"
}

{
 "msisdn": "27832006283",
 "value": "https://payat.io/qr/11669",
     "inputs": [
        {
            "ref": "accountNumber",
            "value": "272257910281"
        }
    ]
}

Basic Lookup With Device Data Sent:

{
 "msisdn": "27832006283",
 "value": "6400594798",
    "deviceData": {
        "os": "Android",
        "osVersion": "9.0",
        "appVersion": "1.5",
        "device": "Huawei Mate 20 Pro",
        "serial": "Serial-1234ABCX",  
        "latitude": "-26.13382683823002",
        "longitude": "28.06927071511155",
        "clientIP": "196.1.2.3"
    }
}

Sample Response

Basic Lookup

{
    "status": "SUCCESS",
    "merchantName": "ABC Test Store",
    "value": "6400594798",
    "transactionId": 469623,
    "data": {
        "amount": 5.75,
        "currency": "R",
        "currencyCode": "710",
        "shortDescription": "Please Pay This",
        "partialPayment": false,
        "tipRequired": false,
        "contactRequired": false,
        "shippingRequired": false,
        "billingRequired": false,
        "extraInputRequired": false,
        "secureCodeMerchantId": "12345678",
        "secureCodeUrl": "https://msgtest.bankserv.co.za/maps/txns.asp",
        "secureCodeProcessorId": "1000",
        "secureCodePassword": "DeMo123",
        "acceptedCards": "master, visa, maestro",
        "acceptedPaymentMethods": "AMT, SECURE_CODE",
        "poi": "12"
    }
}

Lookup Requiring Input

{
    "status": "NEED_INPUT",
    "merchantName": "BillerABC",
    "value": "https://payat.io/qr/11669",
    "inputsRequired": [
        {
            "ref": "accountNumber",
            "title": "Please enter account number",
            "type": "NUMERIC",
            "defaultValue": "",
            "regex": "\\d",
            "regexErrorMessage": "Please enter digits only",
            "template": null
        }
    ]
}

{
    "status": "SUCCESS",
    "merchantName": "BillerABC - CentShop",
    "value": "0014128292",
    "data": {
        "amount": 1000,
        "currency": "R",
        "currencyCode": "710",
        "shortDescription": "Please Complete Payment",
        "partialPayment": true,
        "tipRequired": false,
        "contactRequired": false,
        "shippingRequired": false,
        "billingRequired": false,
        "extraInputRequired": false,
        "secureCodeMerchantId": "12345678",
        "secureCodeUrl": "https://msgtest.bankserv.co.za/maps/txns.asp",
        "secureCodeProcessorId": "1000",
        "secureCodePassword": "DeMo123",
        "acceptedCards": "master, visa, maestro, cup, diners",
        "acceptedPaymentMethods": "AMT, SECURE_CODE",
        "poi": "12"
    }

Purchase Transaction Id

The purchase request that must be sent to initiate a 3DS or AMT transaction to the merchant’s acquirer.

METHOD: POST
ENDPOINT: /purchaseTx

Parameter	Type	Description
msisdn	String	MSISDN (mobile number) of the consumer in international format (Mandatory parameter – Max Length 15N)
value	String	The Scan to Pay value that represents the details required to complete the payment as per the value lookup request (Mandatory parameter – Length 10N)
transactionId	Long	A transaction id related to the purchase transaction, if already generated
cardNumber	String	The card number that will be used for the purchase. A luhn-10 check will be performed on the number (Mandatory parameter – Max length 19N)
account	String	This relates to the account type for the card that the transaction will be performed on. Can be: 00 (DEFAULT), 10 (SAVINGS), 20 (CURRENT/CHEQUE), 30 (CREDIT) (Optional parameter unless required for the card BIN – typically all debit cards require the account type to be sent)
expiryDate	String	Expiry date of the card number if required in the format MMYY (Mandatory parameter)
cardholderName	String	Name of the cardholder
date of Birth	BigDecimal	Date of birth related to the cardholder in the format CCYYMMDD (Required if the issuer requests this for their BINs)
cvv2	String	The card validation value (CVC2), card verification value (CVV2) or card identification value (CID)
secureCodeData	String	A JSON object that includes the secure code data as per the fields shown below in green. This must be sent otherwise the transaction won’t be processed
cavv	String	The Cardholder Authentication Verification Value that will be sent to the issuing bank for authentication. Visa refers to this value as a AVV (Authentication Verification Value) and UKheshe uses UCAF (Universal Cardholder Authentication Field) (Mandatory parameter – Max Length 48AN)
xid	String	The transaction identifier used for 3D-Secure authentication (Mandatory parameter – Max Length 40AN)
eciFlag	String	The Electronic Commerce Indicator (ECI) flag returned by the card issuer via the ACS interface. Accepts the following: UKheshe (01, 02); Visa & Amex (05, 06, 07) (Mandatory parameter – if sent then errorNo, paResStatus and signatureVerification must be populated)
errorNo	String	An application error number returned on the ACS interface for the 3D-Secure call (Mandatory parameter – Length 1N)
paResStatus	String	The transaction status result identifier as returned on the ACS interface for the 3D-Secure call (Mandatory parameter – Can be Y, N, U, A)
signatureVerification	String	The transaction signature status identifier as returned on the ACS interface for the 3D-Secure call (Mandatory parameter – Can be Y or N)
pinData	String	Subfield: encryptedData - A string value of the encrypted payload that is sent on the response from the PinSecLib library (Mandatory parameter if transaction is AMT)
secureCodeBasic	String	A JSON object containing the following subfields:
		A JSON object containing the following subfields: paRes – The PAResPayload data that is generated by the card issuer’s Access Control Server. This value is returned to the returnUrl as configured on secureCodeLookup request secureCodeId – The secureCodeId value that was returned on the response on the secureCodeLookup request (Mandatory parameter if transaction is 3D-Secure and no xid and cavv information is sent)
amount	BigDecimal	The actual amount of the purchase
		(Mandatory parameter)
tipAmount	BigDecimal	The calculated tip amount if required for the value being used in the purchase if any tip value was requested (Required if a tip was requested for the value)
contact	String	The billing information is required if billingRequired was true on the value lookup. This must be sent in a JSON object with the following: country emailAddress firstName LastName
billing	String	The contact information is required if contactRequired was true on the value lookup. This must be sent in a JSON object with the following: city country line1 line2 line3 postalCode
shipping	String	The shipping information is required if shippingRequired was true on the value lookup. This must be sent in a JSON object with the following: city country line1 line2 line3 postalCode recipientName recipientPhoneNumber
extraReference	String	The text that was entered by the user when prompted for an extra reference (Max Length – 50ANS)
extraInput	String	The text that was entered by the used when prompted for an extra input (Length – 50ANS)
deviceData	String	A JSON object containing fields to send the device information of the consumer performing the transaction. The object allows the following optional parameters shown below in blue to be sent if available
os	String	The operating system of the app/wallet
osVersion	String	The operating system version of the app/wallet
appVersion	String	The app version of the app/wallet performing the lookup and transaction
device	String	This includes the device type and model
latitude	String	The latitude related to the GPS coordinates of the app/wallet (eg. -26.13382683823002)
longitude	String	The longitude related to the GPS coordinates of the app/wallet (eg. 28.06927071511155)

Returns - HTTP 200

Parameter	Type	Description
status	String	Status of the request. Can be PENDING or ERROR provided there was no HTTP error. Once this is done a transaction lookup must be done to verify the actual status of the transaction using the transaction id. A payment notification is sent to the integrated merchant or payment service provider who created the value.
transactionId	Long	A transaction id related to the purchase transaction
date	String	The date and time that the transaction was processed. In the format CCYY-MM-DD HH:mm:ss
originalQrDetail	String	A JSON object showing the breakdown of the Scan to Pay QR code if a supported Scan to Pay QR code was done on the lookup (tag length value) or if the code/value was a URL. Will only be displayed if this is one of the above and not if the code/value was a 10 digit Scan to Pay code.

Sample Requests

Full Securecode Purchase

{
    "value": "3785802643",
    "transactionId": "469623,
    "msisdn": "27832006283",
    "cardHolderName": "J Smith",
    "cardNumber": "5123451234567897",
    "dateOfBirth":"19800101",
    "expiryDate": "1119",
    "amount": 1.00,
    "secureCodeData": {
        "cavv": "jM0YaCE08yfhCREAABFNBAcAAAA=",
        "xid": "aTRFelljS0NjcjFwRHhvNEo0WjA=",
        "eciFlag": "02",
        "errorNo":"0",
        "paresStatus": "01",
        "signatureVerification": "Y"
    }
}

Full Securecode Purchase With Device Data:

{
    "value": "3785802643",
    "transactionId": "469623,
    "msisdn": "27832006283",
    "cardHolderName": "J Smith",
    "cardNumber": "5123451234567897",
    "dateOfBirth":"19800101",
    "expiryDate": "1119",
    "amount": 1.50,
    "secureCodeData": {
        "cavv": "jM0YaCE08yfhCREAABFNBAcAAAA=",
        "xid": "aTRFelljS0NjcjFwRHhvNEo0WjA=",
        "eciFlag": "02",
        "errorNo":"0",
        "paresStatus": "01",
        "signatureVerification": "Y"
    },
    "deviceData": {
        "os": "Android",
        "osVersion": "9.0",
        "appVersion": "1.5",
        "device": "Huawei Mate 20 Pro",
        "serial": "Serial12345",
        "latitude": "-26.13382683823002",
        "longitude": "28.06927071511155",
        "clientIP": "196.186.12.11"
    }
}

Basic AMT Purchase

{
    "value": "3785802643",
    "transactionId": "469623,
    "msisdn": "27832006283",
    "cardHolderName": "J Smith",
    "cardNumber": "5123451234567897",
    "dateOfBirth":"19800101",
    "expiryDate": "1119",
    "amount": 1.00,
    "pinData": {
	"encryptedData":"jtB7deO95L/v5sQDEJNEj4BPjqRE645Rb1YA0tUz3MoQX4N+DVTUSUqKrqLkm+5Elf
1ka2vNqEeCShiRh0m8VVp/6fCVOsxwLAtF4loNav0jrFBNrCpFdb6DcXNflou6U8R7ys8rnNBIEn7QDkU+
7x8hF3SitLTNCZ7jS52aBAKdJZkAwdUUSvbVhRaAOXWGirg4i/jQi5S7rtIcIo+v/Vkf08l1tx6G1P5iu+07ulJF
0yBrTpwGVr+v1Y6QovRG5G+/9q1RbhNBXwaClGAVFcAAny7gApAN4vrqeS8rHbvoWzQfq1bLJxFs1NUA
z8SDTya7OP9wNfORhIoCQBoNCc/jRXxmlCadgxMeG8tCJRIPkp/ZBwKIVweObY90PwizKth7qrPKokY/Oo
tDrIyRant5iXOGSPVw9rGjhNDf+xuFLFHi2T1gB7hbOYUKIJ4C8AJTHbVpf5uUalUwlD/GfajugVf//30Ykt3W
zqu+ljPig9E+pTiOATj9jxrflwP3FCQ1drsvAR6DF8Gvyci3TpzeNYXVHsz+prtwwgwYti7huQ53Jm0xu6tDlGI
C4B5yOS6anxHDrOhBGbFGUCRIJKIxFKsPPx/xip9r1f1ZT8yYmZDoWLM3CGK0r0lMpkA+fXRQXSIvrtR4rQ
B6hwaNzhHBiO/Nhrc5XHAdQC7e0Nc="}
}

Basic Securecode Purchase

📘
Note
Must be used in conjunction with secureCodeLookup

{
    "value": "3785802643",
    "transactionId": "469623,
    "msisdn": "27832006283",
    "cardHolderName": "J Smith",
    "cardNumber": "5123451234567897",
    "dateOfBirth":"19800101",
    "expiryDate": "1119",
    "amount": 1.00,
    "secureCodeBasic": {
    	"secureCodeId" :" 11248",
		"paRes": "eNrFWNmSo0iyfecrynoemW52hNqUaRasAgQSiP2NTYBYxSKQvv6SmbXk1"
    },
}

Sample Response

{
    "transactionId": 412345,
    "status": "PENDING",
    "date": "2018-02-11 15:02:427"
}
{
    "status": "PENDING",
    "transactionId": 461632,
    "date": "2019-03-25 08:02:22",
    "originalQrDetail": "https://payat.io/qr/11669"
}

Transaction State

This returns the status of a specific purchase using a transaction id

METHOD: POST
ENDPOINT: /transactionState/{transactionId} (eg. /transactionState/123456)

Parameter	Type	Description

status	String	Status of the request. See section 2.3 for list of statuses.
transactionId	BigDecimal	A transaction id related to the payment transaction
amount	BigDecimal	The amount related to the value that was sent to the acquirer
currencyCode	String	The currency value that was sent to the acquirer for the transaction. Eg. ZAR
code	String	The value/code that represents the details of the payment as used on the purchase request (Length 10N)
clientMsisdn	String	MSISDN of the consumer in international format (if available – Max Length 15N)
clientIdentifier	String	Client identifier if one is present in related to the clientMsisdn (if available – Max Length 50AN)
retrievalReferenceNumber	BigDecimal	The reference that is used between the MRA system and the acquirer for the transaction (Max Length 12N)
authCode	String	The authorization value that is sent by the acquirer to Scan to Pay when a successful payment is done. Can be null if the transaction was unsuccessful (Length 6AN)
bankResponse	String	The bank response value for the transaction
date	String	The date and time that the transaction was processed in the format CCYY-MM-dd HH:mm:ss: (this is in UTC+2)
		Eg. 2017-05-30 12:59:59
merchantName	String	The name of the merchant that the purchase was done for
		(Max Length – 50 ANS)
subMerchantName	String	This will be present if a sub merchant to the main merchant account was used (Max Length – 50ANS)
source	String	This is the acquirer of the merchant

Sample Request

{
     "status": "SUCCESS",
    "transactionId": 461632,
    "reference": "PAYAT0000039172",
    "amount": 150,
    "currencyCode": "ZAR",
    "code": "0014128292",
    "clientMsisdn": "27832006283",
    "retrievalReferenceNumber": 282352,
    "authCode": "DEBUG",
    "bankResponse": "00",
    "date": "2019-03-25 08:02:22",
    "merchantName": "BillerABC",
    "subMerchantName": "CentShop",
    "source": "DEBUG"
}

Transaction History

This returns the last 10 payments as a JSON array.

METHOD: POST
ENDPOINT: /transactionHistory

Parameter	Type	Description
msisdn	String	String
transactionId	BigDecimal	A transaction id related to the payment transaction
amount	BigDecimal	The amount related to the value that was sent to the acquirer
currencyValue	String	The currency value that was sent to the acquirer for the transaction
value	String	The value that represents the details of the payment echoed back
clientMsisdn	String	MSISDN of the consumer in international format (if available)
clientIdentifier	String	Client identifier (if available)
retrievalReferenceNumber	BigDecimal	The reference that is used between the MRA system and the acquirer for the transaction
authCode	String	The authorization value that is sent by the acquirer to Scan to Pay when a successful payment is done
bankResponse	String	The bank response value for the transaction
date	String	The date and time that the transaction was processed in the format yyyy-MM-dd HH:mm:ss: (this is in UTC) Eg. 2017-05-30 10:59:59
dateUTC2	String	The date and time that the transaction was processed in the format yyyy-MM-dd HH:mm:ss: (this is in UTC+2) Eg. 2017-05-30 12:59:59
merchantName	String	The name of the merchant that the purchase was done for (Max Length – 50 ANS)

Sample Request

{
"msisdn": "27832006283"
}

Sample Response

{
    "status": "SUCCESS",
    "transactions": [
        {
            "status": "SUCCESS",
            "transactionId": 461632,
            "reference": "PAYAT0000039172",
            "amount": 150,
            "currencyCode": "ZAR",
            "code": "0014128292",
            "clientMsisdn": "27832006283",
            "clientIdentifier": "213213313213",
            "retrievalReferenceNumber": 282352,
            "authCode": " DEBUG",
            "bankResponse": "00",
            "date": "2019-03-25 06:02:22",
            "dateUTC2": "2019-03-25 08:02:22",
            "merchantName": "BillerABC",
            "subMerchantName": "CentShop",
            "source": "DEBUG"
        },
        {
            "status": "SUCCESS",
            "transactionId": 461524,
            "reference": "MTN000000039164",
            "amount": 10,
            "currencyCode": "ZAR",
            "code": "8802326844",
            "clientMsisdn": "27832006283",
            "clientIdentifier": "213213313213",
            "retrievalReferenceNumber": 282252,
            "authCode": " DEBUG",
            "bankResponse": "00",
            "date": "2019-03-20 12:25:24",
            "dateUTC2": "2019-03-20 14:25:24",
            "merchantName": "MTN MP",
            "subMerchantName": "R10 Airtime",
            "originalQrDetail": "https://ragstest.oltio.co.za/vas/prepaid?id=20&product=Airtime",
            "source": "DEBUG"
        }
    ]
}

Secure Code Lookup

The request verifies that the transaction is eligible for 3D-Secure authentication. The response will return HTML information that the integrator must then display in a web view in order to facilitate the consumer authentication process that the card issuer prescribed.

METHOD: POST
ENDPOINT: /secureCodeLookup

Parameter	Type	Type
cardNumber	String	The card number that will be used for the purchase. A luhn-10 check will be performed on the number (Mandatory parameter – Max length 19N)
expiryDate	String	Expiry date of the card number if required in the format MMYY (Mandatory parameter)
amount	BigDecimal	The full amount of the intended purchase (Mandatory parameter)
returnUrl	String	A URL that the secure code website will return to with the PAResPayload (Mandatory parameter)
transactionId	Long	The transaction id that was returned on the generateTransactionId request (Mandatory parameter)
webViewData	String	The HTML form information that the integrator must send as a HTTP Form POST in order to receive the PAResPayload from the card issuer Access Control Server
transactionId	Long	A transaction id related to the purchase transaction echoed back

Sample Request

{
"cardNumber": "5123451234567897", 
"transactionId": 380344,
"expiryDate": "1018",
"returnUrl": "https://ragstest.oltio.co.za/nix/tempUrl.jsp",
"amount": 7.50
}

Sample Response

{
    "webViewData": "<HTML><head><meta name='viewport' content='width=device-width, initial-scale=1.0'></head><BODY onload='document.frmLaunch.submit();'> Redirecting... <FORM name='frmLaunch' method='POST' action='https://acstest.bankserv.co.za/V3DSStart?osb=mast-3&VAA=B'><input type=hidden name='PaReq' value='eJxVUdluwjAQ/BXEB2RjE0hAiyWOVs0DCAot4jFyVpC2OXAcrq+vDUmhbzPrHc/uLK73imi6IlkpEjijsox21EriYZu7QcC7RVvgYvROB4FHUmWSZ4I5rsMRGmpESu6jTAuM5GEczgVjDKHGmJIKp4LxDsIdYhalJNZU6lajRLjVUOZVptVF+MxFaAhW6kfstS4GAKfTydFGmdZCR+bONUKwLQiPQRaVRaX58pzEYrbbLSf97fWw2V6+5q9V5RfjZb4NvZdyiGA7MI40Ce6ywO1x1mJswHsDt4dwq2OU2lkE93yz1x1jYS1GTw/PBTRxKspks0rDkM5FnpGVIPxhjKmUJjXuBcbRYoTHBpM3G6zUJrq4S5+zD3+1yvPldz/xFpPuUV3HnU1o8761WIfEpMYCa1wTBPsJ1HeE+soG/bv+LzLmr6Y='><input type=hidden name='TermUrl' value='https://ragstest.oltio.co.za/nix/temp.jsp'><input type=hidden name='MD' value=''></FORM></BODY></HTML>",
    "secureCodeId": 11248,
    "transactionId": 380344
}

BIN Lookup

This returns the card related info based on the card BIN

METHOD: POST
ENDPOINT: /binLookup

Parameter	Type	Description

bin	String	The Bank Identification Number (BIN) which is usually the first 6 to 8 digits of the card number
authMethod	String	The recommended authentication method of the BIN. This can be either AMT or SECURE_CODE. For AMT, the PIN data must be sent on the purchase request along with the other related card information. For SECURE_CODE, the 3DS related information must be sent on the purchase request along with the requested card information.
cvvNeeded	Boolean	Indicates whether CVV2/CVC2 is required on the purchase request
expiryNeeded	Boolean	Indicates whether the card requires an expiry date to be provided on the purchase request
accNeeded	Boolean	Indicates whether an account type is to be sent on the purchase request
dobNeeded	Boolean	Indicates whether the date of birth is required on the purchase request
cardHolderNameNeeded	Boolean	Indicates whether the cardholder name is required on the purchase request

Sample Request

{
"bin": "123456"
}

Sample Response

{
    "authMethod": "AMT",
    "cvvNeeded": true,
    "expiryNeeded": true,
    "accNeeded": false,
    "dobNeeded": false,
    "cardHolderNameNeeded": true,
    "displayName": "Bank ABC Debit Card"
}

Get VAS Menu

This returns the VAS menu as a JSON array. The information returned will need to be interpreted and displayed in a logical menu on the 3rd party’s app/wallet so the consumer can choose what to buy/pay. Once the menu item is selected, the app/wallet’s back end will need to prompt the consumer for the necessary information, should this be required.

METHOD: GET
ENDPOINT: /menu

Parameter	Type	Description
status	String	The status of the request. Will always be sent.
prepaidMenu	String	The prepaid menu that is configured for the app/wallet. This will only display if configured for the app/wallet id on the Scan to Pay platform
accountsMenu	String	The accounts/bill payments menu that is configured for the app/wallet. This will only display if configured for the app/wallet id on the Scan to Pay platform
donationsMenu	String	The donations menu that is configured for the app/wallet. This will only display if configured for the app/wallet id on the Scan to Pay platform
id	Long	The menu id that represents the prepaidMenu, accountsMenu or donationsMenu
name	String	The name of the menu related to the main menu id
action	String	The action type that will need to be used on the lookup as a combination with the menus id value mentioned below
menuDefinition	String	Consists of a JSON object including a URL for an image that can be displayed in the app/wallet representing the menu item on the VAS menu
menus	String	A JSON object containing the info of the sub-menu in relation to the main menu. This consists of id, name, action, and it’s own menuDefinition. The object will consist of the input information stated below in purple. It is to be noted that the VAS menus id and prepaidMenu action can used on a lookup request to determine the inputs required for the applicable menu item.
ref	String	A reference value that is used to identify the input that is required from the consumer.
title	String	This is the title to be displayed to the consumer in the app/wallet to prompt for the input.
type	String	This represents the type of input required from the consumer. It can be one of the following: TEXT, NUMBER, EMAIL, DROPDOWN.
regex	String	Short for regular expression. A sequence of characters that allows the app/wallet to help validate the text/input required as per the type mentioned above.
regexErrorMessage	String	An error message related to the regex value. This can be displayed in the app/wallet should the regex validation fail.

Sample Response

{
    "status": "SUCCESS",
    "prepaidMenu": [
        {
            "id": 10000219,
            "name": "MTN",
            "action": "MENU",
            "menuDefinition": {
                "image": "https://rags.oltio.co.za/m/prepaid/mtn.png"
            },
            "menus": [
                {
                    "id": 10000223,
                    "name": "Airtime",
                    "action": "LOOKUP",
                    "menuDefinition": {
                        "image": "https://rags.oltio.co.za/m/prepaid/mtn.png",
                        "inputs": [
                            {
                                "ref": "amount",
                                "title": "Enter Amount",
                                "type": "NUMBER",
                                "regex": "\\d",
                                "regexErrorMessage": "Numeric characters only"
                            },
                            {
                                "ref": "msisdn",
                                "title": "Enter Destination",
                                "type": "NUMBER",
                                "regex": "\\d",
                                "regexErrorMessage": "Numeric characters only"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "id": 10000227,
            "name": "Vodacom",
            "action": "MENU",
            "menuDefinition": {
                "image": "https://rags.oltio.co.za/m/prepaid/voda.png"
            },
            "menus": [
                {
                    "id": 10000231,
                    "name": "Data Bundles",
                    "action": "MENU",
                    "menuDefinition": {
                        "image": "https://rags.oltio.co.za/m/prepaid/voda.png"
                    },
                    "menus": [
                        {
                            "id": 10000235,
                            "name": "100MB Data (R15)",
                            "action": "LOOKUP",
                            "menuDefinition": {
                                "image": "https://rags.oltio.co.za/m/prepaid/voda.png",
                                "inputs": [
                                    {
                                        "ref": "msisdn",
                                        "title": "Enter Destination",
                                        "type": "NUMBER",
                                        "regex": "\\d",
                                        "regexErrorMessage": "Numeric characters only"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "accountsMenu": [
        {
            "id": 10000215,
            "name": "Pay DStv",
            "action": "LOOKUP",
            "menuDefinition": {
                "image": "https://rags.oltio.co.za/m/pay@/dstv.png"
            }
        }
    ],
    "donationsMenu": [
        {
            "id": 10000239,
            "name": "Charity Donation",
            "action": "LOOKUP",
            "menuDefinition": {
                "image": "https://rags.oltio.co.za/m/pay/charity.png"
            }
        }
    ]
}

REST API Requests

Generate Transaction Id

Returns - HTTP 200

📘
Note

Sample Request

Sample Response

Purchase Transaction Id

Returns - HTTP 200

Sample Requests

📘
Note

Sample Response

Transaction State

Sample Request

Transaction History

Sample Request

Sample Response

Secure Code Lookup

Sample Request

Sample Response

BIN Lookup

Sample Request

Sample Response

Get VAS Menu

Sample Response

Generate Transaction Id

Returns - HTTP 200

📘Note

Sample Request

Sample Response

Purchase Transaction Id

Returns - HTTP 200

Sample Requests

📘Note

Sample Response

Transaction State

Sample Request

Transaction History

Sample Request

Sample Response

Secure Code Lookup

Sample Request

Sample Response

BIN Lookup

Sample Request

Sample Response

Get VAS Menu

Sample Response

📘
Note

📘
Note