OnePay API Integration Guide

This guide provides the foundational steps for integrating with the OnePay platform securely and efficiently, whether you are utilizing direct API calls, our frontend JavaScript library, or our pre-built e-commerce plugins.

1. Authentication

All API requests require authentication using an API key. You can obtain your API key from the developer dashboard.

Include your API key or App Token in the Authorization header of all requests:

Authorization: YOUR_APP_TOKEN

2. Error Handling

The OnePay API uses conventional HTTP response codes to indicate the success or failure of a request.

3. API Implementation (Direct REST APIs)

If you are building a custom server-side integration, follow these standard steps to process a payment:

• Create Items (Optional): Use the Create Item API to register specific products and store the returned item_id. You can verify and update these items using the Get Item and Update Item APIs.
• Generate Hash Key: Concatenate the following string exactly: app_id + currency + amount + <<YOUR HASH SALT>>. Apply the SHA-256 algorithm to this string to generate your secure hash.
• Create Payment Request: Call the Create Transaction API with your data and hash. This will return a URL to redirect customers to the payment gateway.
• Track Payment Status: Poll the Get Transaction API endpoint periodically to check the payment's completion status.
• Callback Response: Configure your callback URL in the OnePay portal APP section. OnePay will send a POST request with a JSON payload containing transaction_id, status, status_message, and additional_data upon transaction completion.

4. OnePayJS Integration

OnePayJS is a lightweight JavaScript library that enables an on-site payment gateway overlay, eliminating the need for page redirections.

Steps to Implement:

1. Import the script into your HTML head or body:

   <script src="https://storage.googleapis.com/onepayjs/onepayv2.js"></script>

2. Retrieve your appid, hashToken, and apptoken from the OnePay Dashboard.
3. Configure the window.onePayData object with your transaction details.
4. Set up event listeners for onePaySuccess and onePayFail to handle the payment outcome.

JavaScript Configuration Example:

window.onePayData = {
    appid: "80NR1189D04CD635D8ACD",
    hashToken: "GR2P1189D04CD635D8AFD",
    amount: 100.00,
    orderReference: "7Q1M1187AE",
    customerFirstName: "Johe",
    customerLastName: "Dohe",
    customerPhoneNumber: "+94771234567",
    customerEmail: "test@gmail.com",
    transactionRedirectUrl: "https://www.google.com.au",
    additionalData: "returndata",
    apptoken: "ca00d67bf74d77b01fa26dc6780d7ff9522d8f82d30ff813d4c605f2662cea9ad332054cc66aff68.EYAW1189D04CD635D8B20",
    currency: "LKR"
};

window.addEventListener("onePaySuccess", function (e) {
    const successData = e.detail;
    console.log("Payment SUCCESS ", successData);
});

window.addEventListener("onePayFail", function (e) {
    const failData = e.detail;
    console.log("Payment FAIL", failData);
});

5. Platform Plugins

OnePay offers pre-built integrations for popular frameworks and e-commerce platforms.

6. Test Card Details

Use the following test card credentials for testing your integration in sandbox mode: