For the complete documentation index, see llms.txt. This page is also available as Markdown.
Payment WiFi Integration
Initialize
1- Start Easypay Service:
Click the Connect button in the Easypay app.
Click Start to initiate the service.
Save the displayed IP Address for later use.
Click Running in Background to keep the service active.
2- Create WebSocket Connection:
Easypay service operates on two ports:
5000: Insecure connection (HTTP)
9000: Secure connection (HTTPS)
Insecure Connection Example:
Secure Connection Example:
Purchase
Important: The amount should be entered without decimals. For example, 100 represents 1.00 SAR, and 1455 represents 14.55 SAR. The maximum length is 12 digits, including the exponent (e.g., 123456789012 equals 1,234,567,890.12 SAR).
Reference ID: You may pass a Reference ID in the customerReferenceNumber field to attach it to the transaction. Otherwise, set it to null.
Processing a Purchase Request Using WiFi Integration
To initiate a payment using the WiFi Integration method, establish a WebSocket connection and communicate with the Easypay service in real-time.
const socket = new WebSocket("ws://localhost:5000"); // Use "localhost" for same device or replace with "IP address" for external connections.
// Response format
socket.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.method === "WebSocketOpen" && data.DeviceName !== 'null') {
// Initialization successful
const deviceName = data.DeviceName; // Device name if supported by Easypay
}
};
const socket = new WebSocket("wss://localhost:9000"); // Use "localhost" for same device or replace with "IP address" for external connections.
// Response format
socket.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.method === "WebSocketOpen" && data.DeviceName !== 'null') {
// Initialization successful
const deviceName = data.DeviceName; // Device name if supported by Easypay
}
};
// Function to make a payment using WebSocket Integration
function makePaymentWebSocket(socket, amount, customerReferenceNumber) {
// Prepare the payment data
const paymentData = [
{
method: "PURCHASE",
amount: amount, // [Required] Amount to set (e.g., 100 represents 1.00 SAR)
customerReferenceNumber: customerReferenceNumber || null // [Optional] Any string as a reference number
}
];
// Send the payment request through the WebSocket
try {
socket.send(JSON.stringify(paymentData));
console.log("Purchase request sent:", paymentData);
} catch (sendError) {
console.error("Failed to send purchase request:", sendError);
// Optionally, implement retry logic or notify the user
return;
}
// Event listener for handling responses
socket.onmessage = (event) => {
try {
const responseData = JSON.parse(event.data);
// Simplified Error Handling
if (responseData.error || responseData === false) {
console.error("Payment Error:", responseData.error || "Invalid response.");
// Optionally, notify the user about the error
return;
} else {
const paymentResult = JSON.parse(responseData.message);
if (paymentResult.is_approved) {
console.log("Payment Successful:", paymentResult);
// Optionally, proceed with post-payment actions
} else {
console.warn("Payment Rejected:", paymentResult);
// Optionally, notify the user about the rejection
}
}
} catch (parseError) {
console.error("Failed to parse WebSocket message:", parseError);
// Optionally, handle parsing errors or notify the user
}
};
}
// Example usage:
const socket = new WebSocket("wss://your-ip-address:9000");
socket.onopen = () => {
console.log("WebSocket connection established.");
makePaymentWebSocket(socket, 100, "1234");
};
socket.onclose = () => {
console.log("WebSocket connection closed.");
};
// Function to process a refund using WebSocket Integration
function processRefundWebSocket(socket, transactionUuid, amount, customerReferenceNumber) {
// Prepare the refund data
const refundData = [
{
method: "REFUND",
transactionUuid: transactionUuid, // [Required] Original transaction UUID.
amount: amount, // [Required] Amount to refund.
customerReferenceNumber: customerReferenceNumber || null // [Optional] Any string as a reference number.
}
];
// Send the refund request through the WebSocket
try {
socket.send(JSON.stringify(refundData));
console.log("Refund request sent:", refundData);
} catch (sendError) {
console.error("Failed to send refund request:", sendError);
// Optionally, implement retry logic or notify the user
return;
}
// Event listener for handling responses
socket.onmessage = (event) => {
try {
const responseData = JSON.parse(event.data);
// Simplified Error Handling
if (responseData.error || responseData === false) {
console.error("Refund Error:", responseData.error || "Invalid response.");
// Optionally, notify the user about the error
return;
} else {
const refundResult = JSON.parse(responseData.message);
if (refundResult.is_approved) {
console.log("Refund Successful:", refundResult);
// Optionally, proceed with post-refund actions
} else {
console.warn("Refund Rejected:", refundResult);
// Optionally, notify the user about the rejection
}
}
} catch (parseError) {
console.error("Failed to parse WebSocket message:", parseError);
// Optionally, handle parsing errors or notify the user
}
};
}
// Example usage:
const socket = new WebSocket("wss://your-ip-address:9000");
socket.onopen = () => {
console.log("WebSocket connection established.");
processRefundWebSocket(socket, "f5079b9d-b61c-4180-8a4d-9780f7a9cd8f", 100, "ORDER1234");
};
socket.onclose = () => {
console.log("WebSocket connection closed.");
};
// Function to reconcile transactions using WebSocket Integration
function reconcileWebSocket(socket) {
// Prepare the reconcile data
var data = {
"method": "reconcile"
};
// Send the reconcile request through the WebSocket
try {
socket.send(JSON.stringify(data));
console.log("Reconciliation request sent:", data);
} catch (sendError) {
console.error("Failed to send reconciliation request:", sendError);
// Optionally, implement retry logic or notify the user
return;
}
// Event listener for handling responses
socket.onmessage = (event) => {
try {
const responseData = JSON.parse(event.data);
// Simplified Error Handling
if (responseData.error || responseData === false) {
console.error("Reconciliation Error:", responseData.error || "Invalid response.");
// Optionally, notify the user about the error
return;
} else {
const reconcileResult = JSON.parse(responseData.message);
if (reconcileResult .is_balanced !== undefined && reconcileResult .is_balanced.value) {
console.log("Reconciliation Successful:", reconcileResult );
// Optionally, proceed with post-reconciliation actions
} else {
console.warn("Reconciliation Rejected:", reconcileResult );
// Optionally, notify the user about the rejection
}
}
} catch (parseError) {
console.error("Failed to parse WebSocket message:", parseError);
// Optionally, handle parsing errors or notify the user
}
};
}
// Example usage:
const socket = new WebSocket("wss://your-ip-address:9000");
socket.onopen = () => {
console.log("WebSocket connection established.");
reconcileWebSocket(socket);
};
socket.onclose = () => {
console.log("WebSocket connection closed.");
};
// Function to print the last transaction receipt using WebSocket Integration
function printLastReceiptWebSocket(socket) {
// Prepare the print request data
const printRequest = {
method: "PrintLastResult"
};
// Send the print request through the WebSocket
try {
socket.send(JSON.stringify(printRequest));
console.log("Print request sent:", printRequest);
} catch (sendError) {
console.error("Failed to send print request:", sendError);
// Optionally, implement retry logic or notify the user
return;
}
}
// Example usage:
const socket = new WebSocket("wss://your-ip-address:9000");
socket.onopen = () => {
console.log("WebSocket connection established.");
printLastReceiptWebSocket(socket);
};
socket.onclose = () => {
console.log("WebSocket connection closed.");
};
