OnePay - AvraAPI

When to use OnePay

Use OnePay when your project has an active OnePay Gateway Vault configuration and you need a provider-hosted checkout in LKR or USD. Start checkout with the shared createOrder() function, then use the OnePay-specific status function only from your backend when you need to observe a pending transaction.

Capability	Support
Checkout modes	`redirect`, `overlay`
PHP SDK	Status lookup and callback/return payload wrappers released
Laravel SDK	Released through the `AvraAPI::payment()` Facade accessor
Node.js SDK	Released: transaction-status lookup plus callback and return payload wrappers.
Payment Elements	OnePay redirect card or official OnePay SDK overlay; overlay may fall back to redirect
Completion rule	Provider status reconciliation is always required

The shared UPG lifecycle—availability, createOrder(), and completePayment()—is documented in Quick Setup. This page covers only OnePay-specific functions and presentation.

SDK Functions

PHP SDK
Laravel SDK
Node.js SDK

Function	Purpose
`payment()->onepay()->status()`	Gets the safe current provider summary for a known OnePay transaction ID.
`new OnePayCallbackPayload(...)->toArray()`	Keeps callback fields together as a completion trigger.
`new OnePayReturnPayload(...)->toArray()`	Keeps browser-return query fields together as a completion trigger.

Function	Purpose
Laravel Facade	Use `AvraAPI::payment()` with the released typed helpers shown in the Laravel samples below.

Function	Purpose
`client.payment().onepay().status()`	Retrieves server-side OnePay transaction status.
`new OnePayCallbackPayload(...).toPayload()`	Wraps an untrusted provider callback for shared completion.
`new OnePayReturnPayload(...).toPayload()`	Wraps an untrusted browser return for shared completion.

Retrieve a OnePay transaction status

Use status() for a transaction ID that your backend stored from the prepared checkout session. It retrieves the OnePay provider observation and returns a small, safe summary. It is useful for bounded polling while an order remains pending; it is not a substitute for the normal shared completion flow.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\GatewayEnvironment;

$status = $apix->payment()->onepay()->status(
    onePayTransactionId: $order->onepay_transaction_id,
    gatewayEnvironment: GatewayEnvironment::Sandbox,
);

SDK response — associative array:

{
  "gateway": "onepay",
  "gateway_reference": "OP-320000000000",
  "provider_status": "SUCCESS",
  "amount": "12000.00",
  "currency": "LKR",
  "paid_on": "2026-09-28T10:30:00+00:00"
}

paid_on is null when OnePay has not supplied a payment time. provider_status is SUCCESS or PENDING in this status summary. The SDK does not return OnePay credentials, raw request signatures, or provider-native response data.

use Avraapi\Laravel\Facades\AvraAPI;

use Avraapi\Apix\Payments\GatewayEnvironment;

$status = AvraAPI::payment()->onepay()->status(
    onePayTransactionId: $order->onepay_transaction_id,
    gatewayEnvironment: GatewayEnvironment::Sandbox,
);

import { GatewayEnvironment } from '@avraapi/node-sdk';

const status = await client.payment().onepay().status(
  onePayTransactionId,
  GatewayEnvironment.Sandbox,
);

Prepare a callback payload

OnePay callbacks can wake up your completion handler, but they are not payment proof. Preserve the callback exactly in a OnePayCallbackPayload, then pass its array to shared completePayment() together with the original server-only completion context.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\OnePay\OnePayCallbackPayload;

$payload = (new OnePayCallbackPayload($request->all()))->toArray();

SDK response — the exact callback array under callback:

{
  "callback": {
    "ipg_transaction_id": "OP-320000000000"
  }
}

The original callback fields are preserved unchanged. Do not trust them as a successful payment result: the shared completion request independently retrieves OnePay transaction status.

use Avraapi\Apix\Payments\OnePay\OnePayCallbackPayload;

$payload = (new OnePayCallbackPayload($request->all()))->toArray();

import { OnePayCallbackPayload } from '@avraapi/node-sdk';

const payload = new OnePayCallbackPayload(request.body).toPayload();

Prepare a browser-return payload

A customer returning to your application is only a signal to check the payment. Wrap the query parameters and complete the original payment on your backend; never mark an order as paid from the browser redirect alone.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\OnePay\OnePayReturnPayload;

$payload = (new OnePayReturnPayload($_GET))->toArray();

SDK response — the exact query array under return:

{
  "return": {
    "ipg_transaction_id": "OP-320000000000"
  }
}

OnePay’s returned transaction ID, when present, is bound to the prepared transaction before provider status is used for the final result.

use Avraapi\Apix\Payments\OnePay\OnePayReturnPayload;

$payload = (new OnePayReturnPayload($_GET))->toArray();

import { OnePayReturnPayload } from '@avraapi/node-sdk';

const payload = new OnePayReturnPayload(request.query).toPayload();

Payment Elements

Use an explicit OnePay method when you want to control its title and placement. Keep the mode returned by server-side availability: overlay uses the official OnePay SDK presentation, while redirect sends the customer to the prepared hosted URL.

elements.renderMethods('#payment-methods', {
  methods: [{
    gateway: 'onepay',
    mode: 'overlay',
    label: 'Pay securely with OnePay',
    description: 'Open OnePay secure checkout without leaving this page.',
  }],
});

If the official overlay cannot start and the prepared session permits it, Elements can hand off to the OnePay redirect URL. That browser presentation is not a payment result. For rendering, visual customization, events, and the checkout lifecycle, see More Payment Elements features.

Gateway-specific options

There are no released OnePay tender-selection providerOptions. Your backend may choose redirect or overlay only after availability confirms that OnePay and the selected mode are usable for the active project environment.

The OnePay transaction reference comes from the prepared session; do not invent or replace it in browser code.
The configured Gateway Vault environment is selected on the backend. A buyer must never select sandbox or production.
overlay does not remove the need for a return URL and a configured OnePay notification path.

Completion, webhooks, and safety

On a callback or browser return, pass the stored completion context and one of the payloads above to common completePayment() with its default reconcileProvider: true. OnePay status is the authority for a terminal result. The normalized response can be succeeded, pending, failed, cancelled, or unknown; fulfil only when it is verified and paymentStatus is succeeded. If status retrieval is temporarily unavailable, retain the order as pending and retry from your backend with bounded, idempotent work. Never use an overlay event, callback arrival, or browser redirect as proof of payment.

​When to use OnePay

​SDK Functions

​Retrieve a OnePay transaction status

​Prepare a callback payload

​Prepare a browser-return payload

​Payment Elements

​Gateway-specific options

​Completion, webhooks, and safety

When to use OnePay

SDK Functions

Retrieve a OnePay transaction status

Prepare a callback payload

Prepare a browser-return payload

Payment Elements

Gateway-specific options

Completion, webhooks, and safety