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

PreviousUnderstanding the XYB Payment EcosystemNextAdd and Manage Beneficiary Accounts

Last updated