Payment Workflow Overview

Payment workflows define how money moves through a financial platform. They orchestrate logic across multiple services such as ledger, risk, account verification, and external payment providers. In the XYB platform, workflows make it possible to define custom, dynamic payment flows without writing new backend code.

These workflows are not just automations that react to events they control how a payment happens, step by step.

Why Use Workflows for Payments?

  • Custom behavior per client or product: Payment workflows can be tailored for different transaction types, currencies, or risk profiles.

  • Operational control: Business teams can change the payment behavior without deploying code.

  • Traceability: Each step in the workflow is logged, auditable, and observable.

  • Flexibility: Insert risk checks, ledger evaluations, routing decisions, or manual approvals at any point.

Example: Outgoing FX Payment

Workflow steps might include:

  1. Validate payment request format

  2. Perform ledger balance check

  3. Run risk screening

  4. Determine appropriate payment provider

  5. Initiate payment

  6. Update payment status

  7. Log result for observability

Each step is defined using a sequence of actions and conditions in a workflow plan. Parameters allow dynamic logic per client or product.

Integration with Platform Services

Payment workflows integrate with:

  • Ledger: Check balances, book transactions, validate journal entries

  • Risk: Perform KYC, AML, and fraud checks

  • Wallets: Handle internal transfers

  • Payment Providers: Route to SEPA, SWIFT, instant, or custom rails

Each of these services acts as a participant in the workflow and can be configured independently.

Versioning and Control

Workflows are defined as part of a Plan in a Workflow Family. This allows version-controlled logic that can be activated, rolled back, or tailored for different clients. For example, Client A may use fx-transfer-v1 while Client B uses fx-transfer-v2.

State Tracking and Observability

All payment workflows report state transitions (e.g. INITIATED → AUTHORIZED → SETTLED). Services track the current state and can expose this to end users.

Execution logs, error handling, and audit trails are captured for each workflow instance.

Best Practices

  • Use parameters for flexibility instead of hardcoded logic

  • Separate flows by product type to maintain clarity

  • Insert log.atInfo() checkpoints in key transitions

  • Handle timeouts and retries at the service level, not inside workflows

  • Keep the initial state and terminal states clearly defined

Last updated