WebXPay - AvraAPI

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

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

SDK Functions

PHP SDK
Laravel SDK
Node.js 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.

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

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.

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.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\GatewayEnvironment;

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

SDK response — associative array:

{
  "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.

use Avraapi\Laravel\Facades\AvraAPI;

use Avraapi\Apix\Payments\GatewayEnvironment;

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

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

const status = await client.payment().webxpay().status(
  order.id,
  GatewayEnvironment.Sandbox,
);

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.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\WebXPay\WebXPayReturnPayload;

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

SDK response — the exact query array under return:

{
  "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.

use Avraapi\Apix\Payments\WebXPay\WebXPayReturnPayload;

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

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

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

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.

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.

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.

​When to use WebXPay

​SDK Functions

​Retrieve a Merchant API transaction status

​Prepare a WebXPay browser-return payload

​Payment Elements

​Gateway-specific options

​Completion, webhooks, and safety

When to use WebXPay

SDK Functions

Retrieve a Merchant API transaction status

Prepare a WebXPay browser-return payload

Payment Elements

Gateway-specific options

Completion, webhooks, and safety