Payments and refunds
List gateways, create a hosted checkout, open it, confirm the result and refund.
All functions return a WP_Error on failure. See error codes.
List gateways
$gateways = paylexer_get_gateways( array( 'currency' => 'USD' ) );
Returns the gateways the merchant enabled for this site that are open for checkout. Each entry:
| Key | Example |
|---|---|
code | stripe (pass it to paylexer_create_checkout) |
name, label, description, icon | display fields |
currencies | ["USD","EUR"]; empty means any |
supports | subscriptions, trial, sign_up_fee, refunds, partial_refunds |
Filters: currency, subscriptions (only gateways that support them), test_mode (include gateways whose live verification failed).
Full reference: Get gateways.
Create a checkout
$checkout = paylexer_create_checkout( 'acme-bookings', $order );
| Field | Required | Notes |
|---|---|---|
gateway | yes | A code from paylexer_get_gateways(). |
amount | yes | Major units, above zero. |
currency | yes | Must be accepted by the gateway. |
customer.email | yes | Also first_name, last_name, phone, address. Some gateways require a billing address. |
return_url | yes | Where the shopper lands after paying. |
cancel_url | Defaults to return_url. | |
reference | Your order ID, shown in the PayLexer dashboard. | |
description | Line name when you pass no items. | |
items | [{ name, unit_amount, quantity?, id?, description?, metadata? }]. Without items, one line covers the amount. | |
metadata | Passed to the gateway session. | |
test_mode | true uses the gateways' sandbox. | |
merchant_name, theme_color | Hosted page branding. Defaults: site name, white. | |
order_url | Your page for this order on this site, e.g. its admin edit screen. The PayLexer dashboard links the order's Purchase ID to it. URLs on other sites are ignored. |
The website and your platform ID are added by the PayLexer plugin. You can't set them.
Returns:
array(
'platform' => 'acme-bookings',
'order_reference' => 'ORD-ADF79AA433405B80', // save it on your order
'checkout_url' => 'https://…',
'checkout' => 'redirect', // 'redirect' or 'modal': PayLexer's decision for this gateway
'status_token' => '…', // lets the browser check this order's status
'return_url' => 'https://…',
'cancel_url' => 'https://…',
)
Full reference: Create checkout.
Open the checkout
Load the script once per page:
$handle = paylexer_enqueue_checkout();
wp_enqueue_script( 'acme-checkout', $url, array( $handle ) );
Hand it the whole array from paylexer_create_checkout() (or paylexer_create_subscription()), as JSON:
const result = await PayLexer.openCheckout(checkout, {
onSuccess(r) {}, onCancel() {}, onError(e) {}, onPending(r) {},
});
// result.result is "success" | "cancel" | "error" | "pending"
How the checkout opens is not your choice. PayLexer decides per gateway, from its own configuration: some gateways only work as a full-page redirect, others in the in-page modal, and some need a signed form POST. openCheckout() follows checkout.checkout (and form_post when present).
For a redirect, the shopper comes back to your return_url (paid) or cancel_url. PayLexer may append paylexer_status=failed when the gateway reports a failure.
With no onSuccess, a payment confirmed in the modal goes to return_url. A result the browser can't confirm (a subscription has no status_token) goes to onPending, never onSuccess.
Don't fulfil orders from the browser. Before onSuccess runs, the script asks your server, which asks the gateway, whether the order is paid. Even so, mark orders paid only in the payment_completed webhook.
Full reference: Open checkout.
Check payment status
$status = paylexer_get_payment_status( 'acme-bookings', $order_reference );
// array( 'status' => 'COMPLETED', 'paid' => true, 'live_status' => 'succeeded', 'amount' => 120.0, 'currency' => 'USD', … )
PayLexer re-checks the gateway on every call. paid is true for COMPLETED, PARTIALLY_REFUNDED and REFUNDED, and also when the gateway itself reports succeeded (live_status) before PayLexer has processed its webhook, as long as the amount the gateway reports charged covers the order total.
In that window status is still PENDING, and refunds are refused until it moves on.
List your orders
$orders = paylexer_get_orders( 'acme-bookings', array( 'limit' => 20, 'with_status' => true ) );
// array( array( 'reference' => 'ORD-…', 'type' => 'order', 'created_at' => '2026-10-01 09:56:24', 'status' => array( … ) ), … )
Newest first, only orders your platform created. Pass type => 'subscription' for subscriptions, plus offset for paging. with_status fetches each order's live status (one gateway re-check per order), so it caps limit at 20. There's deliberately no way to list the site's other orders or customers.
Refund
Declare refunds when you register.
paylexer_refund( 'acme-bookings', $order_reference ); // full
paylexer_refund( 'acme-bookings', $order_reference, 20.00, 'Late' ); // partial, major units
The gateway confirms the refund later through paylexer_platform_{id}_payment_refunded. PayLexer refuses orders that aren't paid, gateways without refund support, and amounts above what's left to refund. The error message says which.