Getting Started

Welcome to our documentation! This guide will help you get started with our platform.

Overview

Our API provides a simple and secure way to process payments and manage subscriptions. This guide covers the basics of integrating with our platform.

Authentication

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

API Keys

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

Authorization:  YOUR_APP_TOKEN
                    

Error Handling

Our API uses conventional HTTP response codes to indicate the success or failure of an API request.

Error Codes

OnepayJS Script File Usage

OnePayJS is a lightweight JavaScript that facilitates seamless integration with the OnePay payment gateway, allowing businesses to accept payments effortlessly on their websites. Designed for simplicity and efficiency, OnePayJS eliminates the need for page redirections by enabling an on-site payment gateway overlay.

1. Import onepayJs from this url link
<script src="https://storage.googleapis.com/onepayjs/onepayjs.js"></script>
2. Add it into your project index file
3. Log into our onepay Dashboard and find the app id, Hash token and app token. You can see how its done here
4. Add the following code based on your projects code base

                        

                            HTML
                            PHP
                            React
                        
                        
                        

                            Copy
                            
<script>
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"

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

                        

                            Copy
                            
<?php
$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"

];
?>
<script>
// Convert the PHP array to a JSON object
window.onePayData = <?php echo json_encode($onePayData, JSON_UNESCAPED_SLASHES); ?>;

// Listen for success event
window.addEventListener("onePaySuccess", function (e) {
    const successData = e.detail;
    console.log("Payment SUCCESS (from PHP):", successData);
    // You can do additional processing here or send an AJAX request to PHP
});

// Listen for fail event
window.addEventListener("onePayFail", function (e) {
    const failData = e.detail;
    console.log("Payment FAIL (from PHP):", failData);
    // You can do additional processing here or send an AJAX request to PHP
});
</script>
                        

                        

                            Copy
                            
import React, { useEffect } from "react";

function App() {
    const onePayData = {
        appid: "80NR1189D04CD635D8ACD",
        hashToken: "GR2P1189D04CD635D8AFD",
        amount: 100.0,
        orderReference: "7Q1M1187AE",
        customerFirstName: "Johe",
        customerLastName: "Dohe",
        customerPhoneNumber: "+94771234567",
        customerEmail: "test@gmail.com",
        transactionRedirectUrl: "https://www.google.com.au",
        additionalData: "returndata",
        apptoken: "ca00d67bf74d77b01fa26dc6780d7ff9522d8f82d30ff813d4c605f2662cea9ad332054cc66aff68.EYAW1189D04CD635D8B20"

    };

    useEffect(() => {
        // 1. Expose onePayData globally
        window.onePayData = onePayData;

        // 2. Add event listeners
        const handleOnePaySuccess = (e) => {
            const successData = e.detail;
            console.log("Payment SUCCESS from React:", successData);
        };

        const handleOnePayFail = (e) => {
            const failData = e.detail;
            console.log("Payment FAIL from React:", failData);
        };

        window.addEventListener("onePaySuccess", handleOnePaySuccess);
        window.addEventListener("onePayFail", handleOnePayFail);

        return () => {
            window.removeEventListener("onePaySuccess", handleOnePaySuccess);
            window.removeEventListener("onePayFail", handleOnePayFail);
        };
    }, [onePayData]);

    return (
        <div style={{ margin: "20px" }}>
            <div id="onepay-btn" />
            <div id="iframe-container" />
        </div>
    );
}

export default App;
                        
                    

API Implementation

This guide walks you through the process of implementing our payment system using the REST APIs. We'll cover the steps from creating items to processing payments.

Implementation Steps

1. Create Items (Optional)

   If you want to associate specific items with your payment request:

   • Use the Create Item API to create items in the system
   • Store the returned item_id for use in payment requests
   • You can verify the item creation using the Get Item API
   • Items can be updated later using the Update Item API if needed
2. Generate Hash Key

   Before creating a payment request, you need to generate a hash key:

   • Concatenate the following values in order: app_id + currency + amount + <<YOUR HASH SALT>>
   • Apply SHA-256 algorithm to the concatenated string
   • Use the resulting hash string in your payment request

   Example hash generation:

   Input string: "80NR1189D04CD635D8ACDLKR100.00XXXHASHSALTXXX"
   Hash result: "126ff89348d80fb91ec4f25c2bd55e2f71d8f3986da9470eabe28b2f8becf21a"

3. Create Payment Request

   To initiate a payment transaction:

   • Use the Create Transaction API
   • Include the item_ids in the request if you want to associate specific items
   • The API will return a payment URL that you can use to redirect customers to the payment gateway
4. Track Payment Status

   To monitor the payment status:

   • Use the Get Transaction API to check the payment status
   • Poll this endpoint periodically to track the payment completion
5. Callback Response

   Set up your system to receive transaction status updates:

   • Update your callback URL in the APP section of the Onepay portal
   • Your endpoint should be configured to accept POST requests with JSON payloads
   • After transaction completion, Onepay will send a callback with transaction details

   Sample callback payload:

   {
       "transaction_id": "WQBV118E584C83CBA50C6",
       "status": 1,
       "status_message": "SUCCESS",
       "additional_data": ""
   }

   Use this callback data for logging, verification, and updating transaction status in your system.

WordPress Plugin Integration

Installation Steps

1. Install the Plugin

   You can install the plugin in one of two ways:

   • Visit WordPress Plugin Directory
   • Or search for "Onepay Payment Gateway" from the WordPress plugins section
2. Activate the Plugin

   After installation, activate the plugin from your WordPress plugins page

3. Configure Plugin Settings

   Navigate to the plugin settings page and configure the following:

   • Copy your App ID from the merchant portal
   • Copy your App Token from the merchant portal
   • Copy your Hash Salt from the merchant portal
   • Paste these values in their respective fields in the Onepay plugin settings
4. Redirect Settings

   The default redirect is set to the WooCommerce thank you page. You can keep this setting unless you have specific requirements.

Shopify Plugin Integration

Installation Steps

1. Install the App

   Visit the Onepay Payment Gateway on the Shopify App Store and click "Install"

2. Authentication

   You will be redirected to:

   • Enter your Shopify domain (if not logged in)
   • Or directly to the app page (if already logged in)
3. Grant Permissions

   Review and approve the permission requests to install the app

4. Configure App Settings

   On the Onepay Shopify app management page:

   • Copy your App ID from the merchant portal
   • Copy your App Token from the merchant portal
   • Copy your Hash Salt from the merchant portal
   • Paste these values in their respective fields
   • Click the Save button to apply your changes

WHMCS Plugin Integration

Installation Steps

1. Get Plugin Files

   After successful onboarding with Onepay, you will receive a ZIP file containing the plugin files

2. Extract Files

   Unzip the file contents on your computer

3. Install Gateway Module

   On your WHMCS server:

   • Navigate to modules/gateways directory
   • Copy the onepay folder and onepay.php file from the extracted ZIP
   • Paste them into the gateways directory
4. Install Callback Handler

   Still on your WHMCS server:

   • Navigate to gateways/callback directory
   • Copy the onepay.php file from the callback folder in the ZIP
   • Paste it into the callback directory
5. Configure Plugin Settings

   In your WHMCS admin panel:

   • Locate Onepay in the payment gateways section
   • Copy your App ID from the merchant portal
   • Copy your App Token from the merchant portal
   • Copy your Hash Salt from the merchant portal
   • Paste these values in their respective fields
   • Click Save to apply your changes

Test Card Details

Use the following test card details for integration testing: