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:

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
    }
};

Secure Connection Example:

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
    }
};

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.

Example Code:

// 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.");
};

Find Payment Sample Response model here

Refund

To process a refund, provide the transactionUuid of the original transaction you wish to refund.

Processing a Refund Using WiFi Integration

To initiate a refund using the WiFi Integration method, establish a WebSocket connection and communicate with the Easypay service in real-time.

Example Code:

// 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.");
};

Find Payment Sample Response model here

Reconciliation

Processing a Reconcile Using WiFi Integration

To initiate a Reconcile using the WiFi Integration method, establish a WebSocket connection and communicate with the Easypay service in real-time.

Example Code:

// 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.");
};

Receipt Management

Printing the Last Transaction Receipt

// 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.");
};

Summary of Core Functionalities WiFi Integration

Functionality	WiFi Integration
Making a Payment	- Sends { method: "PURCHASE", amount, customerReferenceNumber } via WebSocket - Handles real-time responses
Processing a Refund	- Sends { method: "REFUND", transactionUuid, amount, customerReferenceNumber } via WebSocket - Handles real-time responses
Printing Last Receipt	- Sends { method: "PrintLastResult" } via WebSocket - Handles real-time responses
Opening the Cash Drawer	- Sends { method: "OpenDrawer" } via WebSocket - Handles real-time responses