> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-platform-1/xyb-payments/getting-started-with-payments/xyb-payments-overview/how-payments-work.md).

# How Payments Work

Every time you initiate a payment on the XYB Payments Platform, a powerful orchestration engine handles the entire process, from validating the request to settling funds.

This article explains what happens under the hood so you can build confidently.

***

### The Payment Flow: Step by Step

#### 1. **Initiate the Payment**

You (the client system) make a POST request to our `/request-payment` API.

**You provide:**

* Basic payment info (amount, currency, sender, receiver)
* Payment type (e.g., SEPA, FX, card payout)
* References to account, card, or beneficiary IDs

**Customer Action:**\
Send the payment request with all required fields and identifiers.

***

#### 2. **Validation & Enrichment**

The Payment Service validates the structure and logic of your request, then enriches it by fetching extra details:

* Sender & receiver account details
* Card or beneficiary info
* Owner type (customer, business, employee, etc.)

**Customer Action:**\
Ensure all referenced accounts or cards are already registered and valid.

***

#### 3. **Schema Selection & Workflow Matching**

The system identifies the right **payment schema** — a predefined template that defines:

* What steps are required (e.g., ledger check, risk review)
* What rules apply (e.g., currency limits, mandatory fields)
* Which third-party adapter (if any) will be used

**Customer Action:**\
During onboarding, agree on supported schemas and how they should behave.

***

#### 4. **Payment Engine Takes Over**

Now that everything is ready, the payment is handed off to the **Payment Engine**, which executes the steps defined in the workflow.

These may include:

* **Ledger Authorization**: Reserve funds in your system
* **Risk Checks**: Run AML or fraud checks
* **Partner Integration**: Forward to a third-party like a card issuer or FX partner
* **Clearing & Settlement**: Mark the payment as settled and deduct balances

**Customer Action:**\
Optionally configure custom workflows per payment type, or use the defaults.

***

#### 5. **Track Progress via Events**

As the payment moves forward, the engine emits real-time **Kafka events** for each state change:

* Payment Created
* Risk Cleared
* Ledger Authorized
* Settled or Failed

You can subscribe to these events or access them via **Payment History APIs**.

**Customer Action:**\
Use webhooks or polling to update your UI or internal systems.

***

#### 6. **Store Final Payment**

Once the payment is finalized, it's removed from the engine’s memory and stored in the **Payment History Service**. This is your source of truth for reporting, support, and user-facing views.

**Customer Action:**\
Query Payment History for transaction records and audit trails.

***

#### 7. **Take Action If Needed (Optional)**

If a payment is stuck, pending, or needs to be stopped, use the **Payment Operations API** to:

* Cancel
* Retry
* Rollback

**Customer Action:**\
Build admin tooling or use our console to monitor and manage payment actions.

***

### Example: Internal Transfer

Let’s say a user in your app transfers £100 to another user.

<table><thead><tr><th width="100">Step</th><th>What Happens</th></tr></thead><tbody><tr><td>1️</td><td>You call <code>/request-payment</code> with user IDs and amount</td></tr><tr><td>2️</td><td>Payment Service fetches sender/receiver accounts</td></tr><tr><td>3️</td><td>System matches to the “internal_transfer” schema</td></tr><tr><td>4️</td><td>Engine runs: ledger auth > risk clearance > settlement</td></tr><tr><td>5️</td><td>Payment status updates: <code>created → authorized → cleared → settled</code></td></tr><tr><td>6️</td><td>Payment stored in history, ready to be shown in user UI</td></tr></tbody></table>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.xyb.co/xyb-platform-1/xyb-payments/getting-started-with-payments/xyb-payments-overview/how-payments-work.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.