Configure Third-Party Adapter
The XYB Payments Platform is built to support payments across multiple providers , including FX partners, card issuers, and clearing houses using a modular adapter framework. This guide explains what an adapter is, how it integrates with the Payment Engine, and what you need to configure on your end to start processing live payments.
What Is an Adapter?
An adapter is a service component that connects the XYB Payment Engine to a third-party Payment Service Provider (PSP). Adapters act as translators:
They receive standard payment commands from XYB
Convert those commands into the provider’s native API format
Send requests to the provider (e.g., CurrencyCloud, Visa, a SEPA rail)
Listen for updates or callbacks from the provider
Convert those updates into standard payment events back into XYB
How Adapters Work Inside XYB
A payment is initiated via API (e.g., /request-payment)
The workflow defines that a specific payment type (e.g., SEPA_OUT) requires an external adapter
The engine sends a payment command to the adapter via Kafka
The adapter calls the third-party API using client credentials and routing metadata
The third party responds via webhook or polling
The adapter emits a payment event to XYB (via Kafka)
XYB updates the payment state (e.g., settled, failed)
Adapter logic is fully decoupled from the Payment Engine via a unified messaging contract.
What You Need to Provide
To configure and activate an adapter for your payments, provide:
PSP credentials (API key, client ID/secret, webhook config)
Supported use cases (e.g., SEPA_OUT, FX_TRANSFER)
Currencies and countries supported per partner
Any PSP-specific metadata (e.g., service level, reference format)
XYB will take care of securely storing this information and ensuring it is mapped correctly in the adapter layer.
Routing Logic (Under the Hood)
XYB uses the PaymentRouteService and associated field decorators to determine which adapter to use for a given request.
Routing is based on fields like:
Schema
Currency pair
Payment type (e.g., instant, priority)
Account metadata
The routing engine dynamically assigns the correct adapter
You can influence routing behavior via request metadata or onboarding config
No hardcoded adapter names — all mapping is field- and schema-driven.
Command and Event Structure
Outgoing (Command)
Sent by Payment Engine to adapter
Includes:
Payment ID
Amount, currency
Sender & beneficiary details
Schema/payment rail
Incoming (Event)
Sent by adapter to Payment Engine
Includes:
Payment ID
Partner reference
Status update (e.g., AUTHORIZED, SETTLED)
FX rate, failure reason, other metadata
All messages follow a standard interface so the platform can support any number of providers through the same contract.
Standard Operations Supported
If the PSP supports it, adapters can expose additional functionality to XYB:
Refund or return
Cancellation (if in-flight)
Resend or status check
These operations can be triggered via XYB's internal workflow engine or via the Payment Operations API.
Partner Onboarding Process
To onboard a new provider via adapter:
Contact your integration manager with your provider list
Provide PSP credentials, supported countries, and intended schemas
Review adapter behavior and test sandbox transactions
Validate events are flowing correctly from adapter to Payment Engine
Go live with mapped routing for those schemas
XYB can support your adapter onboarding or provide a sandbox/mock adapter if your partner is still under integration.
Troubleshooting and Observability
XYB emits real-time Kafka events for all adapter responses. Use these to:
Trace command → event lifecycle
Reconcile external transaction references
Track settlement delays or failures
You can also access adapter status via:
Payment History API
Kafka topics for integration monitoring
MFE Console for internal operations teams
Next Steps
Configure a Workflow That Uses an Adapter
Understand Payment Command and Event Structure
Get Started with Payment History & Monitoring
Last updated