MarxPay - AvraAPI

When to use MarxPay

MarxPay is a one-time, redirect-only checkout for a project that has MarxPay tender variants enabled in its Gateway Vault. Use the shared createOrder() function to prepare checkout; use the functions below only on your backend to bind and inspect a MarxPay return safely.

Capability	Support
Checkout mode	`redirect` only
Tender variants	`OTHER`, `AMEX`, `OTHER_USD`, `AMEX_USD`, `PAY_BY_BANK_ACCOUNT`
PHP SDK	Return verification, initiation, and order-summary retrieval released
Laravel SDK	Released through the `AvraAPI::payment()` Facade accessor
Node.js SDK	Released: return verification, payment initiation, and order-summary retrieval.
Payment Elements	Separate cards for enabled tender variants, followed by a redirect hand-off

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

SDK Functions

PHP SDK
Laravel SDK
Node.js SDK

Function	Purpose
`payment()->marxpay()->verifyReturn()`	Confirms returned `merchantRID` and `trId` match the binding saved with your pending order.
`payment()->marxpay()->initiatePayment()`	Starts the provider-side payment only for a verified, bound MarxPay transaction.
`payment()->marxpay()->retrieveOrderSummary()`	Retrieves the safe current summary for a known, bound MarxPay transaction.

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

Function	Purpose
`client.payment().marxpay().verifyReturn()`	Verifies returned transaction binding before initiation.
`client.payment().marxpay().initiatePayment()`	Initiates the verified MarxPay transaction.
`client.payment().marxpay().retrieveOrderSummary()`	Retrieves one provider order summary.

Verify a browser return

The browser return contains merchantRID and trId. Those values are identifiers, not payment proof. Compare them against the pair your backend saved when it created the checkout session before doing anything else.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\GatewayEnvironment;
use Avraapi\Apix\Payments\MarxPay\MarxPayReturnVerificationOptions;

$verification = $apix->payment()
    ->marxpay()
    ->verifyReturn(new MarxPayReturnVerificationOptions(
        returnedMerchantRid: (string) ($_GET['merchantRID'] ?? ''),
        returnedTrId: (string) ($_GET['trId'] ?? ''),
        expectedMerchantRid: $order->merchant_rid,
        expectedTrId: $order->marxpay_tr_id,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    ));

SDK response — MarxPayReturnVerification:

{
  "verified": true,
  "merchant_rid": "ORDER-2026-000184",
  "tr_id": "MP-320000000000",
  "request_id": "01j..."
}

The SDK exposes these as $verification->verified, $verification->merchantRid, $verification->trId, and $verification->requestId. A mismatch raises an exception; do not change order state.

use Avraapi\Laravel\Facades\AvraAPI;

use Avraapi\Apix\Payments\GatewayEnvironment;
use Avraapi\Apix\Payments\MarxPay\MarxPayReturnVerificationOptions;

$verification = AvraAPI::payment()
    ->marxpay()
    ->verifyReturn(new MarxPayReturnVerificationOptions(
        returnedMerchantRid: (string) ($_GET['merchantRID'] ?? ''),
        returnedTrId: (string) ($_GET['trId'] ?? ''),
        expectedMerchantRid: $order->merchant_rid,
        expectedTrId: $order->marxpay_tr_id,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    ));

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

const verifiedReturn = await client.payment().marxpay().verifyReturn(
  new MarxPayReturnVerificationOptions({
    returnedMerchantRid: String(request.query.merchantRID ?? ''),
    returnedTrId: String(request.query.trId ?? ''),
    expectedMerchantRid: order.id,
    expectedTrId: order.gatewayTransactionId,
    gatewayEnvironment: GatewayEnvironment.Sandbox,
  }),
);

Initiate a verified MarxPay payment

Use this function only after verifyReturn() succeeds for the same saved merchantRID and trId. It asks MarxPay to initiate the bound transaction. It does not replace the final common UPG completion step.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\GatewayEnvironment;
use Avraapi\Apix\Payments\MarxPay\MarxPayInitiatePaymentOptions;

$result = $apix->payment()
    ->marxpay()
    ->initiatePayment(new MarxPayInitiatePaymentOptions(
        trId: $order->marxpay_tr_id,
        merchantRid: $order->merchant_rid,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    ));

SDK response — MarxPayPaymentResult:

{
  "merchant_rid": "ORDER-2026-000184",
  "tr_id": "MP-320000000000",
  "payment_status": "pending",
  "provider_status": "PENDING",
  "amount": "12000.00",
  "currency": "LKR",
  "payment_method": "OTHER",
  "expires_at": "2026-09-28T12:30:00+00:00",
  "request_id": "01j..."
}

The PHP object properties are $result->merchantRid, $result->trId, $result->paymentStatus, $result->providerStatus, $result->amount, $result->currency, $result->paymentMethod, $result->expiresAt, and $result->requestId. payment_status can be succeeded, pending, failed, or unknown; a started payment is not automatically a completed payment.

use Avraapi\Laravel\Facades\AvraAPI;

use Avraapi\Apix\Payments\GatewayEnvironment;
use Avraapi\Apix\Payments\MarxPay\MarxPayInitiatePaymentOptions;

$result = AvraAPI::payment()
    ->marxpay()
    ->initiatePayment(new MarxPayInitiatePaymentOptions(
        trId: $order->marxpay_tr_id,
        merchantRid: $order->merchant_rid,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    ));

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

const payment = await client.payment().marxpay().initiatePayment(
  new MarxPayInitiatePaymentOptions({
    trId: verifiedReturn.trId,
    merchantRid: verifiedReturn.merchantRid,
  }),
);

Retrieve an order summary

Use this read-only function to retrieve the current safe summary for the same transaction. It validates that the returned provider data belongs to the supplied merchantRid and trId before mapping the result.

PHP SDK
Laravel SDK
Node.js SDK

use Avraapi\Apix\Payments\GatewayEnvironment;

$summary = $apix->payment()
    ->marxpay()
    ->retrieveOrderSummary(
        trId: $order->marxpay_tr_id,
        merchantRid: $order->merchant_rid,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    );

SDK response — MarxPayPaymentResult:

{
  "merchant_rid": "ORDER-2026-000184",
  "tr_id": "MP-320000000000",
  "payment_status": "succeeded",
  "provider_status": "SUCCESS",
  "amount": "12000.00",
  "currency": "LKR",
  "payment_method": "OTHER",
  "expires_at": "2026-09-28T12:30:00+00:00",
  "request_id": "01j..."
}

This is a safe SDK projection. Raw MarxPay gateway and card data are intentionally not returned.

use Avraapi\Laravel\Facades\AvraAPI;

use Avraapi\Apix\Payments\GatewayEnvironment;

$summary = AvraAPI::payment()
    ->marxpay()
    ->retrieveOrderSummary(
        trId: $order->marxpay_tr_id,
        merchantRid: $order->merchant_rid,
        gatewayEnvironment: GatewayEnvironment::Sandbox,
    );

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

const summary = await client.payment().marxpay().retrieveOrderSummary(
  order.gatewayTransactionId,
  order.id,
  GatewayEnvironment.Sandbox,
);

Payment Elements

When server-side availability returns more than one enabled MarxPay tender, Payment Elements renders each one as a separate method card. Each card keeps gateway: 'marxpay' and mode: 'redirect', then sends the selected tender as providerOptions.payment_method to your backend.

elements.renderMethods('#payment-methods', {
  methods: [{
    gateway: 'marxpay',
    mode: 'redirect',
    label: 'Cards — USD',
    description: 'Visa, Mastercard, or UnionPay in USD.',
    providerOptions: { payment_method: 'OTHER_USD' },
  }],
});

For rendering, events, visual customization, and checkout lifecycle details, see More Payment Elements features.

Gateway-specific options

providerOptions.payment_method accepts only OTHER, AMEX, OTHER_USD, AMEX_USD, and PAY_BY_BANK_ACCOUNT.

OTHER and AMEX are LKR-only.
OTHER_USD and AMEX_USD are USD-only.
PAY_BY_BANK_ACCOUNT is available only if the connected MarxPay merchant account enables it.
Omitting the option defaults to OTHER for LKR and OTHER_USD for USD.

AvraAPI validates the tender against the order currency and enabled Gateway Vault payment methods. A browser selection never overrides that check.

Completion, webhooks, and safety

Even after a successful return binding or order-summary call, a browser return is not payment proof. Preserve the original server-only completion context and call common completePayment() for the final reconciliation and canonical payment result. Do not send merchantRID, trId, or summary data into client-controlled state.

​When to use MarxPay

​SDK Functions

​Verify a browser return

​Initiate a verified MarxPay payment

​Retrieve an order summary

​Payment Elements

​Gateway-specific options

​Completion, webhooks, and safety

When to use MarxPay

SDK Functions

Verify a browser return

Initiate a verified MarxPay payment

Retrieve an order summary

Payment Elements

Gateway-specific options

Completion, webhooks, and safety