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.
1️
You call /request-payment with user IDs and amount
2️
Payment Service fetches sender/receiver accounts
3️
System matches to the “internal_transfer” schema
4️
Engine runs: ledger auth > risk clearance > settlement
5️
Payment status updates: created → authorized → cleared → settled
6️
Payment stored in history, ready to be shown in user UI
Last updated