Pay-Then-Vault

OrchestratorX provides flexible payment processing with multiple flow patterns to accommodate different business needs. The system supports one-time payments, saved payment methods, and recurring billing through a comprehensive API design.

note

Integration Path

Client-Side SDK Payments (Tokenise Post Payment)

Refer to Payments (Cards) section if your flow requires the SDK to initiate payments directly. In this model, the SDK handles the payment trigger and communicates downstream to the OrchestratorX server and your chosen Payment Service Providers (PSPs). This path is ideal for supporting dynamic, frontend-driven payment experiences.

flowchart TD
    A[Payment Request] --> B{Payment Type}

    %% One-time branch
    B -->|One-time| C[One-time Payment Flows]
    C --> C1[Instant Payment]
    C --> C2[Manual Capture]
    C --> C3[Decoupled Flow]

    %% Store card branch
    B -->|Store card| D[Payment Method Storage]
    D --> D1[Long-term storage]
    D --> D2[Short-term storage]
    D --> D3[List Saved Methods]

    %% Recurring branch
    B -->|Recurring| E[Recurring Payment Flows]
    E --> E1["Setup with charge (CIT)"]
    E --> E2["Setup without charge (CIT)"]
    E --> E3["Execute (MIT)"]
    
    classDef default fill:#3F8CFF,stroke:#3F8CFF,color:#ffffff,rx:6

One-Time Payment Patterns

1. Instant Payment (Automatic Capture)

Use Case: Simple, immediate payment processing

Endpoint: POST /payments

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#ffffff",
    "primaryBorderColor": "#2563EB",
    "lineColor": "#2563EB",
    "secondaryColor": "#EFF6FF",
    "tertiaryColor": "#DBEAFE",
    "fontFamily": "Inter, system-ui, sans-serif",
    "fontSize": "14px",
    "textColor": "#000000",

    "actorBkg": "#346DDB",
    "actorBorder": "#999999",
    "actorTextColor": "#ffffff",

    "signalColor": "#000000",
    "signalTextColor": "#696969",

    "labelBoxBkgColor": "#346DDB",
    "labelBoxBorderColor": "#2563EB"
  }
}}%%
sequenceDiagram
    participant Client
    participant OrchestratorX
    participant Processor

    Client->>OrchestratorX: POST /payments\n{confirm: true, capture_method: "automatic"}
    OrchestratorX->>Processor: Authorize + Capture
    Processor-->>OrchestratorX: Payment Complete
    OrchestratorX-->>Client: Status: succeeded

Required Fields:

confirm: true
capture_method: "automatic"
payment_method

Final Status: succeeded

2. Two-Step Manual Capture

Use Case: Deferred capture (e.g., ship before charging)

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#ffffff",
    "primaryBorderColor": "#2563EB",
    "lineColor": "#2563EB",
    "secondaryColor": "#EFF6FF",
    "tertiaryColor": "#DBEAFE",
    "fontFamily": "Inter, system-ui, sans-serif",
    "fontSize": "14px",
    "textColor": "#000000",

    "actorBkg": "#346DDB",
    "actorBorder": "#999999",
    "actorTextColor": "#ffffff",

    "signalColor": "#000000",
    "signalTextColor": "#696969",

    "labelBoxBkgColor": "#346DDB",
    "labelBoxBorderColor": "#2563EB"
  }
}}%%
sequenceDiagram
    participant Client
    participant OrchestratorX
    participant Processor

    Client->>OrchestratorX: POST /payments<br />{confirm: true, capture_method: "manual"}
    OrchestratorX->>Processor: Authorize Only
    Processor-->>OrchestratorX: Authorization Hold
    OrchestratorX-->>Client: Status: requires_capture

    Note over Client: Ship goods, then capture

    Client->>OrchestratorX: POST /payments/{id}/capture
    OrchestratorX->>Processor: Capture Funds
    Processor-->>OrchestratorX: Capture Complete
    OrchestratorX-->>Client: Status: succeeded

Flow:

Authorize: POST /payments with capture_method: "manual"
Status: requires_capture
Capture: POST /payments/{payment_id}/capture
Final Status: succeeded

Read more: here

3. Fully Decoupled Flow

Use Case: Complex checkout journeys with multiple modification steps. Useful in headless checkout or B2B portals where data is filled progressively.

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#ffffff",
    "primaryBorderColor": "#2563EB",
    "lineColor": "#2563EB",
    "secondaryColor": "#EFF6FF",
    "tertiaryColor": "#DBEAFE",
    "fontFamily": "Inter, system-ui, sans-serif",
    "fontSize": "14px",
    "textColor": "#000000",

    "actorBkg": "#346DDB",
    "actorBorder": "#999999",
    "actorTextColor": "#ffffff",

    "signalColor": "#000000",
    "signalTextColor": "#696969",

    "labelBoxBkgColor": "#346DDB",
    "labelBoxBorderColor": "#2563EB"
  }
}}%%
sequenceDiagram
    participant Client
    participant OrchestratorX

    Client->>OrchestratorX: POST /payments\n(Create Intent)
    OrchestratorX-->>Client: payment_id + client_secret

    Client->>OrchestratorX: POST /payments/{id}\n(Update: customer, amount, etc.)
    OrchestratorX-->>Client: Updated Intent

    Client->>OrchestratorX: POST /payments/{id}/confirm\n(Final Confirmation)
    OrchestratorX-->>Client: Status: succeeded / requires_capture

    opt Manual Capture
        Client->>OrchestratorX: POST /payments/{id}/capture
        OrchestratorX-->>Client: Status: succeeded
    end

Endpoints:

Create: POST /payments
Update: POST /payments/{payment_id}
Confirm: POST /payments/{payment_id}/confirm
Capture: POST /payments/{payment_id}/capture (if manual)

4. 3D Secure Authentication Flow

Use Case: Enhanced security with customer authentication

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#ffffff",
    "primaryBorderColor": "#2563EB",
    "lineColor": "#2563EB",
    "secondaryColor": "#EFF6FF",
    "tertiaryColor": "#DBEAFE",
    "fontFamily": "Inter, system-ui, sans-serif",
    "fontSize": "14px",
    "textColor": "#000000",

    "actorBkg": "#346DDB",
    "actorBorder": "#999999",
    "actorTextColor": "#ffffff",

    "signalColor": "#000000",
    "signalTextColor": "#696969",

    "labelBoxBkgColor": "#346DDB",
    "labelBoxBorderColor": "#2563EB"
  }
}}%%
sequenceDiagram
    participant Client
    participant OrchestratorX
    participant Customer
    participant Bank

    Client->>OrchestratorX: POST /payments<br />{authentication_type: "three_ds"}
    OrchestratorX-->>Client: Status: requires_customer_action<br />+ redirect_url

    Client->>Customer: Redirect to 3DS page
    Customer->>Bank: Complete 3DS Challenge
    Bank-->>OrchestratorX: Authentication Result

     OrchestratorX-->>OrchestratorX: Resume Payment Processing

    OrchestratorX-->>Client: Status: succeeded

Additional Fields:

authentication_type: "three_ds"

Status Progression: processing → requires_customer_action → succeeded

Read more: here

Recurring Payments and Payment Storage

1. Saving Payment Methods

During Payment Creation:

Add setup_future_usage: "off_session" or "on_session"
Include customer_id
Result: payment_method_id returned on success

Understanding setup_future_usage:

on_session: Use when the customer is actively present during the transaction. This is typical for scenarios like saving card details for faster checkouts in subsequent sessions where the customer will still be present to initiate the payment (e.g., card vaulting for e-commerce sites).
off_session: Use when you intend to charge the customer later without their active involvement at the time of charge. This is suitable for subscriptions, recurring billing, or merchant-initiated transactions (MITs) where the customer has pre-authorized future charges.

2. Using Saved Payment Methods

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#ffffff",
    "primaryBorderColor": "#2563EB",
    "lineColor": "#2563EB",
    "secondaryColor": "#EFF6FF",
    "tertiaryColor": "#DBEAFE",
    "fontFamily": "Inter, system-ui, sans-serif",
    "fontSize": "14px",
    "textColor": "#000000",

    "actorBkg": "#346DDB",
    "actorBorder": "#999999",
    "actorTextColor": "#ffffff",

    "signalColor": "#000000",
    "signalTextColor": "#696969",

    "labelBoxBkgColor": "#346DDB",
    "labelBoxBorderColor": "#2563EB"
  }
}}%%
sequenceDiagram
    participant Client as Client
    participant HS as OrchestratorX

    Client->>HS: POST /payments/create<br/>{customer_id}
    HS-->>Client: client_secret

    Client->>HS: GET /customers/payment_methods<br/>{client_secret, publishable_key}
    HS-->>Client: List of payment_tokens

    Client->>HS: POST /payments/{id}/confirm<br/>{payment_token}
    HS-->>Client: Payment Result

Steps:

Initiate: Create payment with customer_id
List: Get saved cards via GET /customers/payment_methods
Confirm: Use selected payment_token in confirm call

PCI Compliance and `payment_method_id`

Storing payment_method_id (which is a token representing the actual payment instrument, which could be a payment token, network token, or payment processor token) significantly reduces your PCI DSS scope. OrchestratorX securely stores the sensitive card details and provides you with this token. While you still need to ensure your systems handle payment_method_id and related customer data securely, you avoid the complexities of storing raw card numbers. Always consult with a PCI QSA to understand your specific compliance obligations.

Recurring Payment Flows

3. Customer-Initiated Transaction (CIT) Setup

flowchart TD
    A[CIT Setup] --> B{Setup Type}
    B -->|With Charge| C[Amount > 0<br/>setup_future_usage:<br/>off_session]
    B -->|Zero Dollar Auth| D[Amount: 0<br/>payment_type:<br/>setup_mandate]
    C --> E[payment_method_id]
    D --> E

    classDef default fill:#3F8CFF,stroke:#3F8CFF,color:#ffffff,rx:6
    classDef accent fill:#3F8CFF,stroke:#3F8CFF,color:#ffffff,rx:6
    classDef decision fill:#FFF8E1,stroke:#CCCCCC,color:#1A1A1A
    class A accent
    class E accent
    class B decision

Read more: here

4. Merchant-Initiated Transaction (MIT) Execution

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#ffffff",
    "primaryBorderColor": "#2563EB",
    "lineColor": "#2563EB",
    "secondaryColor": "#EFF6FF",
    "tertiaryColor": "#DBEAFE",
    "fontFamily": "Inter, system-ui, sans-serif",
    "fontSize": "14px",
    "textColor": "#000000",

    "actorBkg": "#346DDB",
    "actorBorder": "#999999",
    "actorTextColor": "#ffffff",

    "signalColor": "#000000",
    "signalTextColor": "#696969",

    "labelBoxBkgColor": "#346DDB",
    "labelBoxBorderColor": "#2563EB"
  }
}}%%
sequenceDiagram
    participant Merchant as Merchant
    participant HS as OrchestratorX
    participant Processor as Processor

    Note over Merchant: Subscription billing trigger

    Merchant->>HS: POST /payments<br/>{off_session: true, recurring_details}
    HS->>Processor: Process with saved payment_method_id
    Processor-->>HS: Payment Result
    HS-->>Merchant: Status: succeeded

Read more: here

Status Flow Summary

stateDiagram-v2
    [*] --> RequiresConfirmation
    RequiresConfirmation --> Processing : confirm=true
    Processing --> RequiresCustomerAction : 3DS<br />needed       
    RequiresCustomerAction --> Processing : 3DS complete
    Processing --> RequiresCapture : manual capture
    Processing --> Succeeded : automatic capture
    Processing --> Failed : payment failed
    RequiresCapture --> Succeeded : capture API call
    RequiresCapture --> PartiallyCaptured : partial capture
    PartiallyCaptured --> [*]
    Succeeded --> [*]
    Failed --> [*]       

Notes

Terminal States: succeeded, failed, cancelled, partially_captured are terminal states requiring no further action
Capture Methods: System supports automatic (funds captured immediately), manual (funds captured in a separate step), manual_multiple (funds captured in multiple partial amounts via separate steps), and scheduled (funds captured automatically at a future predefined time) capture methods.
Authentication: 3DS authentication automatically resumes payment processing after customer completion
MIT Compliance: Off-session recurring payments follow industry standards for merchant-initiated transactions

One-Time Payment Patterns​

1. Instant Payment (Automatic Capture)​

2. Two-Step Manual Capture​

3. Fully Decoupled Flow​

4. 3D Secure Authentication Flow​

Recurring Payments and Payment Storage​

1. Saving Payment Methods​

2. Using Saved Payment Methods​

PCI Compliance and payment_method_id​

Recurring Payment Flows​

3. Customer-Initiated Transaction (CIT) Setup​

4. Merchant-Initiated Transaction (MIT) Execution​

Status Flow Summary​

Notes​

One-Time Payment Patterns

1. Instant Payment (Automatic Capture)

2. Two-Step Manual Capture

3. Fully Decoupled Flow

4. 3D Secure Authentication Flow

Recurring Payments and Payment Storage

1. Saving Payment Methods

2. Using Saved Payment Methods

PCI Compliance and `payment_method_id`

Recurring Payment Flows

3. Customer-Initiated Transaction (CIT) Setup

4. Merchant-Initiated Transaction (MIT) Execution

Status Flow Summary

Notes