Skip to main content

Payments Flows

OrchestratorX is built for teams that want engineering-grade control over payments.

To simplify architectural decisions, the ecosystem can be viewed as four independent building blocks. By defining ownership of each block — OrchestratorX-managed, self-hosted, or third-party — you can design an architecture aligned with your compliance posture, performance requirements, and internal engineering capabilities.

The Four Core Components​

The SDK (Frontend)​

The entry point for your payment flow. It resides in your frontend and is responsible for securely capturing sensitive payment information.

Intelligent Routing & Orchestration (Backend)​

The core of the operation. It manages the payment lifecycle, executes routing logic, and handles post-payment operations like refunds.

Acquirer & Processor Connectivity (Connectors)​

The actual pipelines that translate the transaction (e.g., Stripe, Adyen, Worldpay).

Vault (Card Data Storage)​

The secure locker for sensitive card data to enable "One-Click" recurring payments without the user re-entering details.

Each Component can be handled by OrchestratorX, managed or self-deployed by your own team, or even sourced from a third-party provider e.g. Vault (reference)

Integration Architecture​

With the components defined, the next step is to select your integration architecture. This choice hinges on a single question: Who controls the payment execution?

Choose the integration method that best aligns with your payment flow requirements:

Integration Model 1: Client-Side SDK Payments​

(Tokenize Post-Payment | SDK-Initiated Execution)

When to Choose This Model:

  • You want dynamic, frontend-driven payment experiences
  • You prefer minimal backend orchestration logic
  • You want SDK-triggered payment confirmation
  • You are optimizing for rapid checkout implementation

High-level Flow:

  1. Merchant will call the /payments API and load the Payment SDK.
  2. SDK securely collects payment details.
  3. SDK triggers payment confirmation.
  4. SDK communicates with OrchestratorX backend.
  5. OrchestratorX:
    • Applies routing logic
    • Sends request to configured PSP
    • Manages authorization/capture
    • Returns final payment status

Integration Model 2: Server-to-Server (S2S) Payments​

(Tokenize Pre-Payment | Backend-Controlled Execution)

When to Choose This Model:

  • You want granular control over transaction timing
  • You require backend-driven orchestration logic
  • You want to tokenize credentials before execution
  • You prefer decoupling vaulting from transaction processing

High-level Flow:

Tokenize Card:

  • Tokenize payment credentials using - Vault SDK or backend call to /payment-methods
  • OrchestratorX securely stores the credential and returns a reusable identifier - payment_method_id.

Trigger Payment Execution:

  • Option A: Process via OrchestratorX Orchestration by calling /payments API.
    • Use this option if you want OrchestratorX to:
      • Apply routing logic
      • Select the optimal connector
      • Manage retries and failover
      • Handle authorization and capture lifecycle
    • This is the recommended model for merchants adopting OrchestratorX orchestration.
  • Option B: Process via Proxy API by calling /proxy API.
    • Use this option if:
      • You do not want to change your existing PSP integration immediately
      • You want OrchestratorX to act as a passthrough layer
      • You are incrementally migrating to full orchestration
    • In this mode:
      • Your existing integration contract remains unchanged
      • OrchestratorX forwards requests to the configured processor
      • You can progressively enable routing and orchestration features