# 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.xyb.co/xyb-payments/payment-workflows-and-automations/payment-workflow-overview.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
