> 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-payments/getting-started-with-payments/planning-your-payments-infrastructure.md). # Planning your Payments Infrastructure Setting up your integration with XYB Payments involves more than sending a request it’s about designing a payment architecture that aligns with your business needs and leverages the full power of XYB’s orchestration engine. This guide walks you through the key decisions and configurations you'll need to make before going live. *** ### 1. Define Your Payment Use Cases Before configuring anything, clarify: * **What types of payments** you want to support (e.g., internal transfers, SEPA, FX, card payouts) * **When payments are triggered** (e.g., user action, batch job, API call from another system) * **What makes a payment successful** in your business context (e.g., settlement, confirmation from partner, ledger update) *** ### 2. Map Out Payment Types & Schemas XYB uses predefined **schemas** to determine how a payment behaves including what data it needs, how it’s validated, and which workflow it follows. For each use case, determine: * Which schema fits: `INTERNAL`, `SEPA`, `FX_TRANSFER`, etc. * What fields are required (e.g., party account, currency, mandate) * Whether a fixed-side amount is required (for FX) * Any special business logic or limits (e.g., max amount per transaction) > During onboarding, you’ll agree on the list of supported schemas and their rules with the XYB team. *** ### 3. Set Up Accounts, Cards, and Beneficiaries To make a valid payment request, the system must be able to **resolve all references** to actual accounts, cards, or beneficiaries. * Ensure all sending and receiving parties are created in the **Account Service** * Make sure account and card IDs are synced between your system and XYB’s * Decide how you’ll link end users (individuals, businesses) to XYB-managed accounts > Payments will fail validation if the referenced parties cannot be enriched. *** ### 4. Configure Adapters for External Payment Rails XYB connects to payment processors (e.g., Visa, Mastercard, SEPA processors) via **adapters**. You need to: * Identify the partners you’ll work with (e.g., Currency Cloud for FX) * Provide credentials or onboarding data for each adapter * Assign adapters to schemas (e.g., use Adapter X for SEPA, Adapter Y for FX) > You do not need to implement these adapters just configure and authorize them with XYB. *** ### 5. Align on Workflow Requirements XYB workflows define the logic that governs a payment’s lifecycle including steps like: * Ledger authorization * Risk assessment (fraud, AML) * External execution via adapter * Settlement confirmation Decide with your compliance, risk, and treasury teams: * Which steps are mandatory per payment type * Which workflows can auto-approve vs require review * Whether you need custom workflows or will use XYB’s defaults *** ### 6. Set Up Observability XYB emits **real-time events** (via Kafka or webhooks) for all key changes in a payment’s state. To track and monitor payments: * Subscribe to topics like `payment.created`, `payment.settled`, `payment.failed` * Feed events into your internal systems or dashboards * Log and persist events as part of your audit trail > Alternatively, use the Payments MFE or History API to retrieve payment status. *** ### 7. Prepare Operational Controls XYB provides APIs and UI tools for managing payments post-submission. Plan your access control and workflows for: * **Canceling** a payment in progress * **Retrying** a failed request * **Rolling back** a payment due to error or dispute Make sure: * Your teams know when each action is allowed * Permissions are mapped to roles (e.g., Support, Ops) * You’ve integrated these into your admin tools or use XYB’s console *** ### 8. Testing & Launch Readiness Before going live: * Test all supported schemas in a sandbox environment * Verify enrichment flows and account resolution * Run payments through all expected workflow paths * Simulate failure and retry scenarios * Confirm event subscriptions and downstream updates > Use your testing phase to validate both functional and operational coverage. *** ### 9. External Ledger or Account Systems If you manage your own account engine or ledger system, you’ll need to: * Sync customer and account data with XYB’s Account Service * Set up adapters or APIs for ledger reservation and balance confirmation * Align on how ledger state is confirmed (e.g., synchronous call vs event subscription) * Ensure updates (success/failure) flow back to XYB via callbacks or events > If you use your own ledger, XYB becomes an orchestrator and requires confirmation before proceeding with a payment. *** ### Next Steps * Submit a Payment Request * Configure an Adapter * Register a Custom Workflow * Using Payment History API --- # 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-payments/getting-started-with-payments/planning-your-payments-infrastructure.md?ask=&goal= ``` `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.