Endpoints in Detail
/api/merchant/authenticate
Returns the current server time, in UTC, formatted as yyyyMMddHHmmssfff. This time can be used to check the client time against that of the server. A deviation of five minutes or less is allowed between the client and server time.
yyyy – four-digit year
MM – two-digit month
dd – two-digit day
HH – Hour formatted as 24-Hour time
mm – two-digit minutes
ss – two-digit seconds
fff – current millisecond
Example
Monday, 7th October 2013, 17:02:45 PM would be formatted as 20131007150245442.
JSON Response:
20131007150245442
/api/merchant/configuration
Returns the user parameters as configured in the BackOffice website.
The user parameters consist of list of applications selected for the user
list of currencies selected for the user list of permissions selected for the user
JSON Response:
{
"Applications": [{
"Description": "mPress test application",
"ApplicationID": "1d76a36f-f10e-4388-87f4-4675c78a5511",
"CertificateID": "4c96973f-71dd-4044-802d-6e234effe8f2",
"Mode": "Live"
},
{
"Description": "mPress test application",
"ApplicationID": "1d76a36f-f10e-4388-87f4-4675c78a5511",
"CertificateID": "7dcb6189-bfad-414b-b4ed-ea9d5875ea12",
"Mode": "Live"
}],
"Currencies": [{
"Format": "SCA,.R ",
"DecimalPlaces": 2,
"Code": "ZAR"
}],
"Permissions": [{
"Name": "AUTHORISATION",
"Allowed": "true"
},
{
"Name": "REFUND",
"Allowed": "true"
},
{
"Name": "SALE",
"Allowed": "true"
}]
}
NB. If no applications are returned in the response configuration, you will need to contact the administrator of the usergroup and request the necessary configuration changes to be made to the respective user.
Application list
You will need to select only one of the applications returned.
The application id, certificate id and mode will be used when performing a transaction to the gateway. The description is returned for display use only and not when performing the transaction
NB: You cannot simply switch to mode test using an application id received for mode live. You will need to download the configuration each time you change between test and live.
Permissions list
The permissions returned in the list relate to the transaction types that the user can perform using the REST API. If the “Allowed” value for any of the transaction types is set to “false”, that transaction option should not be presented to the user.
In all cases irrespective of the allowed transaction types, the void transaction type is allowed.
/api/transactions
Submit a transaction to the gateway.
JSON Request:
Sample request for an mPress SDK (Card Present) implementation
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"ProductType": "Enterprise",
"ProductVersion": "mPress",
"Direction": "Request",
"Transaction": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"Mode": "Live",
"MerchantReference": "{11f1167c-9112-46ca-a69d-b0e856271f4b}",
"MerchantTrace": "{76c8813c-09ad-4b48-bbf5-4a4b320d6659}",
"DeviceMake": "Miura",
"DeviceSerialNumber": "02000567",
"EMV_ApplicationIdentifier": null,
"EMV_ApplicationInterchangeProfile": null,
"EMV_ApplicationTransactionCounter": null,
"EMV_ApplicationVersion": null,
"EMV_AuthorisationRequestCryptogram": null,
"EMV_CardHolderVerificationMethodResult": null,
"EMV_CardSequenceNumber": null,
"EMV_CryptogramInformationData": null,
"EMV_IssuerApplicationData": null,
"EMV_TerminalCapabilities": null,
"EMV_TerminalType": null,
"EMV_TerminalVerificationResult": null,
"EMV_UnpredictableNumber": null,
"EMV_TransactionStatusInformation": null,
"Currency": "ZAR",
"KeySerialNumber": "FF … 14",
"Track2KeySerialNumber": "FF … 44",
"Track2": "37E ... C155",
"PINBlock": "1F … 6F",
"Amount": "2500",
"ExpiryDate": "816",
"CardSecurityCode": null
}
}
/api/merchant/bins
Returns the current bin list used by the gateway in determining whether to prompt for PIN entry while using a POS device when the card service code incorrectly identifies this requirement.
JSON Response:
[{
"BIN": "201010",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},
{
"BIN": "225050",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},
{
"BIN": "3045",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},]
The section “16.6.4 Determining if a card is PIN based” of the iVeri Client Developers Guide, describes how the bin list together with the card's service code is used in determining whether to prompt for PIN.
JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "5049........0023"
}
}
JSON Request:
Sample request for an eCommerce/CNP transaction
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"ProductType": "Enterprise",
"ProductVersion": "mPress",
"Direction": "Request",
"Transaction": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"Mode": "Live",
"MerchantReference": "{11f1167c-9112-46ca-a69d-b0e856271f4b}",
"MerchantTrace": "{76c8813c-09ad-4b48-bbf5-4a4b320d6659}",
"Currency": "ZAR",
"Amount": "2500",
"ExpiryDate": "816",
"CardSecurityCode": null,
“PAN”: ”4242424242424242”
}
}
JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "4242........4242"
}
}
/api/transactions?applicationid={applicationid}
Returns the application transaction history for the last 7 days.
The JSON Response is a list of transaction responses.
/api/transactions/{requestid}
Returns transaction details for a particular transaction identified by the requestid.
JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "5049........0023"
}
}
api/transactions/{requestid}/receipt
Upload a Cardholder signature to be added to a MerchantReceipt linked to a transaction identified by the requestid.
JSON Request:
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"Direction": "Request",
"Enquiry": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"CardholderName", "Russel King",
"SignatureImageFormat", "jpeg",
"SignatureImage", "hexified image data"
}
}