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

# WebXPay

> Use the released WebXPay V2 Pay Once redirect flow with Merchant API reconciliation.

## When to use WebXPay

This guide covers the released **WebXPay V2 Pay Once redirect** flow. Your backend creates checkout through shared `createOrder()`, WebXPay hosts the payment page, and AvraAPI reconciles the original order through WebXPay's authenticated Merchant API before a payment is considered final.

| Capability | Support |
| - | - |
| Checkout mode | `redirect` only |
| PHP SDK | Merchant API status lookup and browser-return wrapper released |
| Laravel SDK | Released through the `AvraAPI::payment()` Facade accessor |
| Node.js SDK | Released: Merchant-API status lookup and browser-return wrapper. |
| Payment Elements | Standard WebXPay redirect hand-off |
| Completion rule | Merchant API retrieval is authoritative |
| Not documented as released | Tokenization and iframe checkout |

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

## SDK Functions

<Tabs>
  <Tab title="PHP SDK">
    | Function | Purpose |
    | - | - |
    | `payment()->webxpay()->status()` | Retrieves the safe Merchant API summary for a known order ID. |
    | `new WebXPayReturnPayload(...)->toArray()` | Keeps an untrusted browser-return query 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().webxpay().status()` | Retrieves authoritative Merchant-API status for one order. |
    | `new WebXPayReturnPayload(...).toPayload()` | Wraps an untrusted browser return for shared completion. |
  </Tab>
</Tabs>

## Retrieve a Merchant API transaction status

Use `status()` only on your backend and only with the order ID you stored when creating checkout. The SDK authenticates to the configured WebXPay Merchant API, retrieves by merchant reference, validates the order binding, and maps the response to a safe summary.

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

    $status = $apix->payment()->webxpay()->status(
        orderId: $order->id,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    );
    ```

    **SDK response** — associative array:

    ```json theme={null}
    {
      "gateway": "webxpay",
      "gateway_reference": "WX-320000000000",
      "provider_status": "SUCCESS",
      "amount": "12000.00",
      "currency": "LKR"
    }
    ```

    The SDK rejects a Merchant API response that does not bind to the requested order ID or that lacks its transaction reference, amount, currency, or status. It intentionally omits raw provider payloads, login tokens, bank MID data, and browser-return data.
  </Tab>

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

    use Avraapi\Apix\Payments\GatewayEnvironment;

    $status = AvraAPI::payment()->webxpay()->status(
        orderId: $order->id,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    );
    ```
  </Tab>

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

    const status = await client.payment().webxpay().status(
      order.id,
      GatewayEnvironment.Sandbox,
    );
    ```
  </Tab>
</Tabs>

## Prepare a WebXPay browser-return payload

WebXPay returns the buyer to your configured HTTPS URL. The return may carry `result3ds`; it is a completion trigger, not payment proof. Preserve the full query in the SDK wrapper, then use shared `completePayment()` and the stored completion context on your backend.

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

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

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

    ```json theme={null}
    {
      "return": {
        "result3ds": "eyJ..."
      }
    }
    ```

    The wrapper does not decode, verify, or treat `result3ds` as successful payment data. During shared completion, AvraAPI checks any usable browser bindings and independently retrieves the Merchant API transaction for the prepared order.
  </Tab>

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

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

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

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

## Payment Elements

Use an explicit WebXPay card when you want to place it alongside other available methods. Elements receives only the public prepared redirect URL from your backend; WebXPay credentials, bank MID rules, and Merchant API credentials stay in the Gateway Vault.

```js theme={null}
elements.renderMethods('#payment-methods', {
  methods: [{
    gateway: 'webxpay',
    mode: 'redirect',
    label: 'Pay securely with WebXPay',
    description: 'Continue to WebXPay to complete your payment securely.',
  }],
});
```

Elements opens the prepared HTTPS checkout URL in the normal redirect flow. It does not expose a WebXPay iframe or tokenization UI in the released public package. For rendering, visual customization, events, and the checkout lifecycle, see [More Payment Elements features](/universal-payment-gateway/payment-elements/overview).

## Gateway-specific options

The released WebXPay redirect flow does not expose public checkout `providerOptions`.

* Your backend selects a configured bank MID from the Vault for the order currency; the buyer cannot supply or override it.
* Use a public HTTPS return URL. The backend validates the payment-page host before returning a redirect session.
* Do not send V2 login credentials, Merchant API credentials, tokens, bank MIDs, or `result3ds` data to the browser, logs, analytics, or client state.

## Completion, webhooks, and safety

Complete the original session from your backend with `completePayment()` and its default `reconcileProvider: true`. AvraAPI treats browser-return information only as an observation and retrieves the provider transaction by the original order reference. The normalized result can be `succeeded`, `pending`, `failed`, `cancelled`, or `unknown`; fulfil only a verified `succeeded` result.

If Merchant API retrieval is unavailable, the completion result remains non-final and recommends a backend retry. Do not turn a browser redirect, a base64 `result3ds` value, or a provider page event into payment proof.


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