Gateway API

Overview

The backend is Django. It exposes three separate planes, all mounted under /api/ by PaymentProvider/urls.py:

Inbound PSP webhooks land on /api/webhooks/<psp_name>, and the Django admin is at /admin/.

Authentication

Signing up in the dashboard mints two secrets with different powers. Keeping them apart is the whole security model — and it is why there is no way to mint them over the API:

Both header forms work:

X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxx
# — or —
Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxx

A missing, unknown or non-ACTIVE key returns 401 {"error": "invalid or missing API key"}.

Two-factor authentication

Turn on TOTP — Google Authenticator, Authy, 1Password, any of them — from Settings → Two-factor authentication in the dashboard. Enabling it needs a code from the app before it takes effect, so an unfinished setup can never lock you out, and it issues ten single-use backup codes shown exactly once. They are stored hashed: nobody, including us, can read them back to you later.

If you drive the dashboard API directly, note that POST /api/auth/login answers a 2FA account with {"mfaRequired": true, "mfaToken": "…"} and no token pair. Post that token with a code to POST /api/auth/mfa/verify to get the session. The challenge token authorises nothing on its own, expires in five minutes, and stops working if the account password changes underneath it.

The Python client

Every example below uses sdk/xlopay.py from this repository. It needs only requests. One named method per endpoint — there is no raw get/post escape hatch, because a caller that hand-builds paths gets to hand-build the auth too, and that is how an skKey ends up on a request that had no business carrying one.

import os
from xlopay import XloPay, GatewayError

gw = XloPay(
    api_key=os.environ["XLOPAY_API_KEY"],
    sk_key=os.environ.get("XLOPAY_SK_KEY", ""),   # wallet key, optional
    base_url="https://api.xlopay.me",
)

try:
    currencies = gw.list_currencies()
except GatewayError as e:
    # e.status is None when the gateway was never reached (DNS, TLS, timeout).
    # That distinction matters: "refused" is final, "not reached" is unknown.
    print(e.status, e.body)

Getting your keys

You get two keys, and they are not interchangeable:

If saveKeyEnabled is on for your account, the endpoints that need sk_live fall back to the stored copy when you omit it — with one deliberate exception, see withdrawals.

Verifying a key

me = gw.get_account()
print(me["name"], me["apiKeyPrefix"], me["saveKeyEnabled"])

Currencies & wallets

The authoritative set of chain / quoteCurrency pairs you may pass to GeneratePayment. Only tokens enabled for your account appear; a native coin maps to an empty address.

currencies = gw.list_currencies()

for chain, tokens in currencies.items():
    for symbol, contract in tokens.items():
        print(f"{chain:5} {symbol:6} {contract or '(native)'}")

Response · 200

{
  "ETH": {"USDC": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "USDT": "0xdac17f958d2ee523a2206206994597c13d831ec7"},
  "BSC": {"USDC": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
          "USDT": "0x55d398326f99059ff775485246999027b3197955"},
  "SOL": {"USDC": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "USDT": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"},
  "BTC": {"BTC": ""}
}

wallets = gw.list_wallets()

# A standalone hot wallet, outside the payment flow.
hot = gw.create_one_time_wallet(chain="BSC", label="invoice-8841")   # needs sk_live
print(hot["address"], hot["hexId"])

Generate a payment

Quotes a USD stable currency amount for a USD value, mints a dedicated one-time wallet, and returns the address the payer must fund. The quote is the requested amount plus your platform fee, converted at the current price and rounded up to the token's precision so it is never short.

payment = gw.create_payment(          # needs sk_live
    amount=49.00,
    quote_currency="USDT",
    chain="BSC",
    uid="order-1001",
)

print("Send exactly", payment["payAmount"], payment["quoteCurrency"])
print("To address  ", payment["address"])
print("Expires     ", payment["dateExpired"])

# Persist these two against your order — they are how you reconcile later.
order.payment_hex_id = payment["hexId"]
order.wallet_hex_id  = payment["walletHexId"]

Response · 201

{
  "hexId": "b86a10a2dc",
  "walletHexId": "ff599af979",
  "address": "0x6CF6716F27057F87d91Ee20fF0c5f39C220Dc271",
  "uid": "order-1001",
  "chain": "BSC",
  "priceCurrency": "USD",
  "quoteCurrency": "USDT",
  "amountRequested": "49.00",
  "payAmount": "49.000000000000000000",
  "payAmountUsd": "49.00",
  "totalReceived": "0E-18",
  "status": "pending",
  "dateCreated": "2026-07-25T22:51:47.938179+00:00",
  "dateExpired": "2026-07-26T02:51:47.938179+00:00",
  "datePaid": null
}

The one-time wallet expires after ONE_TIME_WALLET_TTL_HOURS (default 4 hours). Late funds are still credited, but the quote may have moved by then.

Payment status

GET by payment id returns the same shape as GeneratePayment. POST /status takes a walletHexId and adds the individual on-chain deposits, with live confirmation counts.

from decimal import Decimal

status = gw.get_payment_status(order.wallet_hex_id)

received = Decimal(status["totalReceived"])
required = Decimal(status["payAmount"])

print(f"{status['status']}: {received} / {required} {status['quoteCurrency']}")

for tx in status["txs"]:
    print(f"  {tx['txHash'][:16]}… {tx['amount']} "
          f"({tx['confirmations']}/{tx['requiredConfirmations']} confs)")

Response · 200

{
  "walletHexId": "ff599af979",
  "paymentId": "b86a10a2dc",
  "status": "pending",
  "quoteCurrency": "USDT",
  "payAmount": "49.000000000000000000",
  "totalReceived": "0E-18",
  "txs": []
}

Payment statuses

Polling as a fallback

import time
from decimal import Decimal

def await_payment(gw, wallet_hex_id, *, timeout_s=3600, interval_s=15):
    """Block until a payment settles. Returns the final status payload."""
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        s = gw.get_payment_status(wallet_hex_id)
        if s["status"] in ("paid", "expired", "cancelled"):
            return s
        time.sleep(interval_s)
        interval_s = min(interval_s * 1.5, 120)   # back off
    raise TimeoutError(f"payment {wallet_hex_id} did not settle in {timeout_s}s")

Withdrawals

Accepted work returns 202 — the transaction is signed and broadcast by a background worker, so poll GET /api/v1/withdrawals or wait for the webhook for the final on-chain result.

# Sweep the full balance to your configured withdrawable address.
# Omitting `destination` is the safe path — it needs no explicit sk_live.
job = gw.create_withdrawal(            # needs sk_live
    chain="BSC",
    token="USDT",
    # amount_usd=250.00,      # omit to withdraw everything
)
print(job)   # 202 Accepted — a summary of the queued payout

Payment users

A payment user is one of your customers, held on our side. It is the identity both halves of the gateway hang off: it owns a derived USD stable currency deposit address on every chain, and it owns vaulted cards. That is what makes "this customer's saved payment methods" a real thing rather than a merchant-wide pool.

Four identifiers address the same user. Pass whichever you have as identifier in the request body — never in the URL.

Create a user

CreateUser(user_id) in its smallest form. Supply any one of userId, email or username — a missing username is derived from the id you gave. Deposit addresses on every chain are minted in the same call, which is why sk_live is required (they are derived from your seed).

# The minimal form — just your own user id.
user = gw.create_user(external_id="cust-9001")   # needs sk_live

# …or with a full profile.
user = gw.create_user(
    external_id="cust-9001",
    email="ada@acme.test",
    first_name="Ada", last_name="Lovelace",
    country="gb",
    metadata={"tier": "gold", "signupSource": "ios"},
)

for w in user["wallets"]:
    print(w["chain"], w["address"])

Response · 201

{
  "id": "1",
  "hexId": "a3f19c2b04",          // ours, always present
  "merchantId": "1",
  "username": "cust-9001",          // derived from userId
  "externalId": "cust-9001",
  "email": "ada@acme.test",
  "phone": "",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "country": "GB",
  "status": "active",
  "metadata": {"tier": "gold"},
  "userIndex": 2,
  "balanceUsd": 0.0,
  "createdAt": "2026-07-25T23:30:46.566542Z",
  "updatedAt": "2026-07-25T23:30:46.575188Z",
  "lastSeenAt": null,
  "wallets": [
    {"hexId": "496f29b4a2", "chain": "BSC",
     "address": "0x5218d7a0ab99A646c29cdBE40b0363699Ca26Be4",
     "derivationPath": "m/44'/60'/0'/0/2", "endUserId": "1"}
    /* … one per chain … */
  ]
}

A duplicate userId is rejected with 400. Users created without one do not collide — the uniqueness constraint applies only when the field is set.

Look a user up

# All three of these return the same user.
gw.get_user("cust-9001")        # by your id
gw.get_user("ada@acme.test")    # by email
gw.get_user("sevenup")          # by username

# Editing a profile needs no sk_live — it derives nothing.
gw.update_user("cust-9001", first_name="Grace")

# Block a user: no new checkout sessions, no charges. Deposits still credit.
gw.update_user("cust-9001", status="blocked")

# Fuzzy search across id / email / username / name.
for u in gw.list_users(search="acme"):
    print(u["externalId"], u["email"], u["status"])

Their deposit addresses

The user plus every derived deposit address, both as a flat list and keyed by chain — which is what "where do I send USDT on BSC for this customer" actually needs.

w = gw.get_user_wallets("cust-9001")

print(w["user"]["firstName"])
print(w["byChain"]["BSC"])       # 0x5218d7a0ab99A646c29cdBE40b0363699Ca26Be4

for addr in w["addresses"]:
    print(addr["chain"], addr["address"], addr["hexId"])

Response · 200

{
  "user": { /* the user object, without the wallets array */ },
  "addresses": [ /* full wallet objects, one per chain */ ],
  "byChain": {
    "BSC": "0x5218d7a0ab99A646c29cdBE40b0363699Ca26Be4",
    "ETH": "0x5218d7a0ab99A646c29cdBE40b0363699Ca26Be4",
    "SOL": "6Xy…",
    "BTC": "bc1q6mkhklyl0cx0n3q60383znnp7uptj2ldy7m2fq"
  }
}

Their saved cards

wallet = gw.list_user_cards("cust-9001")

for c in wallet["cards"]:
    print(f"{c['brand']} ••••{c['last4']} exp {c['expMonth']}/{c['expYear']}")

To vault a card against a user directly, pass userId to POST /api/v1/psp/cards. Cards created without a userId stay merchant-level, exactly as before.

Card providers

The catalogue of connectable providers and the credential fields each one needs.

for p in gw.list_psp_providers():
    if p["hidden"]:          # the generic "webhook" escape hatch
        continue
    required = [f["key"] for f in p["fields"] if f["required"]]
    print(f"{p['label']:12} needs {required}")

Connect a PSP

priority is the fallback order — lower runs first. Credentials are encrypted at rest and are write-only: reads report hasCredentials and never the values.

# Primary processor.
gw.connect_psp(
    provider="stripe", psp_name="Stripe",
    priority=1, active=True,
    credentials={
        "secretKey": os.environ["STRIPE_SECRET_KEY"],
        "webhookSecret": os.environ["STRIPE_WEBHOOK_SECRET"],
    },
)

# Fallback, tried only when the primary declines synchronously.
gw.connect_psp(
    provider="payit", psp_name="PayIt",
    priority=2, active=True,
    credentials={
        "bearerToken": os.environ["PAYIT_TOKEN"],
        "clientSlug": "acme",
        "descriptor": "ACME LTD",
    },
)

for cfg in gw.list_psp_configs():
    print(cfg["priority"], cfg["providerLabel"],
          "active" if cfg["active"] else "paused",
          "creds✓" if cfg["hasCredentials"] else "creds✗")

The unified charge

One card payload, routed through your connected PSPs in priority order. It falls through to the next provider only on a synchronous decline — and only if more than one PSP is connected. Every attempt is recorded on the charge.

result = gw.charge_card(
    amount_usd=49.00,
    currency="USD",
    invoice_number="order-1001",

    # Card
    card_number="4111111111111111",
    exp_month="12",
    exp_year="2030",
    cvv="123",

    # Billing profile — several PSPs decline without it
    first_name="Ada",   last_name="Lovelace",
    email="ada@acme.test", phone="+15551234567",
    street1="1 Analytical Way", city="London",
    state="LDN", country="GB", postal_code="EC1A",

    # Who is paying — your own id, an email or a username. Optional:
    # an unknown one creates the user, and sending none at all still
    # resolves or creates one. See the callout below.
    user_id="cust-8814",

    return_url="https://acme.test/thanks",
)

if result["status"] == "succeeded":
    fulfil(result["invoiceNumber"], psp=result["pspName"])

elif result["status"] == "pending":
    # 3-DS: send the shopper to the bank, settle on the webhook.
    redirect_to(result["redirectUrl"])

else:
    for a in result["attempts"]:
        print(f"{a['pspName']}: {a['status']} {a['errorCode']} {a['errorMessage']}")

Error response · 422 (verified)

{"error": "no active PSPs connected — connect a provider first"}

{"status": "succeeded",
 "endUser": {"hexId": "a3f19c2b04", "externalId": "cust-8814",
              "email": "ada@acme.test", "username": "cust-8814", "id": "12"},
 …}

Card vault

Store a card once, charge it later by token. Reads never return the PAN, the CVV or the sealed blob — only brand, last 4 and expiry.

vault = gw.list_cards()
if not vault["vaultConfigured"]:
    raise RuntimeError("card vault keys are not deployed")

# Save at charge time…
paid = gw.charge_card(
    amount_usd=49.00, card_number="4111111111111111",
    exp_month="12", exp_year="2030", cvv="123",
    first_name="Ada", last_name="Lovelace",
    email="ada@acme.test",
    save_card=True, card_label="Ada — personal Visa",
)
token = paid["savedCard"]["token"]

# …then charge on file later, with no card data in the request.
gw.charge_card(
    amount_usd=49.00,
    saved_card_token=token,
    invoice_number="order-1002",
)

Hosted checkout (the iframe)

Implemented end to end — backend sessions, the public pay endpoints, the React checkout page and the dashboard snippet generator are all present and wired together, with the xlopay Node SDK as the supported way to embed it.

The design goal is that the merchant page holds no secret and no amount. The session fixes the amount server-side and can be paid at most once, so the only thing in the browser is a session id.

1. Your server creates a session POST /api/v1/psp/checkout-sessions with your API key. The amount is fixed here and cannot be altered from the browser.
2. Your page embeds the iframe with mountCheckout, or by hand from the returned embedPath.
3. The iframe loads the session GET /api/psp/checkout-sessions/<id> — a display-only view: amount, currency, reference, merchant name. No secrets.
4. The payer submits their card POST /api/psp/checkout-sessions/<id>/pay, rate-limited to 20 attempts per 10 minutes per IP as a card-testing guard.
5. It routes through your PSP chain exactly like the unified charge — same fallback, same attempt trail.
6. Terminal state Success marks the session paid and shows a return link. A decline leaves it open so the payer can try another card. 3-DS moves it to pending_auth with a verification link.

GeneratePaymentLink

Pass a userId and the checkout becomes personal: that user's vaulted cards are pooled for selection, and they can add or remove cards in the frame. Omit it and you get a guest checkout — raw card entry, exactly as before.

link = gw.create_payment_link(
    user_id="cust-9001",
    amount_usd=49.00,
    currency="USD",
    uid="order-1001",
    tracking_id="trk-77",
    reference="inv-9",
    return_url="https://acme.test/thanks",
    expires_in_minutes=15,
    theme={"primary": "#10b981", "buttonLabel": "Top up"},
)

print(link["embedUrl"])     # ready to drop straight into an iframe
order.checkout_session_id = link["sessionId"]

Response · 201 (verified)

{
  "sessionId": "cs_db082a2ca5e4b6b0c751e8e1cabd8b7304d6",
  "merchantId": "1",
  "userId": "1",
  "externalUserId": "cust-9001",
  "amountUsd": 49.0,
  "currency": "USD",
  "reference": "inv-9",
  "uid": "order-1001",
  "trackingId": "trk-77",
  "metadata": {},
  "theme": {"primary": "#10b981", "buttonLabel": "Top up"},
  "allowSaveCard": true,
  "allowCardManagement": true,
  "returnUrl": "https://acme.test/thanks",
  "status": "pending",
  "embedPath": "/embed/checkout?session=cs_db082a2ca5e4b6b0c751e8e1cabd8b7304d6",
  "embedUrl": "https://xlopay.me/embed/checkout?session=cs_db082a2…",
  "expiresAt": "2026-07-25T23:45:59.736684Z",
  "createdAt": "2026-07-25T23:30:59.736684Z"
}

POST /api/v1/psp/checkout-sessions is the original name for this same endpoint and still behaves exactly as it always did — existing integrations need no change.

Embedding it

<iframe src="https://xlopay.me/embed/checkout?session=cs_31f7908ebd…"
        width="440" height="640" frameborder="0"
        style="border:0;max-width:100%"></iframe>

Generating that markup server-side:

from html import escape

def checkout_iframe(gw, *, amount, reference, return_url,
                    frontend="https://xlopay.me", width=440, height=640):
    """Create a session and return ready-to-render iframe markup."""
    s = gw.create_payment_link(
        amount_usd=str(amount),
        currency="USD",
        reference=reference,
        return_url=return_url,
    )
    url = escape(frontend + s["embedPath"], quote=True)
    return s["sessionId"], (
        f'<iframe src="{url}" width="{width}" height="{height}" '
        f'frameborder="0" style="border:0;max-width:100%"></iframe>'
    )


session_id, markup = checkout_iframe(
    gw, amount="49.00", reference="order-1001",
    return_url="https://acme.test/thanks")

# Store session_id against the order so the webhook can reconcile it.
order.checkout_session_id = session_id

# 1. Your server, with the Python SDK.  
link = gw.create_payment_link(
    amount_usd=49.00,
    user_id=user["hexId"],          # ours, opaque, always present
    allowed_origins=["https://acme.test"],
)

# 2. Your page, with the Node SDK.  
import { mountCheckout } from "xlopay"
mountCheckout({ container: "#checkout", sessionId: link.sessionId })

The xlopay Node SDK

TypeScript, zero dependencies, three ways in and four presentations. It exists because a bare <iframe src> cannot size itself, cannot tell you the payer finished, and cannot be restyled without minting a new session.

npm install xlopay

1 · Imperative

import { mountCheckout } from 'xlopay'

const checkout = mountCheckout({
    container: '#checkout',
    sessionId: link.sessionId,
    baseUrl: 'https://pay.xlopay.me',
    display: 'inline',                       // or 'modal' | 'drawer' | 'headless'

    // The checkout itself.
    theme: { primary: '#10b981', accent: '#0ea5e9', radius: 16, mode: 'dark' },

    // The frame around it.
    appearance: { radius: 20, shadow: true, maxWidth: 460 },

    onSuccess: () => location.assign('/thanks'),
    onPending: ({ redirectUrl }) => console.log('3-DS issued', redirectUrl),
    onFailure: () => console.log('declined - the frame stays open for another card'),
})

checkout.open()    // modal / drawer
checkout.close()
checkout.destroy()

2 · Declarative — the embed tag

For templates that have nowhere to put JavaScript: a CMS block, a Rails view, a plain HTML page. Every option is an attribute, and they are live — change theme-primary and it restyles; add or remove open and a modal shows or hides.

<script type="module" src="/vendor/xlopay/index.js"></script>

<xlopay-checkout
    session-id="cs_db082a2c..."
    base-url="https://pay.xlopay.me"
    display="modal"
    theme-primary="#10b981"
    theme-mode="dark"
    max-width="460"
></xlopay-checkout>

Events bubble as CustomEvents — xlopay:success, xlopay:pending, xlopay:failure, xlopay:ready, xlopay:error, xlopay:close — so any framework binds them the way it binds anything else.

3 · Headless

mountCheckout({ sessionId, display: 'headless' })

No DOM at all. The plumbing without the widget, for a UI you are building yourself.

Presentations

theme vs appearance

theme styles the checkout: primary, accent, gradient, radius, mode, locale. appearance styles the frame and its surroundings: radius, shadow, maxWidth, center, background, overlay, side, hideLoader, className. Two questions, two objects.

Customising the checkout

The theme object is stored on the session, server-side — never read from the URL. That matters: a query-string theme is rewritable by anyone holding the link, so a phishing frame could restyle your checkout at will. Unknown keys and malformed values are dropped on write, so the blob can never carry markup.

gw.create_payment_link(
    user_id="cust-9001",
    amount_usd=49.00,
    theme={
        "primary": "#10b981",
        "accent": "#0ea5e9",
        "radius": "16px",
        "mode": "dark",
        "logoUrl": "https://acme.test/logo.svg",
        "buttonLabel": "Top up",
        "merchantLabel": "Acme Store",
        "locale": "en-GB",
    },
)

Saved cards inside the iframe

When the session names a user, the public session view carries their card list and the frame renders a picker. The payer can pay with a stored card, enter a new one, tick "save this card", or remove one.

These are driven by the frame itself; you rarely call them server-side. Paying uses the same /pay endpoint with a savedCardToken instead of card fields:

# What the iframe posts when the payer picks a stored card.
requests.post(f"{BASE}/api/psp/checkout-sessions/{session_id}/pay",
              json={"savedCardToken": "card_87be44144c689d4b…"})

# …and when they enter a new card and tick "save this card".
requests.post(f"{BASE}/api/psp/checkout-sessions/{session_id}/pay",
              json={"cardNumber": "4242…", "expMonth": "12",
                    "expYear": "2030", "cvv": "123",
                    "saveCard": True})

Confirming the result server-side

import requests

def session_state(session_id, base="https://api.xlopay.me"):
    """Public display view — safe to poll, exposes no secrets."""
    r = requests.get(f"{base}/api/psp/checkout-sessions/{session_id}", timeout=15)
    r.raise_for_status()
    return r.json()

state = session_state(order.checkout_session_id)
if state["status"] == "paid":
    fulfil(order)

Response · 200

{
  "sessionId": "cs_31f7908ebd14b22bd9dee99de9602bb5f39c",
  "amountUsd": 49.0,
  "currency": "USD",
  "reference": "order-1001",
  "merchantName": "Acme",
  "status": "pending",
  "returnUrl": "https://acme.test/thanks",
  "open": true
}

Session statuses

What the iframe does and does not do

Two webhook families

This gateway sends you two kinds of event, and since 2026-07 they go to two separate endpoints. They are split because they are different data handled by different code on your side: a settlement deposit credits a wallet, a card outcome closes an invoice. One endpoint receiving both forced every integration to branch on the shape of the payload to find out which had arrived.

Deduplicate on eventId

# Django, and the shape ports to anything with transactions
event = Webhook(request.body, "crypto", verify_with=KEY,
                signature=request.headers.get("X-Gateway-Signature"))

with transaction.atomic():
    if Handled.objects.filter(event_id=event.event_id).exists():
        return HttpResponse(status=200)   # already done — ack, do nothing
    credit(event.amount_usd)
    Handled.objects.create(event_id=event.event_id)   # same commit
return HttpResponse(status=200)

Put a unique constraint on the column. It is what makes two deliveries arriving at the same instant safe: both check, both pass, and exactly one insert survives — the loser's transaction unwinds, credit included.

Configuring both

# Set them independently. Omitting a field leaves it as it is, so setting
# one endpoint never silently wipes the other.
gw.set_webhook("https://acme.test/hooks/crypto")
gw.set_webhook(psp_url="https://acme.test/hooks/cards")

# Or both at once.
gw.set_webhook("https://acme.test/hooks/crypto",
               psp_url="https://acme.test/hooks/cards")

# An explicit empty string clears one.
gw.set_webhook(psp_url="")

Response · 200 — also what gw.get_webhook() returns

{
  "webhookUrl": "https://acme.test/hooks/crypto",
  "pspWebhookUrl": "https://acme.test/hooks/cards",
  "effective": {                       // where each family actually lands
    "crypto": "https://acme.test/hooks/crypto",
    "psp": "https://acme.test/hooks/cards"
  },
  "events": {
    "crypto": ["payment.confirmed", "payment.paid",
               "payment.underpaid", "withdrawal.sent"],
    "psp": ["payment.succeeded", "payment.failed", "payment.pending",
            "payment.updated", "refund.succeeded"]
  },
  "inbound": {                         // the OTHER direction — see below
    "pspCallbackUrl": "https://api.xlopay.me/api/webhooks/<pspName>/42",
    "direction": "your PSP → this gateway"
  },
  "signature": {
    "scheme": "HMAC_SHA256",
    "header": "X-Gateway-Signature",
    "message": "<raw request body>",
    "signingKey": "a3f1…"          // secret — store it like the API key
  },
  "toleranceSeconds": 300
}

USD stable currency webhooks

Delivered to webhookUrl, with kind: "crypto".

Payload · payment.confirmed

POST https://acme.test/hooks/crypto
Content-Type: application/json
X-Gateway-Event: payment.confirmed
X-Gateway-Kind: crypto
X-Gateway-Event-Id: 2060ff5a6e
X-Gateway-Timestamp: 1785107508
X-Gateway-Signature: 4b81…

{
  "type": "payment.confirmed",
  "kind": "crypto",
  "eventId": "2060ff5a6e",      // THIS DELIVERY — deduplicate on it
  "sentAt": 1785107508,
  "data": {
    "hexId": "a41f9c02de",          // THE transaction — reconcile on this
    "walletHexId": "ff599af979",    // which address was paid
    "endUserHexId": "a318827e67",   // which customer — null if not a user wallet
    "chain": "SOL",                 // ETH | BSC | SOL | BTC
    "txHash": "5xY9…",             // the chain's id, for explorers
    "token": "USDC",
    "amount": 25.0,                // token units
    "amountUsd": 25.0,
    "source": "ws"                  // ws | reconcile (SOL only)
  }
}

Payload · withdrawal.sent

{
  "type": "withdrawal.sent",
  "kind": "crypto",
  "sentAt": 1785107700,
  "data": {
    "batchId": "b-7f3c1a",        // THE handle here — a withdrawal is a batch
    "walletHexId": "ff599af979",    // the master wallet it left
    "chain": "ETH",                 // of legs, not one transaction row
    "token": "USDT",
    "txHash": "0x41d…",            // the payout leg
    "amountUsd": 480.25,           // NET — after both fees below
    "feeUsd": 4.80,                // platform fee
    "blockchainFeeUsd": 2.15,      // measured network cost
    "destination": "0xA1b2…"
  }
}

Payload · payment.paid / payment.underpaid

Both carry the same fields — the difference is only whether the quote has been met. Every amount is cumulative for the payment, not per transfer.

{
  "type": "payment.underpaid",
  "kind": "crypto",
  "eventId": "748d2812c6",
  "sentAt": 1785107900,
  "data": {
    "paymentId": "f8eb16ae3e",       // the payment link
    "uid": "order-4417",             // your own reference, echoed back
    "walletHexId": "2a9f907a1c",     // the deposit address we minted
    "status": "underpaid",
    "chain": "BSC",
    "quoteCurrency": "USDC",
    "amountRequested": "103.00",     // what you asked for, USD
    "payAmount": "103.0357534064",   // the quote, in the token
    "totalReceived": "3.0",          // arrived so far, IN THE TOKEN
    "totalReceivedUsd": "3.00",      // arrived so far, in USD ← credit on this
    "remaining": "100.0357534064",   // still outstanding, in the token
    "datePaid": null                 // set only once status is "paid"
  }
}

PSP (card) webhooks

Delivered to pspWebhookUrl, with kind: "psp". These are normalised — the gateway has already verified the provider's signature, re-confirmed the outcome with the provider over TLS, and reconciled it against your charge. You are receiving the settled truth, not a raw provider body.

type carries the provider's own vocabulary for those states (payment.succeeded, payment.failed, payment.pending, payment.updated, refund.succeeded). Match on status when you only care about the outcome — it is normalised across every provider, type is not.

Payload

POST https://acme.test/hooks/cards
Content-Type: application/json
X-Gateway-Event: payment.succeeded
X-Gateway-Kind: psp
X-Gateway-Event-Id: e22cc3aa3a
X-Gateway-Timestamp: 1785107801
X-Gateway-Signature: 7c1e…

{
  "type": "payment.succeeded",
  "kind": "psp",
  "sentAt": 1785107801,
  "data": {
    "chargeHexId": "47974b1165",    // THE payment — ours, opaque, stable
    "endUser": {                     // WHO PAID. null on pre-attribution rows
      "hexId": "a318827e67",        // key your records on this
      "username": "ada",
      "externalId": "cust-1",       // your own id for them, if you sent one
      "email": "ada@acme.test"
    },
    "eventType": "payment.succeeded",
    "status": "succeeded",        // succeeded | failed | pending
    "amountUsd": 49.99,
    "currency": "USD",
    "pspName": "payit",             // which provider took it
    "pspRef": "ch_3PXy…",          // the provider's own id
    "invoiceNumber": "INV-1001",   // YOUR order reference
    "cardLast4": "4242",
    "cardBrand": "visa",
    "metadata": {}                  // whatever you attached to the charge
  }
}

Verifying a delivery

Every delivery, both families, is signed with HMAC-SHA256 over the exact raw body, keyed on the signingKey from gw.get_webhook(). Fetch that key once and store it like the API key.

from xlopay import Webhook, WebhookError
from flask import Flask, request, abort

app = Flask(__name__)
SIGNING_KEY = os.environ["XLOPAY_WEBHOOK_KEY"]   # from gw.get_webhook()


@app.route("/hooks/cards", methods=["POST"])
def card_events():
    try:
        event = Webhook(
            request.data,                     # RAW bytes, not request.json
            "psp",
            verify_with=SIGNING_KEY,
            signature=request.headers.get("X-Gateway-Signature"),
        )
    except WebhookError:
        abort(400)                          # bad signature, stale, or wrong family

    if event.is_paid:
        fulfil(event.invoice_number)          # must be idempotent
    return "", 200

The Webhook class

Webhook(payload, type) turns a raw delivery into a typed object. payload may be a dict, a JSON string or raw bytes. type is "crypto" or "psp", and is optional — every delivery carries kind, so omitting it reads that instead. Passing it makes the expectation explicit and raises on a mismatch, which is what you want on an endpoint that should only ever see one family.

from xlopay import Webhook

# Crypto — the three ids first; they are what you reconcile on
e = Webhook(body, "crypto")
e.hex_id, e.wallet_hex_id, e.end_user_hex_id, e.batch_id
e.chain, e.tx_hash, e.token, e.amount, e.amount_usd
e.from_address, e.destination
e.is_deposit, e.is_outflow, e.is_withdrawal

# PSP — the payment, then who made it
p = Webhook(body, "psp")
p.charge_hex_id, p.invoice_number
p.end_user_hex_id            # the payer's handle, or None
p.end_user                   # {hexId, username, externalId, email}
p.status, p.amount_usd, p.currency, p.psp_name, p.psp_ref
p.card_last4, p.card_brand, p.metadata
p.is_paid, p.is_failed, p.is_pending

# Both
e.type          # "payment.confirmed"
e.kind          # "crypto"
e.sent_at       # unix seconds
e.age_seconds()          # for your own replay window
e.sent_at_datetime      # aware UTC datetime
e.data                  # the raw data dict, nothing dropped
e["amountUsd"]          # wire names still work
e.get("somethingNew")    # a field newer than your SDK
e.to_dict()              # the original envelope, unmodified

Unrecognised fields are never dropped — a provider adding one should not require an SDK release, so anything unmapped stays reachable through .data, event["wireName"] and .get().

Retries and redelivery

Any 2xx is success. Anything else, or a timeout, is a failure and is retried.

# Re-drive everything that gave up (last 100 deliveries are returned).
for d in gw.list_webhook_deliveries():
    if d["status"] == "FAILED":
        gw.resend_webhook_delivery(d["hexId"])

Inbound PSP callbacks

The opposite direction: where your PSP posts to this gateway. Not to be confused with pspWebhookUrl, which is where the gateway posts to you.

gw.get_webhook()["inbound"]["pspCallbackUrl"] returns the exact value to paste into your provider's dashboard. Charges created through this API already carry it as their statusUrl, so it only needs setting by hand for provider-initiated events — refunds, chargebacks, retries.

On arrival the gateway verifies the provider's signature, re-asks the provider over TLS whether the event really happened (a forged body cannot settle a charge — the amount and status acted on come back from the provider), reconciles any pending charge, and only then forwards the normalised event to your pspWebhookUrl.

Set webhookSecret on the PSP config wherever the provider supports it. Without one the delivery proves nothing about who sent it, and attribution falls back to the invoice number.

All endpoints

Every one is POST with a JSON body and an X-API-Key header. "key + sk" means the body must also carry skKey (or the account has a saved key on file). There is no GET on this plane and no public endpoint at all.

The payer-facing plane is separate and deliberately unchanged: the hosted-checkout routes under /api/psp/checkout-sessions/<sessionId> and the inbound PSP callback /api/webhooks/<pspName>/<merchantId>. A browser and a PSP hold no API key — the session id and the confirm-with-the-PSP re-query are the controls there instead.

Errors & limits

Rate limits