JavaScript Library
What is an API function?
An API functions with the goal of allowing different systems, applications and devices to share information with each other. APIs work by translating a user's input into data, which helps a system send back the right response
You may refer to the below list of the API functions and their descriptions that is found inside the POS Buddy JavaScript library.
API functions
setMerchantId(merchantId)
Set the Merchant ID. Needed for transacting.setUsername(username)
Set the Username. Needed for transacting.setApplicationKey(applicationKey)
Set the Application Key. Needed for transacting when doing Retail Auth.
Note: This function will be deprecated in favour of POS authentication.
setAuthenticationKey(authenticationKey)
Set the Authentication Key. Needed for transacting.setPosId(id)
Set the POS id. Needed for POS auth and transacting with POS auth token.setBarcodeCallback(callbackFunction)
Set the callback function when a barcode is scanned from the Payment Device
// Example Barcode Scanner callback
function pb_barcodeCallback(barcode) {
console.log("Received barcode: " + barcode);
}
pingDevice(callback)
Pings terminal and return result to callback function:
function pingCallback(obj) { ... }
// Example returned object
{
"result": "SUCCESS"
}
clearItems()
Clear the items on the line display of the terminal and show the logo screen.displayItems(totalCost, items)
Display items on the terminal. items is an object that must contain description, price and count of each item.
Note: totalCost and price is amount in cents
// Example items object
[
{
"description": "Pizza",
"price": 11000,
"count": 1
},
{
"description": "Pancakes",
"price": 6500,
"count": 1
},
{
"description": "Cappuccino",
"price": 2960,
"count": 2
}
]
doAuth(callback)
Do an auth on the terminal. The terminal will prompt for the user password before it goes online. The result will be returned as an object to the callback function:
function authCallback(obj) { ... }
Note: The software needs to send the returned authentication key to the device using setAuthenticationKey() before a transaction can be initiated
doRetailAuth(secretKey, accessKey, callback)
Do a retail auth. The terminal will not prompt for the user password.
The result will be returned as an object to the callback function:
function authCallback(obj) { ... }
Note: The software needs to send the returned authentication key to the device using setAuthenticationKey() before a transaction can be initiated
// Example of returned object in auth and retailAuth callback
{
"authenticationKey": "11111111-2222-3333-4444-555555555555",
"resultDescription": "COMPLETED",
"fwUpdateDate": "null",
"buildInfo": "THUMBZUP_TEST",
"terminalId": "91000000",
"applicationKey": "12345678-9aabc-defg-h012-34567890abcde",
"fwUpdateVersion": "null",
"pebbleFirmwareVersion": "null",
"resultCode": "00",
"fwUpdateAvailable": "false",
"overrideMerchantNumber": "null",
"merchantID": "123450000000000",
"merchantUsername": "demo",
"pebbleSerialNumber": "504E3030303030303030303030",
"thirdPartyUsername": "null",
"keepAliveMinutes": "0",
"launchType": "AUTH",
"keepAliveAfterExit": "false",
"merchantName": "Demo Merchant",
"deviceIMEI": "null",
"appVersion": "1.1.191"
}
doPosAuth(secretKey, accessKey, callback)
Do a POS auth. The terminal will not prompt for the user password.
The result will be returned as an object to the callback function: function authCallback(obj) { ... }
Notes:
- The software needs to send the returned authentication key to the device using setAuthenticationKey() before a transaction can be initiated.
- Before calling PosAuth, the POS id needs to be set using the setPosId function.
// Example of returned object in POS Auth callback
{
"resultDescription": "SUCCESS",
"authenticationKey": "4a2db56e-4db9-43e0-86ff-9bd20b292cb0",
"sessionTimeout": "86400000"
}
- Initiate a sale transaction. Extra parameters can be set in extraParameters, see Extra Parameters for details.
The result is returned as an object to the callback function:
function saleCallback(obj) { ... }
Example of returned object in doSale callback
{
"thirdPartyMerchantNumber": "null",
"authenticationKey": "11111111-2222-3333-4444-555555555555",
"resultDescription": "APPROVED",
"merchantRegionCode": "null",
"isReceiptRequired": "false",
"latitude": "0.0",
"fwUpdateDate": "null",
"buildInfo": "THUMBZUP_TEST",
"externalSTAN": "0",
"terminalId": "91000000",
"applicationKey": "11111111-2222-3333-4444-555555555555",
"externalInvoiceGUID": "null",
"fwUpdateVersion": "null",
"externalRRN": "null",
"isReceiptDataAvailable": "true",
"pebbleFirmwareVersion": "2.1.18",
"resultCode": "01",
"transactionDescription": "null",
"fwUpdateAvailable": "false",
"receiptBundle": {
"MERCHANT_REGION_CODE": "GP",
"RC_ALT": "00",
"SEQ_NO": "000",
"STATUS": "APPROVED",
"BUDGET_PERIOD": "",
"CARD_TYPE": "",
"PAN_WITH_BIN": "445143** **** 2309",
"MERCHANT_ID": "123456789000000",
"TIMESTAMP": "1683714592279",
"EXTERNAL_TRANSACTION_DATETIME": "",
"PROCESSING_CODE": "",
"RC_DESCRIPTION": "Approved",
"EXTERNAL_INVOICE_GUID": "",
"REPLACEMENT_MERCHANT_ID": "",
"BATCH_NO": "000",
"TXN_CNTR": "0218",
"AUTH_PROFILE": "",
"INTERCHANGE": "null",
"ESC_BY_AUTH_CODE": "226 00 IH 802294",
"TX_TYPE": "DEBIT",
"ACC_TYPE_DESC": "Default",
"TIP_AMOUNT": "",
"CURRENCY_CODE": "ZAR",
"AUTH_CODE": "802294",
"RC": "00",
"AID": "A0000000031010",
"CRY": "C10C84D7F1345F8E",
"CVM": "none",
"IAD": "06010A03A00000",
"PAN": "**** **** **** 2309 ",
"RRN": "313029480001",
"TSI": "",
"TVR": "0000000000",
"APSN": "00",
"DATE": "2023-05-10T10:29:52.279+0000",
"STAN": "",
"NAME_ON_CARD": "UnknownCardholderName",
"AMOUNT_CENTS": "6500",
"ABS_AMOUNT": "65.00",
"RECEIPT_NUMBER": "",
"TERMINAL_ID": "90000000",
"TX_TYPE_DESCRIPTION": "SALE",
"EXTERNAL_TERMINAL_ID": "",
"FORMATTED_OTHER_AMOUNT": "R 0.00",
"FORMATTED_AMOUNT": "R 65.00",
"DESCRIPTION": "",
"BATCH_NUMBER": "0",
"SETTLEMENT_DATE": "2023-05-10T10:29:50.000+0000",
"SURCHARGE_AMOUNT": "0.00",
"EXTERNAL_TRANSACTION_GUID": "",
"CARD_BIN": "445143",
"TRANSACTION_INFO": "22600IH802294",
"REPLACEMENT_TERMINAL_ID": "",
"POS_ENTRY": "701",
"RC_ISO_DESCRIPTION": "Approved",
"APPLICATION_LABEL": "VISA SAVINGS",
"MERCHANT_CITY": "Centurion",
"MERCHANT_NAME": "Demo Merchant",
"CUSTOMER_NAME": "",
"OTHER_AMOUNT": "0.00",
"APP_VERSION": "1.1.191",
"CARD_SEQ_NO": "",
"APP_LABEL": "VISA SAVINGS",
"INVOICE_NUM": "",
"MESSAGE_1": "",
"MESSAGE_2": "",
"CARD_TRANSACTION_TYPE": "CONTACTLESS",
"RESULT_CODE": "00",
"MERCHANT_COUNTRY_CODE": "ZA",
"REPRINT": "",
"PAN_HASH": "34560123196233B9E2B28AE64A7B7F8CD039D7B6A1BD587A9F184B1468B05BC2",
"AMOUNT": "65.00",
"TIP_LABEL": "",
"DIGITS": "2309",
"CVM_ABSA": ""
},
"overrideMerchantNumber": "null",
"emailAddressToSendReceipt": "",
"merchantID": "123456789000000",
"merchantUsername": "demo",
"externalTerminalId": "null",
"pebbleSerialNumber": "504E3430303030303030303030",
"longitude": "0.0",
"thirdPartyUsername": "null",
"invoiceNumber": "null",
"isApproved": "true",
"keepAliveMinutes": "0",
"launchType": "SALE",
"keepAliveAfterExit": "false",
"merchantCity": "null",
"merchantName": "Demo Merchant",
"deviceIMEI": "null",
"cellNumberToSMSReceipt": "",
"customerName": "null",
"alwaysShowTransactionStatusScreen": "false",
"externalTransactionGUID": "null",
"transactionReferenceNo": "null",
"transactionUuid": "06b0c947-a659-45f0-a3e0-d030cc77d786",
"appVersion": "1.1.191",
"merchantCountryCode": "null",
"merchantCategoryCode": "null",
"externalTransactionDateTime": "null",
"transactionAmount": "6500"
}
doRefund(uuid, amount, extraParameters, callback)
Initiate a refund transaction. For a matched refund, include the uuid of the original transaction. Leave uuid empty for unmatched refunds.
Note: Extra parameters can be set in extraParameters, see Extra Parameters for details.
The result is returned as an object to the callback function: function refundCallback(obj) { ... }
// Example of returned object in doRefund callback
{
"commandId": "PAY_APP_RESPONSE",
"commandPayload": {
"thirdPartyMerchantNumber": "null",
"authenticationKey": "11111111-2222-3333-4444-555555555555",
"resultDescription": "APPROVED",
"merchantRegionCode": "null",
"isReceiptRequired": "false",
"latitude": "0.0",
"fwUpdateDate": "null",
"buildInfo": "THUMBZUP_TEST",
"externalSTAN": "0",
"terminalId": "88000000",
"applicationKey": "11111111-2222-3333-4444-555555555555",
"externalInvoiceGUID": "null",
"fwUpdateVersion": "null",
"externalRRN": "null",
"isReceiptDataAvailable": "true",
"pebbleFirmwareVersion": "1.7.17",
"matchedRefund": "false",
"resultCode": "01",
"transactionDescription": "null",
"fwUpdateAvailable": "false",
"receiptBundle": {
"MERCHANT_REGION_CODE": "03",
"RC_ALT": "00",
"SEQ_NO": "000",
"STATUS": "APPROVED",
"BUDGET_PERIOD": "",
"CARD_TYPE": "",
"PAN_WITH_BIN": "445143** **** 2309",
"MERCHANT_ID": "880000000000000",
"TIMESTAMP": "1684222538759",
"EXTERNAL_TRANSACTION_DATETIME": "",
"PROCESSING_CODE": "",
"RC_DESCRIPTION": "Approved",
"EXTERNAL_INVOICE_GUID": "",
"REPLACEMENT_MERCHANT_ID": "",
"BATCH_NO": "000",
"TXN_CNTR": "0224",
"_PDF_AMOUNT_PREFIX": "-",
"AUTH_PROFILE": "",
"INTERCHANGE": "null",
"ESC_BY_AUTH_CODE": "226 20 IH* 324315",
"TX_TYPE": "REFUND",
"ACC_TYPE_DESC": "Default",
"TIP_AMOUNT": "",
"CURRENCY_CODE": "ZAR",
"AUTH_CODE": "324315",
"RC": "00",
"AID": "A0000000031010",
"CRY": "0F9CCBD24D7DFDC6",
"CVM": "none",
"IAD": "06010A03800000",
"PAN": "**** **** **** 2309 ",
"RRN": "313635350017",
"TSI": "",
"TVR": "0000000000",
"APSN": "00",
"DATE": "2023-05-16T07:35:38.759+0000",
"STAN": "",
"NAME_ON_CARD": "UnknownCardholderName",
"AMOUNT_CENTS": "-11000",
"ABS_AMOUNT": "110.00",
"RECEIPT_NUMBER": "",
"TERMINAL_ID": "88012399",
"TX_TYPE_DESCRIPTION": "REFUND",
"EXTERNAL_TERMINAL_ID": "",
"FORMATTED_OTHER_AMOUNT": "R 0.00",
"FORMATTED_AMOUNT": "-R 110.00",
"DESCRIPTION": "",
"BATCH_NUMBER": "0",
"SETTLEMENT_DATE": "2023-05-16T07:35:36.000+0000",
"SURCHARGE_AMOUNT": "0.00",
"EXTERNAL_TRANSACTION_GUID": "",
"CARD_BIN": "445143",
"TRANSACTION_INFO": "22620IH*324315",
"REPLACEMENT_TERMINAL_ID": "",
"POS_ENTRY": "701",
"RC_ISO_DESCRIPTION": "Approved",
"APPLICATION_LABEL": "VISA SAVINGS",
"MERCHANT_CITY": "Gauteng",
"MERCHANT_NAME": "Neels Wonderland",
"CUSTOMER_NAME": "",
"OTHER_AMOUNT": "0.00",
"APP_VERSION": "1.1.191",
"CARD_SEQ_NO": "",
"APP_LABEL": "VISA SAVINGS",
"INVOICE_NUM": "",
"MESSAGE_1": "",
"MESSAGE_2": "",
"CARD_TRANSACTION_TYPE": "CONTACTLESS",
"RESULT_CODE": "00",
"MERCHANT_COUNTRY_CODE": "ZA",
"REPRINT": "",
"PAN_HASH": "34608EF2196233B9E2B28AE64A7B7F8CD039D7B6A1BD587A9F184B1468B05BC2",
"AMOUNT": "-110.00",
"TIP_LABEL": "",
"DIGITS": "2309",
"CVM_ABSA": ""
},
"overrideMerchantNumber": "null",
"emailAddressToSendReceipt": "",
"merchantID": "880000000000123",
"merchantUsername": "default",
"externalTerminalId": "null",
"pebbleSerialNumber": "504C30323139364A3030383933",
"longitude": "0.0",
"originalTransactionUuid": "",
"thirdPartyUsername": "null",
"invoiceNumber": "null",
"isApproved": "true",
"keepAliveMinutes": "0",
"launchType": "REFUND",
"keepAliveAfterExit": "false",
"merchantCity": "null",
"merchantName": "Neels Wonderland",
"deviceIMEI": "null",
"cellNumberToSMSReceipt": "",
"customerName": "null",
"alwaysShowTransactionStatusScreen": "false",
"externalTransactionGUID": "null",
"transactionReferenceNo": "null",
"transactionUuid": "9117bb95-62b6-471b-b20a-0d42d96bf619",
"appVersion": "1.1.191",
"merchantCountryCode": "null",
"merchantCategoryCode": "null",
"externalTransactionDateTime": "null",
"transactionAmount": "11000"
},
"result": "SUCCESS"
}
- doTxRequest(uuid, callback)
Do a transaction lookup by UUID. If no UUID specified it will return the last transaction.
// get the last transaction
pb.doTxRequest("", txRequestCallback);
// Example of returned object in txRequestCallback
{
"thirdPartyMerchantNumber": "null",
"authenticationKey": "11111111-2222-3333-4444-555555555555",
"resultDescription": "DECLINED",
"merchantRegionCode": "null",
"isReceiptRequired": "false",
"latitude": "0.0",
"fwUpdateDate": "null",
"buildInfo": "THUMBZUP_TEST",
"externalSTAN": "0",
"terminalId": "88012381",
"applicationKey": "null",
"externalInvoiceGUID": "",
"fwUpdateVersion": "null",
"externalRRN": "429107450002",
"isReceiptDataAvailable": "true",
"pebbleFirmwareVersion": "null",
"matchedRefund": "false",
"resultCode": "02",
"transactionDescription": "null",
"fwUpdateAvailable": "false",
"receiptBundle": {
"MERCHANT_REGION_CODE": "03",
"RC_ALT": "62",
"STATUS": "DECLINED",
"BUDGET_PERIOD": "",
"CARD_TYPE": "",
"PAN_WITH_BIN": "448387** **** 9568",
"MERCHANT_ID": "880000000000123",
"TIMESTAMP": "1729145267000",
"EXTERNAL_TRANSACTION_DATETIME": "",
"PROCESSING_CODE": "",
"RC_DESCRIPTION": "Declined",
"EXTERNAL_INVOICE_GUID": "",
"REPLACEMENT_MERCHANT_ID": "",
"AUTH_PROFILE": "",
"INTERCHANGE": "null",
"ESC_BY_AUTH_CODE": "226 00 IT ",
"TX_TYPE": "DEBIT",
"ACC_TYPE_DESC": "",
"TIP_AMOUNT": "",
"CURRENCY_CODE": "ZAR",
"AUTH_CODE": " ",
"RC": "62",
"AID": "A00000000310100010",
"ATC": "",
"CRY": "7D4B23BDE4C46F77",
"CVM": "PIN Verified",
"CVR": "",
"PAN": "**** **** **** 9568",
"RRN": "429107450002",
"TSI": "",
"TVR": "",
"APSN": "",
"DATE": "2024-10-17T06:07:47.000+0000",
"STAN": "",
"NAME_ON_CARD": "",
"AMOUNT_CENTS": "290000",
"ABS_AMOUNT": "2,900.00",
"TOKEN": "",
"RECEIPT_NUMBER": "",
"TERMINAL_ID": "88012381",
"TX_TYPE_DESCRIPTION": "SALE",
"EXTERNAL_TERMINAL_ID": "",
"ADDITIONAL_AMOUNT": "0.00",
"FORMATTED_OTHER_AMOUNT": "ZAR 0.00",
"FORMATTED_AMOUNT": "ZAR 2900.00",
"DESCRIPTION": "",
"BATCH_NUMBER": "0",
"SETTLEMENT_DATE": "",
"SURCHARGE_AMOUNT": "0.00",
"EXTERNAL_TRANSACTION_GUID": "",
"CARD_BIN": "448387",
"REPLACEMENT_TERMINAL_ID": "",
"POS_ENTRY": "",
"RC_ISO_DESCRIPTION": "Restricted card",
"APPLICATION_LABEL": "Visa Debit",
"MERCHANT_CITY": "Gauteng",
"MERCHANT_NAME": "Neels Wonderland",
"CUSTOMER_NAME": "My Favorite Customer",
"OTHER_AMOUNT": "0.00",
"APP_VERSION": "1.1.212",
"CARD_SEQ_NO": "",
"APP_LABEL": "Visa Debit",
"INVOICE_NUM": "",
"MESSAGE_1": "",
"MESSAGE_2": "",
"CARD_TRANSACTION_TYPE": "ICC",
"RESULT_CODE": "62",
"MERCHANT_COUNTRY_CODE": "ZA",
"REPRINT": "",
"PAN_HASH": "B81B67C07ACB58EBD53257EA775A67CB766C7489F7D6B21F66257789DA8527B8",
"AMOUNT": "2,900.00",
"TIP_LABEL": "",
"DIGITS": "9568",
"CVM_ABSA": "PIN Verified"
},
"overrideMerchantNumber": "null",
"emailAddressToSendReceipt": "",
"merchantID": "880000000000000",
"merchantUsername": "null",
"externalTerminalId": "",
"pebbleSerialNumber": "50424533323235543430303032",
"longitude": "0.0",
"thirdPartyUsername": "null",
"invoiceNumber": "null",
"isApproved": "false",
"keepAliveMinutes": "0",
"launchType": "TX_SEARCH",
"keepAliveAfterExit": "false",
"merchantCity": "null",
"merchantName": "Neels Wonderland",
"cellNumberToSMSReceipt": "",
"customerName": "My Favorite Customer",
"alwaysShowTransactionStatusScreen": "false",
"externalTransactionGUID": "",
"transactionReferenceNo": "null",
"transactionType": "Sale",
"transactionUuid": "f763f214-d923-4ae0-be14-58a986b45472",
"appVersion": "1.1.212",
"merchantCountryCode": "null",
"merchantCategoryCode": "null",
"externalTransactionDateTime": "",
"transactionAmount": "290000"
}
printHtml(html, css, width, callback)
Send a request to PosBuddy to print the specified html.
// Example of html printing
let html = "<table style='width: 100%'><tr><td style='text-align: center'><h5>Hello World</h5></td></tr></table>";
let css = "* {margin-top:8px;margin-bottom:8px} h5,h5{font-size:24px;line-height:36px}";
let width = 0; // Printer width is ignored
pb.printHtml(html, css, width, printCallback);
// Format of callback function:
void printCallback(map<string, string> resultMap)
// Example of returned object in print callback
{
"result":"SUCCESS",
"commandId":"PRINT_HTML_RESPONSE"
}
setForeground(foreground, callback)
Force PosBuddy application to the foreground (foreground = true) or background (foreground = false)
// setForeground callback
{
"result": "SUCCESS"
}
getSettings(callback)
Return the saved settings from PosBuddy.
Currently these settings are supported:autoStart: Start the PosBuddy application when the device boot up.runInBackground: Minimise the PosBuddy application, except when doing a payment. In this mode you can connect to the PosBuddy application even when another application is in the foreground. When starting a payment, PosBuddy will start the payment application in the foreground.
When the payment is done, both the payment application and PosBuddy will go to the background and the original foreground application will be visible again.
// getSettings and updateSettings callback
{
"runInBackground": true,
"autoStart": true
}
updateSettings(autoStart, runInBackground, callback)
Update the settings permanently saved by PosBuddy.
The arguments (autoStartandrunInBackground) can either be true or false.
SeegetSettingsfor more details.
Once you are comfortable in understanding what the API functions are, it would be easier to execute the POS Buddy implementation.
The below code is a sample application that connects to a PosBuddy terminal. The application sends an auth call followed by a sale.
Example implementation:
<script type='text/javascript' src='posbuddy_1.0.js'></script>
<script language="javascript" type="text/javascript">
// Example implementation of PosBuddy in javascript
// To use it, copy the code into a file with a .html extension and update the device specific variables
var selected_items = [];
var pb = new posBuddy(pb_writeLog);
// Device specific variables
// Update these with your own environment variables
pb.setApplicationKey("6397dead-7d4b-47f7-a0a5-71e5d1705fc4");
pb.setUsername("default");
pb.setMerchantId("000000002451");
pb.setAuthenticationKey("2e4c6acd-9a66-439e-8d02-b39588081559");
pb.setBarcodeCallback(pb_barcodeCallback);
pb.connect("123456", pb_statusCallback); //This number can be found on the POSBuddy app.
// Initiate the auth call, result returned to pb_authCallback
function startAuth() {
pb.doAuth(pb_authCallback);
}
// Process result of auth. On success, start payment
function pb_authCallback(obj) {
if (typeof obj.errorBundle != 'undefined') {
console.log("Auth error: " + obj.errorBundle.description + "\n" + obj.errorBundle.message);
}
else {
pb.setAuthenticationKey(obj.authenticationKey);
startPayment();
}
}
function pb_barcodeCallback(barcode) {
console.log("Received barcode: " + barcode);
}
// Function to display items and initiate the payment process
function startPayment() {
// display items
selected_items.push({ "description": "Hamburger", "price": 5200, "count": 1 });
let total_amount = 5200;
pb.displayItems(total_amount, selected_items);
selected_items.push({ "description": "Coffee", "price": 3000, "count": 1 });
pb.displayItems(total_amount, selected_items);
total_amount += 3000;
// start payment after 3 seconds
setTimeout(() => {
pb.doSale(total_amount, null, pb_saleCallback);
}, 3000);
}
// This function logs debug data received from posbuddy
function pb_writeLog(logtype, message) {
if (logtype != pb.transmitData && logtype != pb.receiveData) console.log("Log received:" + message);
}
// This function logs the changes to the websocet status and start payment after connection success
function pb_statusCallback(status) {
switch (status) {
case pbStatus.connected:
console.log("Received status: connected");
startAuth();
break;
case pbStatus.disconnected:
console.log("Received status: disconnected");
break;
case pbStatus.error:
console.log("Received status: error");
break;
}
}
// This function is called when a payment is finished
function pb_saleCallback(obj) {
console.log("salecallback received: " + JSON.stringify(obj));
}
</script>
Updated 28 days ago