> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OnePay

> Use OnePay redirect or overlay checkout with backend status reconciliation.

## 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 |

<Note>
  The shared UPG lifecycle—availability, `createOrder()`, and `completePayment()`—is documented in [Quick Setup](/universal-payment-gateway/quick-setup). This page covers only OnePay-specific functions and presentation.
</Note>

## SDK Functions

<Tabs>
  <Tab title="PHP 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. |
  </Tab>

  <Tab title="Laravel SDK">
    | Function | Purpose |
    | - | - |
    | Laravel Facade | Use `AvraAPI::payment()` with the released typed helpers shown in the Laravel samples below. |
  </Tab>

  <Tab title="Node.js SDK">
    | 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. |
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="PHP SDK">
    ```php theme={null}
    use Avraapi\Apix\Payments\GatewayEnvironment;

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

    **SDK response** — associative array:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Laravel SDK">
    ```php theme={null}
    use Avraapi\Laravel\Facades\AvraAPI;

    use Avraapi\Apix\Payments\GatewayEnvironment;

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

  <Tab title="Node.js SDK">
    ```ts theme={null}
    import { GatewayEnvironment } from '@avraapi/node-sdk';

    const status = await client.payment().onepay().status(
      onePayTransactionId,
      GatewayEnvironment.Sandbox,
    );
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="PHP SDK">
    ```php theme={null}
    use Avraapi\Apix\Payments\OnePay\OnePayCallbackPayload;

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

    **SDK response** — the exact callback array under `callback`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Laravel SDK">
    ```php theme={null}
    use Avraapi\Apix\Payments\OnePay\OnePayCallbackPayload;

    $payload = (new OnePayCallbackPayload($request->all()))->toArray();
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```ts theme={null}
    import { OnePayCallbackPayload } from '@avraapi/node-sdk';

    const payload = new OnePayCallbackPayload(request.body).toPayload();
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="PHP SDK">
    ```php theme={null}
    use Avraapi\Apix\Payments\OnePay\OnePayReturnPayload;

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

    **SDK response** — the exact query array under `return`:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Laravel SDK">
    ```php theme={null}
    use Avraapi\Apix\Payments\OnePay\OnePayReturnPayload;

    $payload = (new OnePayReturnPayload($_GET))->toArray();
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```ts theme={null}
    import { OnePayReturnPayload } from '@avraapi/node-sdk';

    const payload = new OnePayReturnPayload(request.query).toPayload();
    ```
  </Tab>
</Tabs>

## 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.

```js theme={null}
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](/universal-payment-gateway/payment-elements/overview).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.