Redirect After Payment

When you create a payment, the response contains a checkoutUrl — a hosted payment page where your customer completes the payment. By default, after the payment finishes the customer stays on that page. To bring the customer back to your site, append redirect parameters to the checkoutUrl before you send the customer to it. The hosted page reads them and redirects the customer to your success URL when the payment reaches SUCCESS, or to your failure URL when it becomes FAILED or EXPIRED.

Redirect parameters

Parameter	Type	Required	Notes
`rs`	string	No	Redirect on success. Base64-encoded absolute URL the customer is sent to when the payment succeeds.
`rf`	string	No	Redirect on failure. Base64-encoded absolute URL the customer is sent to when the payment fails or expires.
`ar`	string	No	Auto-redirect. Set to `true` (case-insensitive) to redirect automatically after a 10-second countdown. Any other value (or omitting it) shows a button the customer clicks to continue.

All three parameters are optional and independent — you can set only rs, only rf, or both. If a parameter is missing, the customer simply stays on the result screen for that outcome.

The redirect URLs must be base64-encoded (standard or URL-safe base64 both work; padding is optional) and must decode to an absolute http:// or https:// URL. A value that fails to decode, or decodes to anything other than an http(s) URL, is ignored and no redirect is offered.

The customer is redirected to your URL exactly as you provided it — no query parameters are appended by the payment page. Include everything you need to identify the payment (for example your orderId) in the URL before encoding it. Never treat the redirect itself as proof of payment; always confirm the final status via webhook or the payment status API.

How it looks to the customer

ar=true — after the payment resolves, the result screen shows a 10-second countdown ring with a “redirect now” button. When the countdown reaches zero (or the customer clicks the button), the browser navigates to your URL.
ar omitted — the result screen shows a button; the customer is redirected only when they click it.

End-to-end example

The snippet below runs on your backend — the API key must never reach the browser. It creates the payment, takes checkoutUrl from the response, and attaches the redirect parameters.

// Encode a redirect URL as URL-safe base64 (Node.js 16+).
// In other runtimes, any base64 encoder works — the payment page
// accepts standard and URL-safe base64, with or without padding.
function encodeRedirectUrl(url: string): string {
  return Buffer.from(url, "utf8").toString("base64url");
}

interface CreatePaymentResponse {
  success: boolean;
  data: {
    orderId: string;
    checkoutUrl: string;
    qrPayload: string;
    playerId: string;
    totalAmount: number;
    // Normally PENDING. A payment that already completed (for example
    // a duplicate create request) returns its final status instead,
    // and the response carries no qrPayload.
    status: "PENDING" | "SUCCESS" | "EXPIRED" | "FAILED";
  };
}

async function createCheckoutUrl(): Promise<string> {
  // 1. Create the payment.
  const response = await fetch("https://live.launcx.com/api/v1/payments", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.LAUNCX_API_KEY!,
      "x-timestamp": Date.now().toString(),
    },
    body: JSON.stringify({
      price: 15000,
      playerId: "payer_id",
    }),
  });

  if (!response.ok) {
    throw new Error(`Create payment failed: ${response.status}`);
  }

  const payment: CreatePaymentResponse = await response.json();
  const { orderId, checkoutUrl } = payment.data;

  // 2. Build the redirect URLs. Embed your own order reference —
  //    the payment page redirects to these URLs verbatim.
  const successUrl = `https://merchant.example.com/checkout/success?orderId=${orderId}`;
  const failureUrl = `https://merchant.example.com/checkout/failed?orderId=${orderId}`;

  // 3. Attach the redirect parameters to the checkout URL.
  const checkout = new URL(checkoutUrl);
  checkout.searchParams.set("rs", encodeRedirectUrl(successUrl));
  checkout.searchParams.set("rf", encodeRedirectUrl(failureUrl));
  checkout.searchParams.set("ar", "true"); // auto-redirect after 10s

  return checkout.toString();
}

Hand the finished URL to the browser — respond with a 302 to it, or return it from your route and navigate client-side:

// In the browser:
const { checkoutUrl } = await fetch("/api/checkout", { method: "POST" }).then((r) => r.json());
window.location.assign(checkoutUrl);

A finished checkout URL looks like this:

https://live.launcx.com/external/payments/b36e39bc-c5fb-4c32-ab46-7260e14d1881/receive?rs=aHR0cHM6Ly9tZXJjaGFudC5leGFtcGxlLmNvbS9jaGVja291dC9zdWNjZXNzP29yZGVySWQ9YjM2ZTM5YmMtYzVmYi00YzMyLWFiNDYtNzI2MGUxNGQxODgx&rf=aHR0cHM6Ly9tZXJjaGFudC5leGFtcGxlLmNvbS9jaGVja291dC9mYWlsZWQ_b3JkZXJJZD1iMzZlMzliYy1jNWZiLTRjMzItYWI0Ni03MjYwZTE0ZDE4ODE&ar=true

Handling the customer’s return

When the customer lands back on your site:

Read your order reference from the URL you constructed (e.g. orderId).
Look up the payment’s final status on your backend — via the webhook notification you received, or by querying the payment status API.
Render your own success or failure page based on that verified status.

Redirect URLs are visible to the customer and can be opened directly, so your success page must not fulfill an order on its own. Fulfillment should only ever be driven by the verified payment status.

Getting Started

Payments

Disbursements

Migration

Wallets

Redirect After Payment

Redirect parameters

How it looks to the customer

End-to-end example

Handling the customer’s return

​Redirect parameters

​How it looks to the customer

​End-to-end example

​Handling the customer’s return

Redirect parameters

How it looks to the customer

End-to-end example

Handling the customer’s return