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

ParameterTypeDescription
valueStringThe 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)
msisdnStringMSISDN (mobile number) of the consumer in international format
(Mandatory parameter โ€“ Max Length 15N)

Returns - HTTP 200

ParameterTypeDescription
statusStringThe status of the request. Will always be sent.
valueStringThe 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)
merchantNameStringThe name of the merchant including the sub merchant name if present (Max Length โ€“ 100ANS)
dataStringA JSON object representing the below parameters in blue
amountBigDecimalThe 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
currencyStringThe currency related to the payment (e.g. R for Rands) (Length โ€“ 1ANS)
shortDescriptionStringA description of the payment being completed. This should be displayed to the consumer at the time of payment (Max Length โ€“ 50ANS)
partialPaymentBooleanWill be true if the value allows a partial payment and amount must be sent on the purchase request
tipRequiredBooleanWill 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
tipFixedBigDecimalWill be returned if a tip with a fixed amount is required
tipPercentageDoubleWill be returned if a tip with a percentage is required
contactRequiredBooleanWill be true if the purchase request requires contact information
shippingRequiredBooleanWill be true if the purchase request requires shipping information
billingRequiredBooleanWill be true if the purchase request requires billing information
extraInputRequiredBooleanWill 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
secureCodeMerchantIdStringThe merchant id to be used on the ACS call for 3D-Secure (Max Length 50AN)
secureCodeUrlStringThe 3D-Secure URL that will be used to initiate the 3DS process on the MPI Lookup request along with the 3dsMerchantId, 3dsProcessorId and 3dsPassword
secureCodeProcessorIdStringThe processor id to be used on the MPI Lookup request
(Max Length 20AN)
secureCodePasswordStringThe password that is to be used with the 3dsMerchantId, 3dsProcessorId and 3dsUrl on the MPI Lookup request (Max Length 50AN)
acceptedCardsStringReturns 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
acceptedPaymentMethodsStringReturns a comma-separated string vale describing the payment methods supported for this transactions; can be a combination of the following:
poiStringRelates 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.
transactionIdLongA transaction id related to the purchase transaction, if already generated
originalQrDetailStringA 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)
webhookStringA URL that transaction information be sent to regarding the outcome of a transaction

(Optional parameter โ€“ Max Length 100AN)
inputsRequiredStringA 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
refStringA reference value that is used to identify the input that is required from the consumer.
titleStringThis is the title to be displayed to the consumer in the app/wallet to prompt for the input. @NotNull, @Size(max = 20)
typeStringThis represents the type of input required from the consumer. It can be one of the following: TEXT, NUMBER, EMAIL, DROPDOWN. @NotNull
defaultValueA default value related to the ref input required. @Size(max = 45)
regexStringShort 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)
regexErrorMessageStringAn 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

ParameterTypeDescription
msisdnStringMSISDN (mobile number) of the consumer in international format (Mandatory parameter โ€“ Max Length 15N)
valueStringThe Scan to Pay value that represents the details required to complete the payment as per the value lookup request (Mandatory parameter โ€“ Length 10N)
transactionIdLongA transaction id related to the purchase transaction, if already generated
cardNumberStringThe card number that will be used for the purchase. A luhn-10 check will be performed on the number (Mandatory parameter โ€“ Max length 19N)
accountStringThis 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)
expiryDateStringExpiry date of the card number if required in the format MMYY

(Mandatory parameter)
cardholderNameStringName of the cardholder
date of BirthBigDecimalDate of birth related to the cardholder in the format CCYYMMDD

(Required if the issuer requests this for their BINs)
cvv2StringThe card validation value (CVC2), card verification value (CVV2) or card identification value (CID)
secureCodeDataStringA 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
cavvStringThe Cardholder Authentication Verification Value that will be sent to the issuing bank for authentication. Visa refers to this value as a AAV (Authentication Verification Value) and UKheshe uses UCAF (Universal Cardholder Authentication Field)

(Mandatory parameter โ€“ Max Length 48AN)
xidStringThe transaction identifier used for 3D-Secure authentication

(Mandatory parameter โ€“ Max Length 40AN)
eciFlagStringThe 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)
errorNoStringAn application error number returned on the ACS interface for the 3D-Secure call

(Mandatory parameter โ€“ Length 1N)
paResStatusStringThe transaction status result identifier as returned on the ACS interface for the 3D-Secure call

(Mandatory parameter โ€“ Can be Y, N, U, A)
signatureVerificationStringThe transaction signature status identifier as returned on the ACS interface for the 3D-Secure call

(Mandatory parameter โ€“ Can be Y or N)
pinDataStringSubfield: encryptedData - A string value of the encrypted payload that is sent on the response from the PinSecLib library

(Mandatory parameter if transaction is AMT)
secureCodeBasicStringA 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)
amountBigDecimalThe actual amount of the purchase
(Mandatory parameter)
tipAmountBigDecimalThe 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)
contactStringThe 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
billingStringThe 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
shippingStringThe 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
extraReferenceStringThe text that was entered by the user when prompted for an extra reference (Max Length โ€“ 50ANS)
extraInputStringThe text that was entered by the used when prompted for an extra input (Length โ€“ 50ANS)
deviceDataStringA 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
osStringThe operating system of the app/wallet
osVersionStringThe operating system version of the app/wallet
appVersionStringThe app version of the app/wallet performing the lookup and transaction
deviceStringThis includes the device type and model
latitudeStringThe latitude related to the GPS coordinates of the app/wallet (eg. -26.13382683823002)
longitudeStringThe longitude related to the GPS coordinates of the app/wallet (eg. 28.06927071511155)

Returns - HTTP 200

ParameterTypeDescription
statusStringStatus 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.
transactionIdLongA transaction id related to the purchase transaction
dateStringThe date and time that the transaction was processed. In the format CCYY-MM-DD HH:mm:ss
originalQrDetailStringA 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)

ParameterTypeDescription
statusStringStatus of the request. See section 2.3 for list of statuses.
transactionIdBigDecimalA transaction id related to the payment transaction
amountBigDecimalThe amount related to the value that was sent to the acquirer
currencyCodeStringThe currency value that was sent to the acquirer for the transaction. Eg. ZAR
codeStringThe value/code that represents the details of the payment as used on the purchase request (Length 10N)
clientMsisdnStringMSISDN of the consumer in international format (if available โ€“ Max Length 15N)
clientIdentifierStringClient identifier if one is present in related to the clientMsisdn (if available โ€“ Max Length 50AN)
retrievalReferenceNumberBigDecimalThe reference that is used between the MRA system and the acquirer for the transaction (Max Length 12N)
authCodeStringThe 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)
bankResponseStringThe bank response value for the transaction
dateStringThe 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
merchantNameStringThe name of the merchant that the purchase was done for
(Max Length โ€“ 50 ANS)
subMerchantNameStringThis will be present if a sub merchant to the main merchant account was used (Max Length โ€“ 50ANS)
sourceStringThis 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

ParameterTypeDescription
msisdnStringString
transactionIdBigDecimalA transaction id related to the payment transaction
amountBigDecimalThe amount related to the value that was sent to the acquirer
currencyValueStringThe currency value that was sent to the acquirer for the transaction
valueStringThe value that represents the details of the payment echoed back
clientMsisdnStringMSISDN of the consumer in international format (if available)
clientIdentifierStringClient identifier (if available)
retrievalReferenceNumberBigDecimalThe reference that is used between the MRA system and the acquirer for the transaction
authCodeStringThe authorization value that is sent by the acquirer to Scan to Pay when a successful payment is done
bankResponseStringThe bank response value for the transaction
dateStringThe 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
dateUTC2StringThe 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
merchantNameStringThe 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

ParameterTypeType
cardNumberStringThe card number that will be used for the purchase. A luhn-10 check will be performed on the number (Mandatory parameter โ€“ Max length 19N)
expiryDateStringExpiry date of the card number if required in the format MMYY (Mandatory parameter)
amountBigDecimalThe full amount of the intended purchase (Mandatory parameter)
returnUrlStringA URL that the secure code website will return to with the PAResPayload (Mandatory parameter)
transactionIdLongThe transaction id that was returned on the generateTransactionId request (Mandatory parameter)
webViewDataStringThe 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
transactionIdLongA 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

ParameterTypeDescription
binStringThe Bank Identification Number (BIN) which is usually the first 6 to 8 digits of the card number
authMethodStringThe 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.
cvvNeededBooleanIndicates whether CVV2/CVC2 is required on the purchase request
expiryNeededBooleanIndicates whether the card requires an expiry date to be provided on the purchase request
accNeededBooleanIndicates whether an account type is to be sent on the purchase request
dobNeededBooleanIndicates whether the date of birth is required on the purchase request
cardHolderNameNeededBooleanIndicates 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

ParameterTypeDescription
statusStringThe status of the request. Will always be sent.
prepaidMenuStringThe 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
accountsMenuStringThe 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
donationsMenuStringThe 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
idLongThe menu id that represents the prepaidMenu, accountsMenu or donationsMenu
nameStringThe name of the menu related to the main menu id
actionStringThe action type that will need to be used on the lookup as a combination with the menus id value mentioned below
menuDefinitionStringConsists 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
menusStringA 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.
refStringA reference value that is used to identify the input that is required from the consumer.
titleStringThis is the title to be displayed to the consumer in the app/wallet to prompt for the input.
typeStringThis represents the type of input required from the consumer. It can be one of the following: TEXT, NUMBER, EMAIL, DROPDOWN.
regexStringShort 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.
regexErrorMessageStringAn 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"
            }
        }
    ]
}