OnePay JS

A lightweight checkout overlay for your website. No redirects, no page reloads, no lost customers halfway through a sale. Your buyer pays right where they are, and you get the result back in real time.

Why an overlay instead of a redirect

Sending a customer away from your website to pay, and hoping they come back, has always been a weak point in online checkout. Every redirect is a chance for someone to lose their place, get distracted, or simply give up.

OnePay JS solves this the way modern checkout experiences are meant to work. The payment form opens in a clean overlay on top of your page. Your customer never leaves your site. The moment they finish paying, your page hears about it instantly, with no polling and no guesswork.

Setup & Integration

Getting OnePay JS running on your site takes four short steps. Most teams have a working test payment within the hour.

1. Add the script

   Place this script tag in your page, ideally near the closing </body> tag so it loads after your content.

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

2. Get your credentials

   Log in to your OnePay merchant dashboard and open the App section to find your App ID, App Token, and Hash Salt. You will use all three in the next step.

   Warning

   Your Hash Salt should never be exposed in your frontend code. Generate the hash on your server and pass only the resulting hashToken value to the browser.

3. Set your payment data

   Define a window.onePayData object with your transaction details, then listen for the two events OnePay JS dispatches when the payment finishes.

   Configuration Fields

   Field	Type	Description
   appid Required	string	Your OnePay App ID.
   hashToken Required	string	Your Hash Salt, used by the script to sign the request. Keep this server-managed where possible.
   apptoken Required	string	Your App Token, sent as the Authorization header when the payment request is created.
   amount Required	number	The amount to charge, e.g. 100.00.
   currency Required	string	Three-letter currency code (e.g. LKR).
   orderReference Required	string	Your internal order or invoice reference.
   customerFirstName Required	string	Customer's first name.
   customerLastName Required	string	Customer's last name.
   customerPhoneNumber Required	string	Phone number in E.164 format, e.g. +94771234567.
   customerEmail Required	string	Customer's email address.
   transactionRedirectUrl Required	string	Fallback URL used by the gateway. The overlay flow does not navigate the customer away, but this is still required.
   additionalData Optional	string	Any extra metadata you want echoed back in the success or fail event.

   Code Examples

   HTMLPHPReact

   <script>
   window.onePayData = {
       appid: "80NR1189D04CD635D8ACD",
       hashToken: "GR2P1189D04CD635D8AFD",
       amount: 100.00,
       orderReference: "7Q1M1187AE",
       customerFirstName: "Amila",
       customerLastName: "Perera",
       customerPhoneNumber: "+94771234567",
       customerEmail: "amila@yourstore.lk",
       transactionRedirectUrl: "https://yourstore.lk/thank-you",
       additionalData: "returndata",
       apptoken: "YOUR_APP_TOKEN",
       currency: "LKR"
   };
   
   // Fires when the customer completes payment
   window.addEventListener("onePaySuccess", function (e) {
       const successData = e.detail;
       console.log("Payment SUCCESS", successData);
       // show a confirmation, update your order, etc.
   });
   
   // Fires when the payment is declined or cancelled
   window.addEventListener("onePayFail", function (e) {
       const failData = e.detail;
       console.log("Payment FAIL", failData);
   });
   </script>
   
   <!-- OnePayJS automatically injects a "Pay Now" button here -->
   <div id="onepay-btn"></div>

4. Test, then go live

   Use your sandbox App ID and App Token first to confirm everything fires correctly. Once a test payment completes successfully on your page, switch to your live credentials and you're ready to accept real transactions.

   Info

   OnePayJS automatically renders a Pay Now button inside the element with id onepay-btn. You don't need to build your own button, just provide the container and the data object.

Events & Callbacks

OnePay JS talks back to your page using two browser events. No polling, no waiting, no extra requests. The moment the customer's payment is decided, your code finds out.

OnePay Success

Dispatched the instant a payment completes successfully. The overlay closes itself automatically before this event fires, so your page is already clear to show a confirmation message.

OnePay Fail

Dispatched when a payment is declined, cancelled, or otherwise does not complete. Use this to let the customer know gently and offer them another attempt.

Listening for both events

window.addEventListener("onePaySuccess", function (e) {
  const { transaction_id, status } = e.detail;

  // Confirm the order in your own UI
  document.getElementById("order-status").textContent = "Payment received, thank you!";

  // Optional: verify server-side using the Transaction Status API
  fetch("/api/confirm-order", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ transaction_id }),
  });
});

window.addEventListener("onePayFail", function (e) {
  const { transaction_id } = e.detail;
  document.getElementById("order-status").textContent =
    "That payment didn't go through. Please try again.";
});

Server-side callback

In addition to the two browser events, OnePay can send a server-to-server callback to a URL you configure in your dashboard. This is the most reliable way to confirm payment outcomes, since it does not depend on the customer's browser staying open.

Set your callback URL under the App section of your OnePay dashboard. Your endpoint should accept a POST request with a JSON body and respond with a 200 status.

Sample callback payload

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

Use this payload to log the transaction, verify it against your own records, and update the order status in your system. Always treat the callback and the Transaction Status API as your source of truth, with the browser events as a fast, friendly layer on top for your customer's experience.