WallexPay Integration Documentation

WallexPay is an on-chain payments rail for WALXUSD, built for merchants, SaaS, hosting, exchanges, and Web3-native apps. One URL redirect. One transaction. Instant, non-custodial settlement with a transparent 1% fee.

Instant Finality

No chargebacks, no rolling reserves. Every payment is final on BSC.

Borderless Stable Unit

Accept WALXUSD globally with consistent value.

Non-Custodial

Funds route directly: user → contract → merchant.

1. Overview

WallexPay is a lightweight payment layer:

Merchants integrate once using a simple redirect URL.
Customers pay using their wallet at pay.wallex.ws.
Smart contract takes 1% fee, forwards 99% of WALXUSD to the merchant.
Merchants receive on-chain proof via PaymentProcessed events + optional webhooks.

2. Payment Flow

Step 1: Create Order

Your backend generates an internal orderId and amount in WALXUSD.

Step 2: Redirect

Redirect user to WallexPay with query params: merchant, merchantAddress, amount, orderId, callback.

Step 3: On-chain Pay

User confirms transaction. WallexPayProcessor pulls WALXUSD, routes net to merchant, emits event.

Step 4: Confirm

Your backend verifies via webhook or chain event → marks order as PAID.

3. Integration Guide

Step 1 — Register Merchant

Go to the WallexPay Merchant Dashboard: /merchant
Connect your wallet (this becomes your payout address).
Set your Webhook URL (optional but recommended).
If merchant whitelisting is enabled, your wallet must be approved by Wallex.

Step 2 — Redirect to WallexPay

From your checkout (WHMCS, WooCommerce, custom app), redirect to:

https://pay.wallex.ws/pay?merchant=YourShop &merchantAddress=0xYourMerchantWallet &amount=25.50 &orderId=ORDER-12345 &callback=https://yourstore.com/api/wallexpay/webhook

orderId should be unique per order. Use your own format; WallexPay will echo it back via events/webhook.

Step 3 — Confirm on Backend

On successful payment, WallexPay:

Emits PaymentProcessed on 0xC5d69371EE104f64cC83AB753873CDaCdf125EfA.
Optionally POSTs JSON to your callback / webhook URL.
You match orderId/paymentId, verify netAmount, then mark order as PAID.

Example: Validate Webhook Payload (pseudo-code)

1. Receive JSON:
   { paymentId, merchant, amount, netAmount, token, txHash, orderId }

2. Check:
   - merchant == your configured wallet
   - token == WALXUSD
   - netAmount matches expected price
   - txHash exists on-chain and logs PaymentProcessed with same values

3. If all good:
   - Mark orderId as PAID in your system.

4. Webhooks & On-Chain Events

Webhook Payload (Example)

{
  "paymentId": "0xabc123...",
  "orderId": "ORDER-12345",
  "payer": "0xUser...",
  "merchant": "0xYourMerchantWallet",
  "token": "0x25d697B574068f84fd2b7B5ef3f45287F43CD4C2",
  "amount": "25.50",
  "feeAmount": "0.25",
  "netAmount": "25.25",
  "timestamp": 1731139800,
  "txHash": "0xTransactionHash"
}

On-Chain Event: PaymentProcessed

event PaymentProcessed(
  bytes32 indexed paymentId,
  address indexed payer,
  address indexed merchant,
  address token,
  uint256 amount,
  uint256 feeAmount,
  uint256 netAmount,
  uint256 timestamp
);

You can consume this event directly using ethers.js in your backend indexer if you prefer on-chain verification over webhooks.

5. Security & Guarantees

Non-Custodial by Design

WallexPay never holds your private keys.
Payments are executed via smart contracts on BSC.
1% fee is enforced in contract; no hidden spreads.
Merchant whitelisting (if enabled) prevents spoofed receivers.

6. FAQ

Is WallexPay custodial?

No. Funds go directly from customer to merchant wallet (minus the 1% protocol fee).

How do I issue refunds?

Refunds are handled manually by the merchant sending WALXUSD back to the customer. WallexPay does not reverse transactions.

Can I use WallexPay with WHMCS / WooCommerce / custom apps?

Yes. Any system that can redirect to a URL and receive a webhook can integrate WallexPay.

Ready to go live?

Connect your wallet on the Merchant Dashboard and plug the redirect URL into your checkout.

Open Merchant Dashboard