Back to home
Product · Architecture

How Paynexus fits into your system.
One layer between you and every payment provider.

Paynexus is a payment orchestration platform, not a PSP. We sit between your application and the 100+ payment providers you'd otherwise integrate one by one — giving you a single API surface, automatic failover, and full observability over every transaction.

Read the quickstart Talk to sales
The big picture

What Paynexus actually is.

Think of Paynexus as payment middleware. Your application never talks directly to a PSP. Instead, you talk to Paynexus, and Paynexus picks the best PSP, handles the integration, retries on failure, verifies callbacks, and gives you a unified view of every transaction in your business.

It's not a PSP. We don't process cards ourselves. We're the layer that makes working with PSPs — all of them, at the same time — tractable.

Architecture at a glance

Three tiers. One data flow.

Your systems are on the left, Paynexus in the middle, payment providers on the right. All traffic between them is HTTPS; callbacks from PSPs are HMAC-verified before they reach you.

Your Systems
Your Application Checkout, orders, customer accounts, ledger
PHP SDK (optional) Direct server-side access, framework-agnostic
Webhook handler Your endpoint receiving transaction events
HTTPS
REST / SDK
Paynexus Layer
REST API  ·  api.paynexus.io Smart Routing · Retry & Circuit Breaker · Idempotency · Callback Verification · Rate Limiting
Admin Cabinet Multi-tenant panel for routing rules, keys, monitoring
Sandbox Deterministic test environment, debug scenarios
HTTPS
Per-PSP protocol
Payment Providers
Piastrix live
Ampay live
Betterbro live
Unlimit live
Stripe
Adyen
Checkout.com
Worldpay
+ 92 more
Core components

What each piece does.

REST API

The primary interface. Language-agnostic. Every operation — deposits, withdrawals, status, balances, payway catalog — happens over JSON endpoints with idempotency keys, signed callbacks, and structured error envelopes. Most integrations never need anything else.

Admin Cabinet

Multi-tenant web panel built on Filament v3. Configure routing rules (per merchant, per country, per payway), issue API keys, monitor transactions in real time, replay failed webhooks, and manage team RBAC — all without deploying code.

PHP SDK

Framework-agnostic (PHP 7.4+). Spec-driven architecture — adding a new PSP is a PHP array file, not a refactor. Use it when you need direct PSP access outside the REST API, or when you want to package a custom provider.

Sandbox environment

Full API parity at api-sandbox.paynexus.io. The Debug module lets you force specific outcomes (success, pending, failed, declined, transport_error) via a single request parameter — test every error path in CI.

Webhook delivery

Every transaction state change posts a signed event to your endpoint. 5 retries with exponential backoff (0s → 2s → 8s → 32s → 2m), HMAC-SHA256 signatures, and full replay from the Cabinet. You never lose a transaction update.

Observability stack

Prometheus-ready metrics, structured JSON logs, per-request tracing, and SLI/SLO tracking targeting 99.5%. Release gates prevent bad deploys from reaching production. Your team sees what we see.

Integration flow

What happens when a customer pays.

Here's a typical card deposit, end to end. The entire flow completes in 2–10 seconds for the synchronous parts; webhooks arrive asynchronously when the PSP confirms settlement.

Customer hits checkout

Your app renders the order summary and collects payment method choice.

You call Paynexus

POST /v1/deposits with amount, currency, payway, and an idempotency key (your order ID).

Paynexus routes

Our routing engine picks the optimal PSP based on your rules, PSP health, and the customer's region.

PSP returns redirect URL

We wrap the PSP's response and return a clean redirect_url for your app to send the customer to.

Customer pays on PSP page

Standard hosted-page flow. PSP handles 3DS, card entry, and authorization.

PSP calls Paynexus back

We verify the PSP signature, update our ledger, and emit a deposit.completed event.

We call your webhook

HMAC-SHA256 signed payload arrives at your endpoint. Verify, update order status, fulfill.

You respond 200 OK

Webhook delivery is complete. If you return non-2xx, we retry with exponential backoff up to 5 times.

flow.ts
TypeScript
// Step 2: Your backend creates the deposit const r = await fetch("https://api.paynexus.io/v1/deposits", { method: "POST", headers: { "X-Api-Key": process.env.PN_KEY, "X-Api-Secret": process.env.PN_SECRET, "X-Idempotency-Key": `order-${orderId}`, }, body: JSON.stringify({ amount: "100.00", currency: "USD", payway: "CARD", bill_id: `order-${orderId}`, callback_url: "https://your-app.com/webhooks/paynexus", }), }); // Step 4: We return routing info const { id, status, redirect_url } = await r.json(); // Step 5: Send customer to the PSP-hosted page response.redirect(redirect_url); // Step 7: Your webhook handler receives the event app.post("/webhooks/paynexus", (req, res) => { if (!verifyHmac(req.body, req.headers["x-paynexus-signature"])) { return res.status(401).end(); } const { transaction } = req.body; if (transaction.status === "completed") { fulfillOrder(transaction.bill_id); } res.status(200).end(); });
Division of responsibility

What you handle. What we handle.

A clear split is the whole point of an orchestration layer. You own your product and your ledger. We own the payment plumbing.

You handle

  • Your product, UX, and business logic
  • Your checkout screens and customer experience
  • Your order model, fulfillment, and shipping
  • Your customer accounts and customer support
  • Your financial ledger and tax reporting
  • Your webhook handler (one endpoint)
  • Your API credentials (keep them secret)

We handle

  • PSP negotiation, contracts, and relationships
  • Smart routing across 100+ providers
  • Automatic failover and retry with backoff
  • Idempotency guarantees (no duplicate charges)
  • Callback verification and webhook delivery
  • Rate limiting, circuit breakers, observability
  • PCI-DSS scope reduction (we hold the card data)
  • Compliance plumbing (PSD2/SCA, AML hooks)
Integration patterns

Three ways to integrate.

REST

Direct API integration

Best for most merchants. Any language, any framework. Call our endpoints, handle our webhooks, done. Ship in days.

SDK

PHP SDK integration

Best for PHP monoliths that need direct PSP access or want to add custom providers. composer require paynexus/sdk-core.

Both

Hybrid integration

Common in complex businesses. Use REST API for customer-facing deposits and the SDK for back-office payout flows. Same keys, same transaction IDs.

Why an orchestration layer

What you skip by not doing this yourself.

Not integrating 5–10 PSPs yourself

Every PSP has its own API, webhook format, edge cases, and incident channels. Integrating one well takes 2–4 weeks. Ten takes a year of engineering time — time you don't get back.

Not building your own failover

When a PSP has an outage (they all do), your revenue stops unless you have a tested failover. Our circuit breaker and multi-PSP cascade routing already handle this — battle-tested at casino-scale.

Smaller PCI-DSS scope

Card data never touches your servers when you use our hosted flows. Compliance scope stays small and audits stay cheap.

Commercial leverage

Our PSP rates come from aggregate volume. A new merchant immediately benefits from our negotiated pricing — rates you'd need years to earn on your own.

Next steps

Start building.

Ready to stop thinking about payment plumbing?

Free sandbox. Production when you're ready. No contracts.

Start free Talk to sales