> 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/payment-setup/configure-third-party-adapter.md). # 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 1. **A payment is initiated** via API (e.g., /request-payment) 2. **The workflow defines** that a specific payment type (e.g., SEPA\_OUT) requires an external adapter 3. The engine sends a **payment command** to the adapter via Kafka 4. The adapter calls the third-party API using client credentials and routing metadata 5. The third party responds via webhook or polling 6. The adapter emits a **payment event** to XYB (via Kafka) 7. 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: 1. Contact your integration manager with your provider list 2. Provide PSP credentials, supported countries, and intended schemas 3. Review adapter behavior and test sandbox transactions 4. Validate events are flowing correctly from adapter to Payment Engine 5. 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 --- # 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/payment-setup/configure-third-party-adapter.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.