> This is part 1 of 4 of the full documentation (pages 1–100 of 306). > The content is paginated: fetch every part to see all of it. > Next part: https://docs.xyb.co/llms-full.txt/1 > Page index: https://docs.xyb.co/llms.txt # 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 This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.xyb.co/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # XYB Documentation Portal! Learn how to maximise our platform offerings, build financial solutions catered to your needs, and seamlessly integrate with our modern banking components.
Cover image
Platform Orchestrationconsole.jpgXYB Console - Quick Start Guide
Getting Startedcard-nextgen.pngProduct Configurations
Solutionsapi.jpghttps://app.gitbook.com/s/akJn6TxWIBAbZwLlYoVP/api-reference-guides/ledger-setup-and-configuration-apis
Build Productspayment (1).jpgXYB Payments
Orchestrate and Operatepayment (2).jpgXYB Credit Solutions Overview
API Referenceconsole.jpg
### Important Links * [XYB Console - Quick Start Guide](/the-platform/xyb-console-quick-start-guide) * [Product Configurations](/xyb-console/product-configurations) * [Workflows: Build, Automate, and Orchestrate Operations](/xyb-console/workflow-management) * [Set up Access & Permissions](/xyb-console/access-and-permissions-overview) * [Explore the Use Cases](/the-platform/explore-the-use-cases) * [Platform Release Notes](https://github.com/xybteam/main-customerdocs/tree/main/broken-reference/README.md) ### What's New * Explore key workflows across the XYB platform with guided walkthroughs: * [**Create a New Product with the Orchestration Tool**](/the-platform/video-tutorials-and-demos/create-a-new-product) **-** Quickly configure and deploy tailored financial products using XYB’s drag-and-drop orchestration engine. * [**Customer View of Global Balances on Console & Mobile App**](/the-platform/video-tutorials-and-demos/view-global-balances)**:** Get a real-time snapshot of multi-account, multi-currency balances across platforms via the back-office console or customer-facing mobile app. * Check out our latest release notes: [XYB Platform 1.01 Release Notes](/platform-release-notes/release-updates-and-announcements). # XYB Platform - Overview XYB is a platform for building, orchestrating, and operating financial products: deposits and wallets, payments and FX, credit, interest, and cards.It works through three layers: **Component** (the individual capabilities), **Orchestration** (the shared services those capabilities configure against), and **Experience** (how it's all surfaced to a person)each independent, connecting outward to payment rails, card networks, and identity/KYC providers through adapters. It's made of composable components you use only as needed, not one fixed product, plus the adapters that connect them outward.With the XYB platform, you can modernise a live system, add a single new capability, or build from scratch, all on the same platform, so your starting point doesn't lock you into a different product later. It's built for multiple personas: product managers and developers who configure products and workflows, banking operators who run day-to-day operations from the console, and the end users of the resulting white-labeled apps.
Your situationWhat you do
You have an existing financial systemModernise it. Run XYB above your current core, which stays in place beneath it.
You want to add something newEnhance it. Add a specific new capability on top of what you already have.
You're starting freshBuild it from the ground up. Run your entire infrastructure on XYB.
### How it works XYB's components are composable: Ledger for balance history, Accounts for funds, instruments, and limits, Payments for moving money, and Credit for origination and servicing, so you use only what your product needs, not one fixed product.
You combine these into the product you're actually building, and where you need to reach outside XYB, into your existing core banking system, a payment rail, a KYC provider, you connect through **custom-built adapters**. Your integration points stay explicit and swappable, not buried inside the product itself. *** ### Built for your team XYB is built for multiple user personas. For **product managers and developers**, the platform is where you build and orchestrate workflows. With your environment provisioned in your chosen cloud, you: 1. Configure your product by defining **rules**, **behaviors**, and **workflows** 2. Each of those is powered by its own backend service 3. Once configured, the product is ready for your end users
### From publish to production Once you publish a product, the system runs continuously. Alongside it, XYB provides a fully transparent, fully operable **console**, where your banking operators work day to day. #### What operators can do in the console
CapabilityWhat it means
Track money movementsSee transactions as they happen, across every account
Execute paymentsInitiate and approve payments directly
Investigate behaviorTrace an account's or customer's activity end to end
Manage reconciliationsMatch ledger entries against external statements
Configure policiesUpdate the rules governing how workflows behave
...and moreAdditional operational tools, as your team needs them
*** ### White-labeled, end to end Both your operators and your end users interact with **fully white-labeled web and mobile applications**, carrying your brand throughout, not XYB's. | | End users get | Operators get | | ------ | ---------------------------------- | -------------------- | | Mobile | A branded app for everyday banking | — | | Web | A branded self-serve experience | The operator console | *** ### Learn more about: {% content-ref url="/pages/rpf68cfrdhbij1sQvuGf" %} [Platform Authentication](/the-platform/xyb-platform-overview/platform-authentication) {% endcontent-ref %} {% content-ref url="/pages/aV5I0QbJ0dOqERkNP4Lx" %} [XYB Console - Quick Start Guide](/the-platform/xyb-console-quick-start-guide) {% endcontent-ref %} {% content-ref url="/pages/FEmhZdYkKdeSB2DSBGw4" %} [Product Configurations](/xyb-console/product-configurations) {% endcontent-ref %} # SSO Setup Single Sign-On (SSO) allows your team to access the XYB Console using your organization’s existing identity provider (IdP), such as Okta, Microsoft Entra ID (Azure AD), JumpCloud, Google Workspace, or any provider that supports SAML 2.0.\ This setup is fully self-service: XYB provides the details required to create a SAML app in your IdP, and you return your IdP’s metadata to complete the connection. *** **Before you begin** You will need: * Access to your organisation’s IdP with permission to create or modify a SAML application. * Admin access to the XYB Console SSO configuration typically takes **5–10 minutes**. *** 1. Open your setup link: When your organisation begins onboarding with XYB, the designated admin receives an email inviting to set up SSO. Click **Continue setup** in the email and follow the prompts. 2. Configure your SSO connection**:** On the **Single sign-on** screen, you'll see two sections
* **Share with IdP** These fields contain metadata from XYB.\ Add them to your Identity Provider when creating the new SAML app. | Field | Description | | ---------------- | --------------------------------------------------------------------------- | | **ACS URL** | The Assertion Consumer Service URL used by your IdP to send SAML responses. | | **SP Entity ID** | XYB’s Service Provider (SP) Identifier. | {% hint style="info" %} Use the **copy icon** next to each field to avoid typos. {% endhint %} *** * **Get metadata from your IdP:** Most identity providers have a “Download Metadata” option within the SAML app you create. Refer to their docs to obtain the metadata, and copy and paste it in Metadata XML field. XYB will fetch **IdP Entity ID, SAML Sign-In URL**, and **X.509 Certificate** from this. Alternatively, you can also click the **Manual entry** tab and provide these details in each field separately. *** **3. Test your SSO connection** Once you’ve entered all three IdP values, click **Test and continue.** XYB securely validates that it can reach your IdP and process authentication requests. You will receive one of the following results: * **Success: Connection test successful.** You will see a confirmation message stating that your SSO connection is working. Click **Enable SSO** to activate SSO for your organisation. * **Failed: Connection test failed.** If XYB cannot reach your IdP or the metadata is invalid, you’ll see: **“Connection test failed. IdP cannot be reached.”** Click **Go back** to review the fields and test again, or reach out to our support team. You will then be redirected to your IdP to sign in for the first time. Upon completing the SSO flow, you'll be redirected back to the XYB console. Your organisation’s SSO setup is now complete and becomes the login method for all users in your organisation *** *** # Platform Architecture ### The three layers XYB is structured in three layers, each responsible for one part of the system: * **Component** the individual financial capabilities: Deposits & Wallets, Payments & FX, Credit, Interest, Cards. Each owns its own database and API; no other layer or capability reads or writes it directly. * **Orchestration** the shared services capabilities configure against instead of reimplementing: product configuration, policy, and workflow. * **Experience** how the platform is surfaced to a person: the console, and the mobile and web apps. Data flows upward and outward, not sideways. A capability posts its transactions to the Ledger and exposes an API and an event stream. Orchestration services read and write configuration that governs how those APIs behave, without touching a capability's data directly. Experience surfaces read from Orchestration and the capabilities' APIs — they don't hold their own copy of anything. *** ### Integration through adapters Anywhere XYB needs to talk to something outside the platform, a payment rail, a card network, an identity or KYC provider, an open banking connection, an email or SMS channel, that connection is a self-contained **adapter**, not logic embedded in the capability using it. A capability calls its own internal contract; a configuration setting decides which adapter, and which real-world provider, handles the request. Adapters register the specific features they support rather than a generic category, across five areas: Payments & FX, Accounts & ledger, Identity & verification, Open banking, and Communications. This lets more than one provider support the same feature side by side, and lets an integrator register their own existing provider relationship as an adapter, evaluated the same way as any built by XYB. *** ### How backend services power product configuration A **product** is what an entity is entitled to use. It's assembled from one or more backend services — Accounts, Cards, Policy management, and so on — each independently versioned, with its own configuration: the Accounts service configures default currency and wallet currencies, for example, while Policy management configures risk rules and approval requirements. A product moves through a **draft → active** lifecycle; assigning an active product to an entity is what unlocks account creation and onboarding for that entity. Nothing downstream is available until that assignment happens — the backend services power the product, but the product configuration is what turns them on for a given entity. *** ### Orchestration: policies and workflows **Policy** is structured as a hierarchy: a Domain (e.g. Payment Processing) contains Policy Types (e.g. Risk Rule), each with a Policy Definition and a versioned, current setting. Each policy type declares an evaluation strategy and a default evaluation service — the capability that actually executes the rule. Capabilities call out to policy rather than hardcoding limits or approval logic themselves. **Workflows** are named, ordered definitions of how something moves through the platform. Onboarding is one instance — a sign-up runs through an ordered list of steps (e.g. verify phone, choose product, link device), evaluated once per sign-up. Payments is another — named flow definitions (an ACH flow, an internal payment flow) define the shape a payment takes, with policy governing what's allowed inside it: scheme, rail, and whether an operation requires approval. **Approvals** are a cross-cutting workflow concern: a dedicated four-eye service raises and tracks approval requests from any capability that needs one, rather than each capability building its own approval logic. *** ### How operators work: the console The console isn't one application: it's a shell that loads one interface module per capability or orchestration service, so its structure mirrors the backend's own boundaries: a ledger module, a payments module, a policy module, an access-management module, each shipped alongside its own service. It reads live data directly from the capabilities and orchestration services underneath it — there's no separate reporting copy that can drift out of sync. A menu item's visibility depends on two independent conditions: the underlying service is deployed to that environment, and the interface module that renders it is deployed and registered there. Both have to be true — a service can be fully live with the right permissions granted, and its screen still won't appear if the module registration hasn't happened. Access within the console follows the same permission model as everywhere else: actions requiring a permission the operator lacks are hidden or disabled, not shown and then rejected. Roles split into two kinds — console roles, fully editable, governing what an operator can do; and roles corresponding to a customer-side access level, which are platform-managed and read-only wherever they're provisioned. *** ### How end users work: mobile and web apps Mobile and web apps are deployed independently of the backend — an app update doesn't require redeploying any underlying service, and the frontend scales separately from transaction processing. What an app actually does for a given user is determined entirely by product configuration and workflow, not hardcoded into the app itself: the same onboarding step sequence that orchestration defines is what the app walks a new user through, step by step, at sign-up. Apps resolve the calling user's identity server-side from their own session, rather than trusting a client-supplied identifier — the same request that reaches a capability's API from the console (where an operator can act on someone else's record) carries a different, higher-trust permission scope than the equivalent request from an end user's own app acting only on their own record. Both mobile and web apps are white-labeled to the operating institution, not to XYB — the branding is a configuration concern, the same as everything else at this layer. # Platform Authentication To securely use XYB APIs, you create **entity agents** in the XYB Console that are unique identities that represent your applications or services. You then generate a **public–private key pair** on your own system. Your **private key** stays with you and is used to sign short-lived **JWTs** (JSON Web Tokens). Your **public key** is then **registered in the console** by linking it to an agent. This allows XYB to verify JWTs you sign with your private key and authenticate API requests without sharing secrets over the network. ### **What do you need to do** To authenticate with XYB APIs, you: * Create an **agent** in the console which is a unique identity that represents your application or service. * Generate a **public–private key pair** locally. The **private key** stays with you to sign requests, and the **public key** is what you register with XYB. * In the console, **register your public key** by creating an API key entry linked to your agent. *** ### How to set up authentication #### 1. Create an Agent An *agent* is a unique identity representing your app or service. 1. In the **XYB Console**, go to **Entities**. 2. Click **New entity** and choose **App** (Application role). 3. Fill in: * **Name:** Friendly name for your application. * **Reference:** Unique identifier for your app.\ \ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-178a98b00cdd79fd3fd326a77ffd0449c68d78f2%2Fimage.png?alt=media) 4. Click **Create entity**. #### 2. Generate a Key Pair You must generate a **JWK key pair** (public/private key). Supported types include: * RSA (e.g. RS256) * EC (e.g. ES256) * EdDSA (Ed25519) Store your **private key** securely. #### 3. Register your Public Key in the Console Once you have your public JWK: 1. In the **XYB Console**, go to **API Keys** under **Admin**. 2. Click **+ New key**. 3. Fill in: * **Key name:** A label for your tracking (e.g., `Payroll Processor Prod Key`). * **Reference:** Auto-generated or custom unique ID for the key. * **Agent name:** Select the application entity you created. * **Public JWK key:** Paste your public key JSON.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-b621466ad02fcc9132fa4fff4ee31d68bc07c069%2Fimage.png?alt=media) 4. *(Optional)* You can also **Add expiration date** for when the key will automatically expire. Minimum 3 days from now. If left blank, the key will remain valid until you revoke or rotate it. 5. Click **Create key** and this registers your public key and links it to your agent. XYB can now verify JWTs signed with your private key. #### 4. Key Rotation and Revocation You can manage keys directly in the console: * **Rotate:** Replace the public key without downtime.\ During rotation, both the old and new keys remain valid for the set **transition period** (e.g., 30 days).\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-8056d25f318f11175a146634dade4b4f469d10c9%2Fimage.png?alt=media) * **Revoke:** Disable a key instantly if it’s compromised. * **One active key per agent:** At any given time, only one key is active, except during the rotation period. All key actions are logged for auditing. *** ### How to Authenticate a Request Each API request must include: | Header | Description | | ------------- | ------------------------------------ | | Authorization | `Bearer ` | | xyb-agent | Your registered agent identity | | request-id | *(Optional)* A unique ID for tracing | **JWT Payload Claims:** * `sub`: subject of the token * `iss`: must include the value of `xyb-agent` * `iat`: issued-at timestamp * `exp`: expiry timestamp (recommended 5–15 minutes) **JWT Header Claims:** * `alg`: algorithm used (e.g., RS256, ES256, EdDSA) * `kid`: key ID *** # XYB Banking Orchestration Platform - Overview XYB offers a banking orchestration platform: it lets you build or expand your financial product ecosystem by configuring composable components: **deposits and wallets**, **payments and FX**, **credit**, **interest**, and more. That means you can build a financial product stack from scratch, or add new capabilities to what you already run, without disrupting it. Around these capabilities sits a shared operating layer: **access control, product configuration, and an automation engine that any capability can plug its own actions and triggers into.** Connections to outside providers: payment rails, card networks, identity verification, run through adapters, so you can bring the providers you already work with, or switch one later, without touching anything else. XYB's capabilities are built to compose with each other from the start. They share one canonical model for the core objects (customer, account, transaction, balance), they all post through the same Ledger, and they can all register actions with the same automation engine. Adding a capability means configuring it against data that already exists, not building a new integration. |

EXAMPLE: A lending feature added to an existing wallet product

A fintech already uses XYB for customer wallets and the underlying balance records in the Ledger. They want to add a “pay in 3 installments” option at checkout.

  • They configure a new credit product: repayment schedule, interest terms, eligibility rules without touching how wallets or the Ledger are already set up.
  • When a customer takes the offer, the credit contract is created and the payments capability disburses the funds into the same wallet that already exists.

Result: one new capability was switched on; nothing already running had to be re-integrated.

| | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### How does the XYB platform work? The platform has three layers: * Component layer: the core capabilities (Deposits & Wallets, Payments & FX, Credit, Interest, and the Ledger) * Orchestration layer: shared services used by every capability: access control, product configuration, and an automation engine other services register actions and triggers with. * Experience layer: how everything above is actually surfaced to a person: the console, your customer web app, and your customer mobile app. Solutions aren't a fourth layer stacked on top: they're named combinations that draw from all three layers at once, packaged around a specific use case. Adaptive Digital Banking, for example, composes capabilities (Component), the workflows that connect them (Orchestration), and the customer-facing screens that result (Experience) into one named, buyable thing. |

Use Case: A company runs payroll for employees across multiple countries from a single payroll batch.

  • Component layer: Deposits & Wallets holds the company's funding balance, and Payments & FX executes each employee's payout.
  • Orchestration layer: a workflow routes each payment through the correct rail for that employee's country, swappable per corridor without changing the payroll product itself and holds any batch over a set threshold for a second approver's sign-off before release.
  • Experience layer: an operator reviews and approves large batches in the console, while the company's own finance team just sees "payroll sent" in their app, the rail differences per country stay invisible to them.

Result: one payroll run, many countries, and the only thing that changes per corridor is which rail handles it.


| | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### Where it's used Current documented use cases: * A full-stack digital bank: ledger, accounts, payments, and credit together. * Embedded payments inside another company's product. * Credit for e-commerce (buy-now-pay-later and similar). * A reconciliation layer sitting over an existing core banking system. * A fully white-labelled banking app. Adaptive Digital Banking (Solutions section) documents the first of these a full-stack digital bank as a worked example, including the specific capabilities it composes and a step-by-step tutorial.
# XYB Console - Quick Start Guide The **XYB Console** is your central workspace for building and operating financial products. It provides a visual interface for managing services, configuring product behavior, defining workflows, and assigning roles. {% hint style="info" %} **Note:** This guide is for **product managers** and **operators** using the Console UI. If you're a developer working directly with APIs, refer to the [XYB API Reference](/xyb-platform-1/accounts/apis-and-events/api-quick-reference-guide). {% endhint %} ### Parts of the Console XYB Console provides a set of **general features** available to all users and **core service areas** like **ledger, accounts, payments**, or **credit** that are provisioned based on your business needs. Click on the tabs below to learn more about each part of the Console. {% tabs %} {% tab title="Product Configuration" %} The product configuration layer in the Console lets you define not just what the product is, but also how it behaves throughout its lifecycle. You can: * **Create offerings** like current accounts, savings products, or revolving credit lines, tailored to customer segments. * **Predefine key settings** such as supported currencies, interest or fee structures, transaction limits, and more so you can deploy at scale with consistency. * **Link core services** like ledger behaviors, coordinate types, and account states directly into product blueprints to automate financial operations. [Learn more about Product Configuration.](/xyb-console/product-configurations) {% endtab %} {% tab title="Entities" %} Entities represent the core actors in your product ecosystem, such as customers, businesses, partners, and owners. In XYB, every financial relationship, transaction, or product is tied to an entity. * **Classify Entity Types**: Set up different entity roles like **Customer**, **Business**, **Partner**, or **Owner** based on their relationship to your financial product. * **Capture Core Identity Data**: Define required fields including names, personal or business identification (e.g., national ID, SSN), date of birth, contact details, and more. * **Segment by Sector and Use Case**: Tag entities by **sector** (e.g., fintech, retail) and **segment** (e.g., SMB, enterprise) to tailor product offerings and workflows. [Learn more about entities](/xyb-console/understanding-entities-in-xyb). {% endtab %} {% tab title="Workflows" %} The workflow engine in the Console allows you to design and automate operational processes across your financial stack. You can: * **Build workflows** for tasks like customer onboarding, identity verification, fund transfers, or payment approvals, reducing manual overhead. * **Define custom logic** and business rules that trigger based on system events, user actions, or external inputs. * **Connect internal systems** and third-party tools using configurable steps and conditions to orchestrate processes end-to-end. [Learn more about workflows.](/xyb-console/workflow-management) {% endtab %} {% tab title="Access Management" %} The access control layer in the Console helps you manage who can do what across your environments. You can: * **Define roles and permissions** for team members based on responsibilities and environments (e.g., sandbox or production). * **Apply fine-grained access controls** across services, product configurations, and operational workflows. * **Manage API keys** and secure integrations with third-party systems using built-in tooling. [Learn more about Access Management.](/xyb-console/access-and-permissions-overview) {% endtab %} {% endtabs %} ### Console Set Up Check out the video and detailed steps to understand how to set up the Console for your team. {% embed url="" %} #### 1. Assign Roles and Permissions When your Console is first provisioned, the **super admin** receives login credentials. This user is responsible for: * [Accessing the Console](/xyb-console/access-and-permissions-overview/access-management-dashboard) * [Creating and managing employee accounts](/manage-employees-roles-and-permissions) * [Assigning roles and setting permissions](/manage-employees-roles-and-permissions/create-roles-with-permissions) {% hint style="info" %} Roles can be assigned at various scopes per service, per environment (e.g., sandbox, production), or by workflow. Use the Access and Permissions Matrix to define access levels for teams managing services, workflows, or product areas. {% endhint %} *** #### 2. Verify Available Services Next, confirm that the services you’ve opted into are active in your Console. To do this: * Navigate to **Product Configuration < Services** * Review the list of available modules * Typical services include: * [**Accounts**](/core-banking-components/account-creation-and-management) * [**Ledger**](https://docs.xyb.co/xyb-platform-1/xyb-ledger/) * [**Entities**](/xyb-console/understanding-entities-in-xyb) * [**Product Configuration**](/xyb-console/product-configurations) Each service can be customized and integrated into your products. Once configured, those service settings are inherited by all products that use them. *** #### 3. Create Products with linked Services and Entities After roles and services are in place, begin designing your business architecture. * [**Create entities:**](/xyb-console/understanding-entities-in-xyb) These represent your customers, business units, or legal entities. * [**Define financial products**](/xyb-console/product-configurations)**:** Set up offerings such as savings accounts, credit lines, or payment wallets. * [**Configure workflows:**](/xyb-console/workflow-management) Automate processes like onboarding, verification, fund transfers, or approvals using the Workflow Builder. *** #### 4. Monitor and Operate in Real Time Once your products are launched, financial operators can use operational view to stay in control of daily activities: * **Track Core Metrics**: [Monitor account balances](/xyb-platform-1/accounts/account-management/managing-account-lifecycle-in-xyb), [ledger postings](https://app.gitbook.com/s/akJn6TxWIBAbZwLlYoVP/integrate-with-xyb-ledger/set-up-transaction-workflows/create-and-manage-postings), transaction histories, repayment statuses, and more in real time. * **Access Operational Dashboards**: Use [prebuilt and customizable views ](/xyb-platform-1/accounts/account-management/managing-account-lifecycle-in-xyb)to review service activity, customer behavior, and financial performance. * **Perform Manual Adjustments**: [Make operational entries when needed ](https://app.gitbook.com/s/akJn6TxWIBAbZwLlYoVP/ledger-use-case-and-operations)(e.g., balance corrections, backdated ledger movements) in line with permissions and audit controls. ### Additional Information The XYB Console also supports **orchestration workflows** to simplify multi-step configurations. These orchestration flows allow you to: * Automate the setup of products and services * Pre-define rules, templates, and activation steps * Launch preconfigured product bundles quickly Check out the video below to understand how you can create and manage products using orchestration tools. {% embed url="" %} ### Also check out: {% content-ref url="/pages/FEmhZdYkKdeSB2DSBGw4" %} [Product Configurations](/xyb-console/product-configurations) {% endcontent-ref %} {% content-ref url="/pages/9FrNyT33NmCUWQn1xhOQ" %} [Understanding Entities in XYB](/xyb-console/understanding-entities-in-xyb) {% endcontent-ref %} {% content-ref url="/pages/tckQvpeQ73DZ1C0FvVCS" %} [Workflows: Configure Operational Behaviors & Automations](/xyb-console/workflow-management) {% endcontent-ref %} # Platform Infrastructure ## **Platform Infrastructure: The Foundation of the XYB Platform** ### **Introduction** The **XYB Platform Infrastructure** serves as the backbone of the platform, ensuring **high availability, security, scalability, and flexibility**. It is designed to support **global banking operations** by leveraging **cloud-native technologies, automated deployment processes, and a robust networking architecture**. This article provides an **in-depth look** at how the **infrastructure is structured, managed, and optimized** to meet the needs of banks and financial institutions. *** ### **1. Cloud Deployment & Global Reach** #### **Supported Cloud Providers** The platform is designed to be **cloud-agnostic**, meaning it can be deployed on different cloud environments with **minimal differences in infrastructure design**. Currently, we support: **AWS (Amazon Web Services)** – Offers a wide range of banking-grade infrastructure and security controls.\ **GCP (Google Cloud Platform)** – Provides high-performance computing and analytics capabilities.\ **IBM Cloud (Limited Support)** – Available with shared management responsibility alongside IBM teams. #### **Multi-Region Failover & Redundancy** To ensure **business continuity**, the platform is deployed across **multiple regions**. This provides: * **Automatic failover** in case of regional disruptions. * **Load balancing** to distribute traffic for optimal performance. * **Disaster Recovery (DR) & Backup Strategies** to restore data in case of failures. **Key Benefit:** Banks can operate **globally** while ensuring local **regulatory compliance** and **minimal downtime**. *** ### **2. Infrastructure Components** The platform is built using **a modular infrastructure** that allows seamless deployment and scalability. Below are its core components: #### **2.1. AWS & GCP Account Setup** Each bank gets a **dedicated cloud account** configured with: * **Predefined IAM roles & security policies** for managing access. * **Isolated environments** for **production, testing, and sandboxing**. **Key Benefit:** Ensures **strong security** and prevents unauthorized access. #### **2.2. Kubernetes-Based Container Orchestration** The platform **runs all services in Kubernetes (K8s)**, providing: * **Automated scaling of workloads** based on demand. * **Self-healing capabilities**, ensuring high availability. * **Portability across cloud environments** with a standardized setup. **Key Benefit:** Efficient resource utilization, reducing **infrastructure costs** while improving performance. #### **2.3. Helm Charts for Standardized Deployments** * **All Kubernetes deployments** are managed using **Helm charts**, ensuring: * **Consistency** across AWS, GCP, and IBM Cloud. * **Automated infrastructure updates** for new features. * **Integration with CI/CD pipelines** for faster releases. **Key Benefit:** **Simplifies infrastructure management**, making deployments **repeatable and error-free**. #### **2.4. Networking & Security** The platform includes **strong networking controls** such as: * **Virtual Private Cloud (VPC)** – Isolates customer environments. * **Private networking & VPN support** – Ensures secure internal communications. * **DNS Routing & Load Balancing** – Optimizes traffic distribution. **Key Benefit:** **Reduces security risks** while ensuring **fast and stable connections**. #### **2.5. Secret Management & Encryption** * **API keys and credentials** are managed securely using **secret management tools**. * **Encryption standards** ensure **data protection at rest and in transit**. **Key Benefit:** Helps banks **meet security compliance** requirements with minimal effort. *** ### **3. High Availability & Scalability** The infrastructure is **designed for high availability** with: * **Auto-scaling mechanisms** that adjust **compute, storage, and networking** resources based on demand. * **Load balancing** to optimize traffic across multiple cloud regions. * **Database replication** with **read/write separation** to enhance performance. #### **Scaling Strategies:** | **Component** | **Scaling Mechanism** | **Benefit** | | ------------------------- | -------------------------------- | --------------------------------- | | Compute (VMs, Containers) | Auto-scaling groups in AWS/GCP | Optimized resource usage | | Storage | Dynamic provisioning | Cost-efficient scaling | | Networking | Load balancing & traffic routing | High performance | | Databases | Read/write replication | Faster queries & failover support | **Key Benefit:** Ensures **smooth banking operations** even during **traffic spikes or failures**. *** ### **4. Deployment & Automation (CI/CD Pipelines)** #### **4.1. Automated Deployments with GitOps** The platform follows **GitOps principles**, meaning all infrastructure changes are version-controlled and automated using:\ ✅ **GitHub Actions** – Automates testing & deployment.\ ✅ **ArgoCD** – Ensures **continuous delivery** of updates.\ ✅ **Helm & Kubernetes Operators** – Manages stateful applications efficiently. **Key Benefit:** Enables **fast and stable deployments**, reducing **manual errors**. #### **4.2. Standardized Environments** Each customer can have **multiple environments**: * **Sandbox** – For testing new banking products. * **Staging** – For pre-production validation. * **Production** – Live system for customer transactions. **Key Benefit:** Provides a **safe testing environment** before rolling out to customers. *** ### **5. Single-Tenant vs. Bring Your Own Account (BYOA)** Banks can choose how they want to deploy the platform: | **Deployment Model** | **Who Manages It?** | **Benefits** | | --------------------------------- | ---------------------- | ------------------------------ | | **XYB Cloud (Single-Tenant)** | XYB manages everything | Fully managed, low maintenance | | **Bring Your Own Account (BYOA)** | Customer’s IT team | Full control over cloud setup | **Key Benefit:** Offers **flexibility** in deployment and compliance management. *** ### *** ### # Video Tutorials and Demos In this section, you can find: * Product demos and walkthroughs * Feature highlights and use case deep-dives * Insights on modern financial infrastructure * Tutorials for developers and product teams * Updates on new capabilities and launches # Create a new product In this video, see how effortlessly you can design, configure, and launch a fully governed multi-currency account product that is custom-crafted to your business needs and ready to scale. From GBP as the core wallet to linked EUR and USD support, watch a seamless flow from product setup to mobile onboarding. Whether you're building for global users or streamlining your launch process, this demo shows the speed, flexibility, and extensibility you can expect. {% embed url="" %} # Onboard a new customer Experience real-time customer onboarding that's driven by product configuration, not custom code.\ In this demo, see how XYB enables seamless customer onboarding through a fully white-labeled mobile app. Starting from a selected product in the Console, we guide you through a setup flow that dynamically provisions identity, accounts, and wallets, all based entirely on product metadata. {% embed url="" %} # Top up a wallet In this demo, we walk through how a manual wallet credit flows through the system, from top-up in the consumer app to confirmation via orchestration. The customer initiates a manual GBP top-up, which triggers the wallet gateway to apply platform policies and instantly post the credit to the ledger. The wallet is updated in real time and immediately usable. We then verify the result in the console by checking balances and reviewing transaction logs.\ Finally, we use the orchestration agent to confirm the credit has propagated across all system layers, including metadata. This flow showcases our platform’s real-time consistency, governance, and composability, delivering a single source of truth for both users and operators. {% embed url="" %} # Adding New Wallets See how easy it is to add a new currency wallet to a multi-currency account, in real time, with no manual setup. In this demo, we: a) Use the mobile app to add a Euro wallet b) Trigger a €50 top-up using the orchestration tool c) Confirm wallet setup and funding in the admin console This end-to-end flow demonstrates how composable infrastructure allows for instant wallet creation, seamless orchestration, and full ledger integration, all in a matter of seconds. {% embed url="" %} # View Global Balances Get real-time visibility into wallet balances across currencies with XYB. In this demo, we showcase the Global Balance View, where GBP, EUR, and USD wallets are unified into a single, FX-resolved position. See how customers can drill into individual wallets, track transactions, and act instantly. Then switch to the Console to explore the same balances from an operational lens. No refreshes, no batch updates, you get live, ledger-backed data. {% embed url="" %} # Send Money to a New Beneficiary In this demo, we walk through the experience of adding a new beneficiary and sending a payment directly from the consumer app. The flow starts with selecting a currency, entering recipient details, and completing a real-time account validation. Once the beneficiary is created, we initiate a payment, review the exchange rate, and confirm the transaction that's processed instantly via SEPA Instant. The updated balances are reflected immediately, and full transaction details are available for review. This demo highlights how the platform brings together real-time orchestration, compliance, and user experience in one effortless flow. {% embed url="" %} # Explore the Use Cases # Get Started with XYB Console The **XYB Console** is a unified, web-based interface where you can design, configure, and operate financial services tailored to your business. It is built for product owners, compliance analysts, developers, or operations leads to bring all your financial operations and tools into a single cohesive environment. Through the console, you can manage the services you’ve subscribed to and access a wide array of **administrative and operational capabilities,** including **access control**, **task workflows**, and **financial configurations**. It is your centralized control center for launching and managing modern financial products, without scattered tooling. *** ## Manage Services and Design Products The console intelligently adapts based on the **services you've enabled**. For each service, it surfaces the relevant capabilities and gives you the flexibility to: * **Service management:** Customize configurations to suit your specific business needs * **Product Configuration:** Design financial products using modular product configuration tools. * **Workflows:** Orchestrate operations by linking services through no-code workflows. Whether it’s launching a new product, troubleshooting transactions, or managing accounts, the console ensures everything happens in one place. *** ## Admin & Operational Features Across all services, the console provides: * **Access Management**: Define roles, permissions, and visibility controls for different user types across your organization. * **Task Management**: Track pending actions, assign approvals, and orchestrate workflows involving your internal teams. *** ## Available Services ### Ledger You can create and manage both manual and bulk chart structures, review and add manual postings, and view balances, all within a fully transparent, real-time ledger. This gives you complete visibility and control over your financial data and accounting activity. [Learn more about using Ledger powered by XYB.](https://docs.xyb.co/xyb-platform-1/xyb-ledger/) ### Payments You can create customized payment products, such as **payouts to bank accounts** via ACH or SEPA, or **wallet-to-wallet transfers** for real-time peer transactions, and **define workflows** to manage how payments are processed. The console also lets you view and filter transaction history, cleared, failed, or pending with full traceability and audit-friendly identifiers.\ \ [Learn more about setting up payment systems and workflows with XYB.](https://docs.xyb.co/xyb-platform-1/xyb-payments/) ### Accounts You can design account products, such as a “Retail GBP Wallet”, directly in the Console by configuring default currency, jurisdictions, lifecycle rules, balance behavior, and access controls. These product templates are fully customizable using the Schema Builder, and you can view, manage, and operate all accounts created from them in one place. [Learn more about creating accounts and managing them using XYB.](/xyb-platform-1/accounts/getting-started-with-accounts/xyb-accounts-overview) ### Credit You can create a variety of credit products such as **loans**, **microloans**, **BNPL**, or **embedded finance offerings,** tailored to your business model. The console enables you to automate contract creation, configure credit terms, and manage the full lifecycle of each credit product from origination to closure. # Product Configurations The **Product Configuration** module is the powerhouse of the XYB Console, a central toolkit for designing, deploying, and managing financial products with both **precision** and **flexibility**. It empowers you to define every aspect of your product’s structure and behavior, giving your team full control from initial setup to production deployment. *** ## Core Components **1. Products** This is where you build modular financial products tailored to your use case. You can define how a product behaves, its constraints, and lifecycle parameters such as when it becomes active or archived. With built-in version control, teams can iterate safely while maintaining visibility into historical changes.\ Use cases include launching **wallets** for niche segments, rolling out **BNPL offerings**, or safely testing logic in staging environments before production deployment. **2. Services** Each product draws on backend logic powered by modular services like `cac-account-svc`, `cda-entity-svc`, or `cac-ledger-svc`. These services are intentionally decoupled, allowing for easier debugging, clearer ownership, and scalable deployments. Deprecated services are clearly labeled, ensuring teams use only current and supported modules. **3. Schema Builder** The Schema Builder is your tool for defining and managing configuration templates using editable JSON blueprints. You can create versioned schema definitions with labeled components and timestamps, perfect for experimenting, onboarding new teams, or aligning front-end behavior with service logic. This makes the platform flexible yet governed, with changes easily tracked and safely deployed. *** ## How it all Comes Together The Product Configuration module integrates deeply with the rest of the XYB ecosystem: * **Entities & Accounts** to tie products to real users * **Ledger & Payments** to enforce business logic for money movement * **Workflows** to automate events (e.g., disburse a loan after approval) Together, these integrations turn the module into a **digital product factory**, where your business logic, operational workflows, and technical architecture align. *** ## Why It Matters * **Full lifecycle control**: Manage everything from drafts to live deployments * **No-code configurability**: Built for product and operations teams * **Safe governance**: Versioned, timestamped, and transparent by design *** *** # Managing Products in the XYB Console The **Products dashboard** within the **Product Configuration** module is your central hub for creating, organizing, and managing all financial products across the XYB ecosystem. It lets you design products once, then attach services, schemas, and configurations that power their behavior across your platform. *** Products are modular building blocks that define the structure and lifecycle of financial offerings, like BNPL services, or savings accounts. Each product is a container for: * **Behavioral logic** (when it becomes active or archived) * **Attached services** (backend modules like ledger, entity, and account services) * **Schema configurations** (defining data and operational rules) *** The Products dashboard gives you full visibility and control over all your products. Key capabilities include: * **List View of All Products**\ Browse every product created across environments and services. Each product entry shows its name, reference ID, updated timestamp, owner, and current status (Active/Passive). * **Recently Updated Section**\ Quickly access products that were recently modified for rapid iteration and testing. * **Search, Filter & Sort**\ Filter by product name, reference ID, date range, or status to locate products instantly. * **Lifecycle Management**\ Activate or deactivate products as needed. Passive products are safely preserved without impacting live environments. *** To create a new product: 1. Click **+ New Product** on the top right. 2. Enter a **Product Name** (displayed in the dashboard). 3. Choose a **Product Reference** (auto-generated or custom). * This is the unique ID used by other XYB modules (Access Management, logs, APIs). 4. Add a **Description** to document its purpose or scope. 5. Click **Create product**. Once created, you can start attaching **services** and **schema configurations** to bring your product to life. > **Tip:** Use descriptive names and references to make products easy to identify when they’re consumed by other services. *** ### Importing Products If you have predefined product definitions, you can bulk import them: 1. Click **Import**. 2. Drag and drop your import file or select it manually. 3. Click **Import**. Imported products are added as **Passive** by default, so they don’t affect production until you activate them. *** ### Exporting Products You can export product configurations to share or version-control them: 1. Click **Export**. 2. Select up to 100 products from your dashboard list. 3. Click **Export products**. This produces a file containing your selected product definitions. *** # Workflows: Configure Operational Behaviors & Automations Workflows let you define how recurring operations behave and automate responses to key activities across the platform. They are available across core services like Payments, Ledger, and Credit allowing you to individually design how service-specific operations execute. For example, you can define how a payment flow is routed, how a credit check is performed, or how the ledger should record balance updates. In addition to these **service-level flows**, you can also create **automation workflows** that respond to system activity. These are useful for orchestrating cross-service reactions, such as sending an alert when a customer hits a credit threshold, triggering a task when a new entity is created, or updating account details after a role change. All workflows are created using a visual builder in the Console, making it easy to design logic without writing code.
*** #### **Service Workflows** Service workflows define how a system service behaves during execution. These workflows determine internal logic such as: * Which providers to call * What validation rules to apply * What data to fetch or ignore Examples: * **Payments:** Define execution paths, provider selection, fraud checks * **Credit:** Decide which credit bureaus to consult, scoring logic * **Ledger:** Define rules for how and when accounts are credited or debited #### 2. **Automation Workflows** Automation workflows respond to events that have already happened. These workflows allow operational teams to define what should happen next across services like task creation, notification, or account updates. Examples: * **Role Change:** Reassign tasks when an employee leaves a team * **Risk Closure:** Automatically close tasks linked to blocked customers * **Create Account:** Generate an account when a new entity is onboarded *** ### Key Features
Visual CanvasUse the drag-and-drop canvas to build logic flows using triggers, conditions, and actions.
Triggers and Actions
  • Internal events (like EmployeeDeactivated, EntityCreated)
  • Custom HTTP triggers or webhooks (future support)
  • Task actions (create, assign, update)
  • Account or wallet creation
  • Notifications
Execution Controls
  • Conditional logic
  • Branching and parallel execution
  • End nodes and pause/resume behavior
TemplatesStart faster using prebuilt workflow templates or create your own. Templates are reusable and save time on repetitive logic.
XYB Workflows are designed for: * **Operations Leads** who want to reduce manual work and improve reliability * **Compliance Teams** who need to enforce process-level rules * **Case Managers** who handle onboarding, KYC, or customer tasks * **Business Analysts** looking to prototype and validate improvements Learn more about: [Building Blocks of a Workflow](/xyb-console/workflow-management/building-blocks-of-a-workflow) [Automation Tutorial](/xyb-console/workflow-management/automation-tutorial-employee-offboarding-handoff) [Payment Workflows](/xyb-platform-1/xyb-payments/payment-workflows-and-automations/payment-workflow-overview) *** # Building Blocks of a Workflow Workflows in the XYB Console let you define how processes should unfold across the platform, whether it’s orchestrating payment logic, reacting to internal events, or automating task actions. Each workflow is designed visually, using an intuitive interface, and composed of modular building blocks called **nodes**. *** ### Getting Started To begin, navigate to the **Workflows** section and click **+ New Workflow**. You’ll be prompted to: * **Enter a workflow name** (e.g., *Standard Outbound Payment*) * **Optionally customize a reference** (used to programmatically identify this workflow) * **Add a description** that outlines the workflow’s purpose Once created, you’ll be taken to a **blank visual canvas**, which begins with a single **Start** node. *** ### Workflow Canvas and Nodes The workflow canvas is where you visually construct your process by connecting nodes that represent actions, conditions, or states. Each node is connected with arrows to define how data or execution flows from one step to the next. Learn more about: [Start & End Nodes](/xyb-console/workflow-management/building-blocks-of-a-workflow/start-and-end-nodes) [Trigger Nodes in Workflows](/xyb-console/workflow-management/building-blocks-of-a-workflow/trigger-nodes-in-workflows) [Task and Condition Nodes](/xyb-console/workflow-management/building-blocks-of-a-workflow/task-and-condition-nodes) # Start & End Nodes #### Start Node The **Start node** is the foundational block of any workflow in the XYB Console. It is automatically placed on the canvas when you create a new workflow and serves as the **entry point** for the workflow’s execution logic.
The **Start node** acts as the anchor of every workflow, it’s the point from which all logic begins and cannot be deleted. It doesn’t hold any configuration or logic itself but connects directly to a trigger node, such as an **Internal Event** or **Webhook**. #### End Node The **End node** is a **non-functional** marker that indicates the termination of a workflow path. While it does not influence the workflow’s behavior or execution, it plays an important role in improving **visual clarity**.
The **End node** marks where a branch or sequence of actions finishes, serving as a visual cue rather than a functional step. It doesn’t trigger actions or affect performance but helps teams quickly see where each process concludes. Use it in multi-branch or long workflows to make endpoints clear, improve readability, and prepare your workflow for easy review or documentation. # Trigger Nodes in Workflows Trigger nodes define the event that initiates a workflow run. Each workflow must have at least one trigger, which connects directly to the **Start node**. Depending on the workflow type (payment, automation, etc.), different trigger types are available. *** ### Types of Trigger Nodes #### 1. **Internal Event Trigger** Internal event triggers are based on system activity within XYB services. These are predefined events that originate from core services like Tasks, Ledger, Entity Management, and more.
Once you select an internal event, you’ll see the trigger options in the configuration panel on the right. Each event exposes **output variables,** such as `EmployeeId` or `EntityReference` which can be used in downstream nodes like tasks, conditions, or Slack messages. These variables are automatically populated when the event fires, allowing you to build dynamic and data-driven logic across your workflow
*** #### 2. **Webhook Trigger** The **Webhook** node lets you trigger a workflow from an external system by sending a POST request to a unique, auto-generated URL. This node is ideal for integrating third-party systems or custom apps into your automation flows. #### How It Works * When you add a Webhook node to your workflow, a Webhook URL is automatically generated. * This URL is specific to that workflow version, and cannot be edited. * You can copy and share this URL with any external system that should trigger the automation. * The workflow starts every time a valid POST request is made to this endpoint with the correct authentication and payload format.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-746613cfce90a02133f4e4d5000f9dd66fc0d902%2Fimage.png?alt=media) #### What You Need To Do 1. **Add a Webhook node** in your workflow (after the Start node). 2. A **Webhook URL** will appear automatically. 3. Paste a **sample JSON payload** in the `Sample payload` section. * This helps extract and configure **output variables** automatically. * These variables can then be used in downstream nodes (e.g., Slack, Task, Code, etc.) *** ### Connecting Trigger Nodes * **Placement**: Always connect directly to the **Start node**. * **Next Steps**: From the trigger node, add action or task nodes to define what should happen once the event fires. *** # Task and Condition Nodes Task and Condition nodes are used to add **human review** and **decision-making logic** to automated workflows.\ They allow your workflow to pause for manual verification (Task) or branch based on certain criteria (Condition). *** ### Task Node A **Task node** creates a manual or system-assigned task during the workflow, often used for checks, approvals, or reviews. *** #### Key Fields in the Task Node | Field | Description | | -------------------- | -------------------------------------------------------------------- | | **Task Type** | The kind of task to create. | | **Task Priority** | Defines urgency: `LOW`, `MEDIUM`, or `HIGH`. | | **Entity Reference** | Links the task to a specific record (e.g., employee, case, request). | | **Input Variables** | Dynamic data passed from earlier nodes | | **Task Description** | The message or instructions shown to the reviewer. | *** ### Condition Node A **Condition node** evaluates one or more logical statements and routes the workflow accordingly, for example, “If this variable is true, go this way; otherwise, go that way.” **Key Fields in the Condition Node** | Field | Description | | ------------------- | ------------------------------------ | | **Input Variables** | Variables available for logic checks | | **Variable** | The specific variable to check | | **Operator** | The condition to apply | # Automation Tutorial - Employee Offboarding Handoff This automation is used to create and assign a follow-up task automatically when an employee is disabled in the system. It helps ensure that responsibilities owned by the deactivated employee are reviewed or transferred, so nothing gets left behind. When an employee is disabled, the system detects this internal event and automatically creates a follow-up task. The task is assigned directly to a specified user or group for further action, such as reviewing and reassigning the disabled employee’s responsibilities.. #### Step 1: Start a New Automation 1. Navigate to **Workflows < Automations**. 2. Click **+ New Automation**. 3. Fill in the details:
* **Automation name**: Employee Offboarding Handoff * **Automation reference**: You can leave it as the default unless you need a custom reference. * **Description**: Write a simple description of the workflow. 4. Click **Create automation**. #### Step 2: Add the Trigger 1. On the canvas, click the **Start** node and select **Internal Event**.
2. Choose the trigger: **Employee is disabled**.
2. The event will expose the following variables: * `{EmployeeEmail}` * `{EmployeeId}` * `{EntityReference}` 3. Click **Save** #### Step 3: Create and Assign the Task 1. Click the **+** button next to the event node. 2. Select **Task** < **+Add**
3. In the Task window, select the **Change assignee** tab. 4. Provide the **Reassign from** email variable and the **Assign to** email/variable. In this tutorial, we're assigning the review task to the operations team.
5. Provide the instructions under **Task description** and click **Save**. 6. Once the steps are configured, click **Activate** in the top-right corner of the screen. **Result** When an employee like is deactivated: * The automation is triggered. * A task is immediately created and assigned to the operations team. * The task includes context about the deactivated employee for easy follow-up. # Workflow Version Control Workflow versioning gives you full control over how and when your logic changes go live. From drafting and reviewing to activating or ending a version, this article outlines how to manage your workflow lifecycle effectively. *** ### Creating a New Draft Version To make updates to an already activated workflow: 1. Go to the **Workflows** section. 2. From the `...` menu next to an active version, select **Copy as draft**.
A new draft version will be created with the same nodes as the source version. This draft can now be edited safely without affecting the active version. > **Note:** Additionally, the user can also create a new draft from the **New draft** button above the Versions list. This will create a clean draft to start a version from scratch. > > Each workflow can have only one active draft at a time. If a draft already exists, you’ll need to delete it to create a new one. *** ### Activating a Draft Version Once you’ve finished editing a draft: 1. From the `...` menu , click **Activate** and on the confirmation screen and the draft becomes the **Active** version.\\
**Note:** You can only have one **Active** or **Suspended** version at a time. Trying to activate another version will result in an error unless the existing one is ended or deleted. *** ### Suspend a Version 1. From the `...` menu, select **Suspend** to temporarily pause a workflow version.\\
2. Click **Pause** in the confirmation screen. No new runs will be triggered while suspended, but current runs will complete.\ \ Suspended versions can later be **resumed** or **ended**, depending on your use case. You cannot activate another version while you have a version suspended. Terminate the version to activate another one. ### Terminating a Version You can choose to manually end a version without activating a new one: * From the `...` menu of an active or suspended version, click **Terminate**. * The version status updates to **Ending**, indicating it won’t accept new runs.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-787a1b6e501b2c5081331c10e475539241384693%2Fimage.png?alt=media) * Background polling ensures that once all active runs complete, the status changes to **Terminated** automatically. *** ### Deleting Versions Drafts can be deleted anytime by clicking **Delete** from the `...` menu. Only **draft versions** can be deleted and deleting a draft will also delete the workflow if no other versions exist. **Note:** Once a version has been activated (and after that suspended), it can no longer be deleted, only **terminated**. This is because there may already be runs associated with it, so it cannot be removed entirely. *** ### Things to Remember * Each workflow can only have **one draft version** at a time. * Approval-based workflows will enter an **In review** status until approved. * You can always track the status of each version (Draft, Active, In review, Terminated, Suspended, Deleted) from the **Versions** table.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-b3307c03472ccc1ef8d8dae377abe214ed36f90d%2Fimage.png?alt=media) # Track Live Stats and Errors for Workflows Once a workflow is active, it's essential to monitor how it's performing in real time. The **Runs** panel gives you complete visibility into execution trends, failure rates, and active run statuses, all directly from the canvas. You can track workflow performance and investigate run-level behavior from two key views: **1. Canvas View (Workflow Designer)** When viewing a workflow version on the canvas, click the **Runs** toggle in the top-right corner to open the **Runs** panel.
Here you can view: * **Success rate:** the percentage of completed runs that ended successfully. * **Velocity:** how many runs are processed per minute. * **Completed and In-progress runs:** each entry shows status (success, failure, stopped), duration, and timestamp. You can also: * Click on any run to inspect its details. * See failure reasons or retry failed/stopped runs from the actions menu. * Use filters (e.g. "Last 24 hours") to scope the data by time window. **2. Versions Table** From the **Workflows** list view, each version row shows a summary of: * Runs that were **Successful** * Runs **In progress** * Runs that **Failed** * Average **Velocity** (runs/min)\\
Clicking into a version brings you to the canvas with full run logs and flow visualization. #### Investigating Failures Failed or stopped runs are clearly marked with red icons. You can view" * Error messages with stack trace or failed endpoint * Task that caused the error * Option to **Retry** the run or **Stop** if still in progress This makes it easy to quickly identify issues such as: * Misconfigured webhook URLs * Timeouts * User-stopped executions
# Roles & Permissions Overview - For Admins Before you create a permission or build a role, it helps to understand how the two fit together and how they show up for your users once assigned. This page covers the concepts; the step-by-step guides for creating permissions and building roles are linked at the end. ### The two building blocks **Permissions** are the smallest unit of access. Each one grants a single, specific capability on a single service for example, the ability to view invoices, or the ability to edit a payment specification. On their own, permissions aren't assigned to people; they're assigned to **roles**. **Roles** are named bundles of permissions that map to a job function: Treasury Analyst, Client Services, Auditor, and so on. You assign roles to employees, not individual permissions. This is what makes access manageable: instead of deciding "does this specific person get 40 individual permissions," you decide "which role does this person's job match," and the permissions come along with it. A useful way to think about it: **permissions describe what can be done; roles describe who gets to do it.** ### How permissions are structured Every permission belongs to a service and follows the pattern: ``` / ``` For example: `pay-invoice-svc/invoice_w` The code ends in a suffix that tells you what kind of access it grants: | Suffix | Meaning | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `_r` | Read: view data, no changes | | `_w` | Write: create, edit, or perform an action | | `ui_r` (occasionally `mfe_r` on older services) | Controls whether a menu item or screen is visible at all, separately from whether the underlying data can be read | That last one is worth pausing on, because it explains behavior your users will notice directly: a person can have `ui_r` for a section (so they see it in the navigation) but not have the `_w` permission for a specific action inside it — in which case the button is still visible, just disabled, usually with a tooltip explaining why. Conversely, no `ui_r` at all means the whole menu item disappears rather than showing up disabled. This is intentional and consistent across the platform, so once you know the pattern, permission-related UI behavior stops looking inconsistent and starts looking predictable. #### Two kinds of permission Most permissions are **static** a flat yes/no on a capability, like `pay-invoice-svc/invoice_w`. Some are **dynamic**, meaning they're scoped to a specific resource or set of resources rather than being all-or-nothing: ``` /@// ``` For example: `plt-workflow-svc/read@/family/**` (read access to all workflow families) or `cac-account-svc/read@/account/*` (read access scoped to accounts). Dynamic permissions are how you grant access to *a category or subset* of resources rather than every resource a service manages. One thing dynamic permissions are **not**: a way to gate access by a business value or threshold (e.g. "approve payments over $10,000"). That kind of rule lives in policy configuration elsewhere in the platform, not in the permission string itself. ### How roles work in practice When you build a role, you're choosing a set of permissions often spanning several services that together represent everything a job function needs and nothing it doesn't. A Payment Operations role, for instance, typically needs write access to payment entry, beneficiaries, and payment sessions, but should *not* include the permission to approve those same payments that belongs to a separate approver role. That separation isn't just tidiness. It's the mechanism behind **segregation of duties**: keeping the person who initiates an action and the person who approves it as two different roles, so no single person can do both. The same logic applies elsewhere the team managing platform configuration typically shouldn't also hold payment or approval rights, and the team administering access and roles typically shouldn't be able to transact either. If you're designing roles for a regulated or higher-risk environment, it's worth explicitly mapping out which roles must never be held by the same person, not just which permissions each role needs. #### Console roles vs. webapp roles Roles come in two flavors, and they're not interchangeable: * **Console roles** are ones you create and manage yourself, for people using the admin console. * **Webapp roles** are fixed roles built into the platform for people using the customer-facing webapp (e.g. an "Admin," "CFO," "Treasury Manager," or "Owner" persona for the business using your banking product). These are pre-defined and can't be edited you assign them, but you don't customize what's inside them. If you're trying to change what a webapp user can do, that's a different lever than editing a console role worth knowing before you go looking for an edit button that isn't there. #### A note on sensitive permissions Not every permission needs to live inside a standard role. Highly sensitive ones access to raw card details or PII that would normally be masked, for example are often deliberately left out of every role and instead granted only through a time-boxed, audited exception process when genuinely needed. If you have permissions like this in your catalog, it's worth deciding upfront that they're "break-glass only" rather than folding them into a role by default. ### Putting it together A rough mental checklist when setting up access for a new function: 1. **Identify the job function** (e.g. "Reconciliation Ops") and what it actually needs to do read invoices? Approve payments? Configure products? 2. **Check whether existing permissions cover it.** Most core permissions already exist per service. 3. **Create custom permissions only for gaps** a genuinely new capability that doesn't map to an existing one. 4. **Build a role** that bundles exactly the permissions that function needs no more. 5. **Check for conflicts** does this role, combined with any other role the same person might hold, cross a line you don't want crossed (e.g., maker + checker)? 6. **Assign the role**, not individual permissions, to people. # Access Management Dashboard The Admin Console section of the platform provides a **centralized way to manage users, roles, and permissions**, ensuring secure and controlled access to the platform features. This section helps administrators configure user access, enforce security policies, and customize system settings to align with their organization's needs. ![](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAFSGiQTIBWtkOYVzQXi%2Fuploads%2FKoIxS4XbmSl8kHRY52ik%2Fimage.png?alt=media\&token=6faf3251-c341-4538-843c-d78759cbf2ec) ### Access Management CommentGive feedback on the editorThe **Access Management** module allows administrators to control who can access different parts of the platform and what actions they can perform.CommentGive feedback on the editor * CommentGive feedback on the editor**Employees** – View, add, and manage platform users (e.g., employees, auditors, and system operators). * CommentGive feedback on the editor**Roles** – Define role-based access control (RBAC) to ensure users have appropriate permissions based on their responsibilities. CommentGive feedback on the editor**Use Case:** An admin can assign a **Finance Manager** role with access to **Ledger Balances and Reports**, while a **Support Agent** might only have access to transaction inquiries. *** **Employee & Role-Based Permissions** CommentGive feedback on the editorEvery employee or user in the system must be assigned a **role**, which dictates their access level.CommentGive feedback on the editor * CommentGive feedback on the editor**Admins** can create **custom roles** or use predefined templates. * CommentGive feedback on the editorPermissions include **viewing, editing, and managing transactions, reports, or ledger entries**. * CommentGive feedback on the editorEnsures **audit trails** and security compliance by restricting sensitive actions to authorized personnel. **Use Case:** A **bank administrator** can create a **"Read-Only Analyst" role** for auditors, allowing them to view data but not modify transactions.\\ # Understanding Entities in XYB Entities are the foundational building blocks in XYB that represent all participants involved in your financial ecosystem. Whether you're onboarding a customer, setting up a business account, or integrating a third-party partner, each is modeled as an entity. Entities help structure your operations, define relationships, and enable service provisioning across your product workflows. #### Types of Entities XYB supports five types of entities: * **Customer**: Individual users using your financial services (e.g., account holders, borrowers). * **Business**: Legal or commercial organizations using your platform (e.g., SMEs, vendors). * **Partner**: External systems or institutions connected to your platform (e.g., banks, KYC providers). * **Owner**: Internal or admin-level operators with control over configurations and operations. * **App:** App entities are typically used for system-to-system authentication and are linked to API keys for secure request signing. #### Create new entities Entities power everything from account creation and payment routing to credit assessments and compliance. They act as the core data objects that link services like ledger accounts, cards, and workflows. When you create an entity, you're enabling the backend to enforce rules, attributes, and connections associated with that person or business.
When you create a new entity, you need to provide the basic details based on the type of entity you create. * Choose entity type (Customer, Business, Partner, Owner, App) * Enter personal/business identifiers (e.g., name, national ID, date of birth) * Specify the sector and segment * Provide contact info (email, phone) #### Managing Entities You can view and manage all entities directly from the **Entities** page in the Console.\ The **entity view** lists key information such as the entity’s reference ID, name, role, country, creation and update timestamps, and status. You can use filters to narrow results by **segment**, **role**, **country**, **date range**, **app access**, or **status**. {% hint style="success" %} **Each entity includes an App access status, which you can view or update to reflect whether the customer or application currently has access to your services.** {% endhint %} From the entity view, you can also: * Open individual entity details to review attributes, relationships, and activity. * View associated services such as accounts or workflows. * Identify **Active**, **Inactive**, or **Deleted** entities at a glance. This view provides a centralized overview of all participants in your ecosystem, making it easier to monitor entity health, troubleshoot access issues, and manage lifecycle changes. # Approvals and Policies Approvals and Policies work together to ensure that important changes in the system are controlled, reviewed, and securely authorized before they take effect. This helps your organization maintain compliance, reduce errors, and add accountability to critical workflows. *** ### What are Approval Policies? An **approval policy** defines the rules for when an approval is required and who needs to approve the request. * **Trigger:** The specific service and event that activate the policy (e.g., a product version status change). * **Attributes:** The type of change that requires review (e.g., moving a product version from *Active > Expiring*). * **Approvers:** The employees or roles responsible for reviewing and approving the request. * **Minimum approvals:** The number of approvals needed for the request to proceed. *** ### What are Approval Requests? An **approval request** is automatically generated whenever a change matches the conditions set in a policy. * It contains details of the change (e.g., which product version is being updated, and what status is changing). * It lists the employees who are eligible to approve. * It tracks the status of the request (Pending, Approved, Rejected, Terminated). Approval requests are the *instances* that result from applying a policy to a real change in the system. *** ### How They Work Together 1. **Policy is defined:** An admin sets up an approval policy, specifying the conditions and approvers. 2. **Change is initiated:** A user performs an action (e.g., updates a product version). 3. **Approval request is generated:** The system checks the policies, creates a request, and assigns approvers. 4. **Approvers review:** Designated employees review the request details and either approve or reject. 5. **Outcome is enforced:** If the required approvals are met, the change is applied. Otherwise, it is blocked. *** ### Why They Matter * **Security & Compliance:** Ensure sensitive actions (like publishing, expiring, or modifying product versions) are properly reviewed. * **Accountability:** Create a clear record of who approved what and when. * **Control & Governance:** Prevent unauthorized or risky changes by requiring review from the right people. * **Transparency:** All approval activity is logged and viewable in the Approvals dashboard. *** With Approvals and Policies in place, your organization can confidently manage changes while staying compliant and secure. # Creating and Maintaining Approval Policies Approval policies let you control which actions in the system require review and who must authorize them. By setting up policies, you ensure that sensitive changes (such as product version updates) go through the right checks before being applied. *** ### Creating a New Approval Policy Follow these steps to create a new policy: #### 1. Navigate to Policies * Go to **Admin > Approvals > Policies**. * Click + **New Policy**. #### 2. Add Policy Details * **Policy name:** Enter a descriptive name (e.g., *Product version status change*). * **Policy reference:** Either use the system reference or create one manually. #### 3. Configure Triggers Approval policies are triggered by a **service** and an **event**.\\
* **Service:** Select the service where the policy applies (e.g., *Product configuration*). * **Internal event:** Select the event that requires approval (e.g., *Version status changed*). * **Attributes:** Define which specific changes should trigger approval (e.g., *DRAFT to ACTIVE*, *ACTIVE to EXPIRING*). #### 4. Assign Approvers * Search and add one or more employees who will act as approvers. * Approvers will receive approval requests when the policy is triggered. #### 5. Set Minimum Approvals * Define the minimum number of approvals required (e.g., 1 or 2). * The system enforces this rule before the change can proceed. #### 6. Save Policy Click **Save** to activate the policy. It will now apply automatically whenever the defined event occurs. *** ### Editing an Existing Policy * Go to **Approvals > Policies**. * Click the Edit icon next tot the policy you want to update. * Make changes to triggers, approvers, or approval requirements. * Save your changes.\ **Note**: Editing a policy affects future approval requests but does not retroactively change already-created requests. *** ### Tips & Best Practices * Use **clear names** for policies so approvers can quickly recognize what they cover. * Keep **approver lists up to date** to reflect team changes. * Use **multiple approvers** for high-risk changes. * Regularly **review and retire unused policies** to keep the system clean and compliant. # Managing Approvals in the Approvals Page The **Approvals page** is where approvers and requesters can monitor and act on approval requests. It provides full visibility into pending reviews, completed actions, and the history of who approved what and when. *** ### Accessing the Approvals Page * Navigate to **Approvals < Requests** in the console. * The page has two main views: * **To Review:** Requests waiting for your decision. * **Sent:** Requests you initiated that are currently in progress or completed. *** ### Reviewing Requests #### 1. Filtering and Searching * Use filters to narrow down requests by: * **Status** (Pending, Approved, Rejected, Terminated). * **Service** (e.g., Product configuration). * **Date range** (when the request was created). * Use the search bar to find requests by entity or policy name. #### 2. Viewing Request Details Click a request row to open the details page: * **Summary:** What change is being requested (e.g., *Product version Draft > Active*). * **Approvers:** List of designated approvers, with indicators showing who has approved, rejected, or is still pending. * **Requester:** The person who initiated the change. * **Activity log:** Timestamped record of all actions taken (request created, approvals, rejections, termination). * **Change details:** Side-by-side view of old and new values. *** ### Approving or Rejecting #### Approving * Click **Approve**, add a short note, and confirm. * Once the minimum required approvals are collected, the request status changes to **Approved** and the action is executed. #### Rejecting * Click **Reject**, provide a reason, and confirm. * If any approver rejects, the request status changes to **Rejected**, and the action is blocked. **Note:** If you are the requester, you cannot approve your own request. *** ### Understanding Request Statuses * **Pending:** Waiting for approvals. * **Approved:** Enough approvals collected; action has been carried out. * **Rejected:** One or more approvers rejected; action is blocked. * **Terminated:** Request ended manually or automatically (e.g., if the related policy was retired or action canceled). *** ### Tracking Approvers * Each approver’s decision is shown in the request details. * Approvers who have acted display as **Approved** or **Rejected** with a timestamp. * Approvers who haven’t acted yet remain in **Pending**. * If the requester is also listed as an approver, they are marked as **Requester** and cannot approve. *** The Approvals page gives you full control and transparency into every approval request, ensuring sensitive actions only proceed once they have been properly reviewed. # Create and Manage Tasks **Task Management** in the XYB Console helps teams **organize, execute, and track operational work** in a structured and transparent way. Tasks can be created, assigned, updated, and completed, ensuring that no action items are missed and all responsibilities are clearly defined. ### Use Cases Tasks support a wide range of operational and business processes. Some common use cases include: * **Operational process tracking:** Monitor and complete tasks such as loan processing, contract reviews, onboarding checks, or payment approvals. * **Exception and alert handling:** Automatically convert alerts such as ledger anomalies or failed validation checks into tasks that can be tracked, assigned, and resolved. * **Cross-team collaboration:** Assign tasks to the right team members, set clear priorities, and track ownership to ensure nothing falls through the cracks. * **Compliance and audit readiness:** Maintain a complete record of who did what and when, including comments, file uploads, and status changes, for easy audit preparation and traceability. * **Performance visibility:** Use the task list to get a clear overview of pending work, completed actions, and progress across different projects and workflows. ### Create Task Types Before users can create manual tasks, **task types must be defined**. Task types determine how work is categorized (for example, Contract Review, Payment Review, Entity Review, or any other custom type your organization needs). 1. Navigate to **Tasks** > click the **“⋯” (More options)** button in the top right corner. 2. Select **New task type.** 3. In the **New Task Type** form:\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-808d44b153693bc4281cafa153cc5426c55ea149%2Fimage.png?alt=media) * **Name:** Enter a clear, descriptive name (e.g., Contract Review, KYC Follow-Up). * **Entity:** Toggle this on if the task type should include entity-related details. * **Associate with:** Link the task type to an entity type such as Account, Contract, Ledger, or Payment. 4. Click **Create task type.** The new type will now appear in the **task type dropdown** when creating a new task. #### To manage task types: 1. Navigate to **Tasks > ⋯ > Manage task types.** 2. View all **Active** and **Inactive** types. 3. Archive unused types as needed. ### How to Create a New Task 1. **Go to the Tasks section:** From the main navigation menu, select **Tasks**. 2. Click **New Task**, this opens the task creation window.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-da9c1a5c8dd21809032902f493b8ea351da7380c%2Fimage.png?alt=media) 3. Under **Task Type**, choose from the predefined options, such as **Manual Review**, Contract **Review**, **Entity Review**, or **Payment Review**. Selecting the right type helps categorize and filter tasks later. 4. Based on the task type you select, you'll be prompted to link it to the applicable entity, select the entity and other details as asked. 5. Clearly describe what needs to be done, including relevant context, links, or instructions. 6. Choose the appropriate **priority level** (Lowest, Low, Medium, High, or Highest) based on urgency and impact. 7. Click **Create Task** to finalize. The task will now appear in the task list and can be tracked from there. *** ### Creating and Managing Task Permissions Before users can access or edit specific task types, appropriate permissions must be created in **Access management > Permissions**.\ Refer to the general [Creating a New Permission ](/manage-employees-roles-and-permissions/define-permissions)article for detailed steps. When setting up permissions for tasks: * Select **Task** as the service. * Task permissions follow the format: ``` bko-task-svc/@/task/ ``` Example: `bko-task-svc/read+write@/task/CONTRACT_REVIEW` grants read and write access to *CONTRACT\_REVIEW* tasks. * Task type names must be written in **UPPERCASE**, with underscores if needed (e.g., `ENTITY_REVIEW`). * The **wildcard** `*` can be used to apply the permission to all task types. * Default permission provided by the system: ``` bko-task-svc/read+write@/task/* ``` ### Managing Tasks After tasks are created, they can be monitored and updated in the **Task List View**. #### Viewing and Filtering Tasks * Access the full list of tasks under **Tasks**. * Use filters to narrow results by **priority, type, assignee, status, or date range**. * Switch between **“Assigned to you”** and **“All tasks”** views. #### Working with a Task 1. **Open a task:** Click on a task to view its details. 2. **Review information:** Check the description, related entity details, and any attachments. 3. **Assign or reassign:** If unassigned, assign it to a team member. 4. **Update status:** Change task status as it progresses (Open < In Progress < Resolved < Closed). 5. **Add comments or files:** Use the comment field to provide updates or attach relevant documents. 6. **Review activity history:** View timestamps, status changes, and comments for a complete audit trail. *** # File Vault The File Vault provides a central location in the XYB Console for uploading, viewing, and managing reconciliation data files such as external bank statements or partner reports. These files serve as input to reconciliation workflows, which compare external transaction data against ledger balances in XYB. The feature ensures that statement files are stored securely, versioned correctly, and automatically made available for reconciliation processing. *** ### Use cases | Use case | Description | | -------------------------- | -------------------------------------------------------------------------------------------- | | Uploading bank statements | Upload daily or monthly CSV files containing transaction or balance data for reconciliation. | | Partner or PSP settlements | Store partner-generated data files for reconciliation against ledger entries. | | Audit and reporting | Download or verify previously uploaded statements for audit and compliance purposes. | | Issue resolution | Replace or correct statement files when data needs to be updated or reprocessed. | *** ### Overview File Vault allows users to: 1. Upload statement files in CSV format. 2. Validate files against the prescribed reconciliation schema. 3. View stored files with key metadata including upload date, uploader, and date range. 4. Download or replace existing files as needed. 5. Automatically make uploaded files available to reconciliation workflows. *** ### Uploading a file 1. In the XYB Console, open **Platform > File Vault**. 2. Select **Upload file**. 3. Choose **Statement** as the file type. 4. Drag and drop the CSV file or use **Choose file** to select it from your system. 5. Optionally, add a short description. 6. Select **Upload**. After a successful upload, the file appears in the list view with details such as name, size, date range, file type, and upload date. *** ### Viewing and managing files Each file in the File Vault displays the following information: | Field | Description | | ------------------------ | --------------------------------------------------------------- | | **ID** | Unique identifier for the file. | | **Name and description** | File name and any additional description provided. | | **Size** | File size in bytes or kilobytes. | | **From / To** | Date range of transactions or balances included in the file. | | **Type** | File category (for reconciliation, this should be *Statement*). | | **Updated** | Timestamp and user who last updated or replaced the file. | To replace a file, select the **edit** option next to the record and upload a revised CSV.\ The previous version is overwritten, and the updated file becomes the active version.\ To download a file, select the **download** option next to the record. *** ### File validation All uploaded files are validated before being accepted.\ Validation checks include: * File format must be CSV (`.csv` extension). * Required columns must be present. * Column data types and date formats must be correct. If validation fails, an error message is displayed describing the issue.\ The file can be corrected and re-uploaded. *** **Supported formats and limits**
SettingValue
File typeCSV
Maximum file size25 MB (default limit)
EncodingUTF-8
Version controlLatest version replaces previous
Event handlingAn internal event is generated for every upload or update
*** ### # Data Deletion Requests in Console XYB console supports a policy-controlled data deletion process that enables institutions to comply with privacy regulations such as the General Data Protection Regulation (GDPR) and similar frameworks. You can initiate and manage data deletion requests governed by applicable approvals to ensure sensitive actions like removing personal data are audited and reviewed by the appropriate stakeholders. Typical use cases are the following: * A customer requests deletion of their personal data ("right to be forgotten"). * You need to clean up test or outdated entity data in your environment. * Internal compliance reviews prompt the removal of inactive or expired records. #### How to Request Deletion for an Entity If you need to delete data for a specific customer, partner, or other entity: 1. Under **Entities**, navigate to the specific entity you want to delete data for. 2. In the entity’s profile, click the **three dots (`⋯`)** in the top right corner.\\
3. Select **Request data deletion.** This creates a data deletion request and routes it through the appropriate approval process. *** #### What Happens After the Request 1. The request appears immediately in the Data deletion requests dashboard under Compliance and Privacy. The request will remain in a **Pending** status until approved by one of the assigned approvers.
2. If you're set as an approver, select the data deletion request to view the entity details. Review the deletion request and click the **three dots (`⋯`)** in the top right corner. You can select **Delete immediately** to remove the info permanently or select **Cancel Request** to retain the data in the system. Note that the **requester cannot approve their own deletion request,** only assigned approvers can. Once the approval request is approved, the data deletion request moves into a **Queued** status.\ The system then performs the deletion automatically after a configured delay (default: **4 hours**).\ The scheduled deletion time is displayed in the UI. #### Generate Data Deletion Report Additionally, you can also get detailed reports on deleted data including entity information, who initiated the request, and approval and deletion timestamps. 1. In the Data Deletion Request item, click **Generate report** post deletion.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-5f91563feb446d8e35aedca38eaf41bb03b42e81%2Fimage.png?alt=media) 2. Select the applicable template, language, and click **Generate report**. # Customer Communications **Customer Communications** brings together all outbound messages triggered across the XYB platform as part of day-to-day operations. This includes notifications, welcome emails, one-time passwords, payment reminders, and any other messages sent to customers during their lifecycle. All of these **messages are centralized in one place**, allowing you to track every outbound communication that is triggered at any stage, from onboarding to ongoing account activity. Messages can be configured during initial product setup, defined within workflow configurations, or triggered directly by your own external applications integrated with the XYB platform. Regardless of how they are initiated, all messages flow through the same messaging system, giving product and operations teams a single view for delivery, tracking, and status reporting. **Typical flow:** **Platform event > Message trigger > Email or SMS sent > Message appears in the Communications console**
*** ### Where messages come from Messages can be initiated from three sources inside the XYB platform. | Source | What it does | Examples | | --------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Product workflows** | Send messages during standard customer journeys | Login OTPs, onboarding emails, loan approval notifications, payment reminders | | **Platform services** | Automatically send messages as part of built-in platform logic | Authentication sending verification codes, Credit sending contracts, Payments sending receipts | | **Your applications** | Your backend systems trigger messages using XYB messaging APIs | Custom alerts, partner notifications, or bespoke workflows | All three sources use the same delivery channels, templates, and tracking system. ### Communications Tab The **Communications** tab in the XYB console shows all messages sent across your environment.
Each message includes the following key fields:
FieldDescription
Message IDUnique identifier for the message instance. Used for support, auditing, and troubleshooting.
Entity referenceInternal reference for the entity associated with the message (for example, a customer, account, or transaction).
ToDestination for the message. This may be an email address, phone number, or device identifier depending on the channel.
TypeChannel used to send the message: Email, SMS, or Push.
CreatedDate and time when the message was triggered.
StatusCurrent delivery state of the message: Sent, Delivered, or Failed.
This ensures every communication is fully traceable from trigger to delivery. *** ### Entity view You can also view message history for an individual customer or account directly on their profile. This view is useful when: * handling support tickets * confirming whether a message was delivered * reviewing recent interactions It shows all messages related to that specific record, giving support teams full context without needing to search across the entire system. # Managing Languages and Translations in the XYB Console The XYB Console includes a fully integrated localisation solution that allows organisations to enable new languages, automatically translate content across services, and let users switch their preferred language instantly. This article explains how localisation works from an end-user and administrator perspective. ### Who Can Use Localisation Features Localisation features are permission-based. To manage translations and languages, users must have the relevant localisation permissions assigned by an administrator. * **`plt-localise-svc/mfe_r`**\ Grants access to the Localisation UI within the XYB Console. * **`plt-localise-svc/localise_r`**\ Allows users to view localisation keys and existing translations. * **`plt-localise-svc/localise_w`**\ Allows users to create, update, and manage localisation content and translations. Users without the appropriate permissions will not see localisation-related menu items in the Console. ### Enabling a New Language (Admins) Languages are enabled at the platform configuration level and automatically applied across all supported services and interfaces. #### Steps to enable a new language 1. Go to **Product configuration > Services** 2. Select the **Product Configuration** service from the list. 3. Open the active **service version** 4. Navigate to the **Global Configuration** > **Languages** section 5. Add or enable the new language Once enabled, the platform automatically starts generating translations for that language across all registered services. No manual translation work is required. {% hint style="danger" %} XYB does not supply the translation service directly. Customers are free to choose their preferred translation provider (for example, Google Gemini) and share the required API credentials with their XYB administrator for secure configuration. {% endhint %} ### Automatic Translation Jobs When a new language is enabled, the platform creates **translation jobs** that run in the background. #### Where to view translation jobs * Navigate to **Admin > Localisation > Jobs** Here you can see: * Job type (e.g. Language activation, Service registration) * Status (Completed, In progress, Failed) * Progress indicator * Number of translated keys * Creation timestamp *** ### Viewing Job Details and Progress Clicking into a job shows detailed progress information. #### Job details include: * Target language * Start time * Overall job status * Per-service translation batches * Number of keys processed per batch Each batch shows its current state (pending, completed, failed), making it easy to understand exactly what the system is doing at any point in time. If a job fails, it can be **re-triggered** directly from the job details view. ### Translation Coverage Across the Platform Once a language is enabled and translation jobs complete: * The new language is available across **all supported Console modules** * All micro-frontends automatically receive updated translations * Newly registered services automatically inherit translations for enabled languages This ensures a consistent, platform-wide language experience without manual coordination. *** ### Changing Your Language (End Users) Individual users can change their preferred language at any time. #### Steps to change language 1. Go to **Profile** 2. Open the **Language** dropdown 3. Select your preferred language The interface updates immediately without requiring a reload or new session. Your language preference is saved and applied automatically on future visits. # Manage Employees, Roles, and Permissions Managing access across your organization starts with a clear structure. This visual outlines the five essential steps to effectively set up and assign roles and permissions using the XYB platform. From planning access levels to assigning roles and finalizing configurations, each step ensures secure, scalable, and role-specific control across your banking modules.
Learn how to: 1. [Manage permissions](/manage-employees-roles-and-permissions/define-permissions) 2. [Create roles with pre-defined permissions](/manage-employees-roles-and-permissions/create-roles-with-permissions) 3. [Manage employees and assign roles](/manage-employees-roles-and-permissions/add-employees-with-pre-defined-roles) # Understanding & Creating Permissions **Permissions** define what actions users can take within your digital banking platform, such as viewing account data, approving payments, or managing employees. They are the building blocks of access control, allowing you to tailor user capabilities based on roles and responsibilities. ### How Permissions Work Many **core permissions are auto-created by the system** based on services like: * Ledger * Payments * Accounts * Access Management These built-in permissions typically cover standard operations like read (`*_r`), write (`*_w`), and approve (`*_a`). These cannot be modified but are always available for use when assigning roles. ### When to Create Custom Permissions While core permissions are system-generated, **admins can create additional permissions** to support custom workflows or more granular access control. For example, you might need a permission for: * Viewing only flagged transactions * Approving high-value payments over a certain threshold * Accessing internal reporting tools To create a new permission: 1. In the Manage Permissions screen, click **Add New**. 2. In the Add a new permission screen, select the applicable instruction.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-8db0a8fa89f28d0a21d43ab16193794954725ef5%2Fimage.png?alt=media) 3. Type a suggestive name and description of the permission.\ Example permissions: * `ledger-svc/view_large_txns_r` — View transactions over a set amount * `employee-svc/update_roles_w` — Edit employee role assignments * `chart-svc/structure_preview_r` — View chart of accounts structure without edit access **Naming convention for permissions** Use the following format: ``` /_ ``` * **Service Name**: identifies the module (e.g., `employee-mgmt`, `ledger`, `access-mgmt`) * **Action**: describes what the permission allows * **Suffix**: * `_r` = read/view * `_w` = write/create/edit {% content-ref url="/pages/6fiDIIoZSMbzsorI0i1A" %} [Create Roles with Permissions](/manage-employees-roles-and-permissions/create-roles-with-permissions) {% endcontent-ref %} 4. Click **Add a permission** to confirm. You can add all the necessary permissions and then proceed to creating the roles. *** ### Best Practices * Use consistent naming conventions (e.g., `*_r` for read, `*_w` for write). * Regularly audit inactive permissions. * Always provide a meaningful reference to clarify what each permission does. *** # Create Roles with Permissions **Roles** are collections of permissions that represent the tasks and responsibilities of specific users in your organization - like Finance Managers, Treasury Analysts, Developers, or Support Agents. Instead of assigning individual permissions to every employee, you group them into roles to simplify access control, ensure consistency, and maintain security across your digital banking platform. Roles help you: * Align system access with actual job functions * Scale access control efficiently as teams grow * Reduce the risk of human error from manual permission assignments * Improve visibility and auditability of who can do what To create a new role: 1. In your console, navigate to **Access Management** → **Roles.**\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-97ca061c0150e290c908b6d54152809b4196c406%2Fimage.png?alt=media) 2. A pop-up window titled **"Add a Role"** will appear. Enter the role details in the fields provided * **Role Name** – Enter a **unique role name** (without spaces) * **Description** – Provide a brief **summary of the role’s purpose**. Use clear and descriptive names to avoid confusion when assigning roles. 3. Under **the Select permissions** dropdown, choose **one or more permissions** applicable to the role. **Example Role Assignments:** **🧾 Example Roles & Permissions** | **Role** | **Example Permissions** | | ---------------- | ------------------------------------------------- | | Treasury Analyst | `ledger_view_postings_r`, `ledger/execute_w` | | Finance Manager | `payments-approve_w`, `ledger_view_postings_r` | | Product Manager | `charts-/create_w`, `template-/view_r` | | Support Agent | `profile-/view_customer_r`, `txn-/view_history_r` | | HR Manager | `employee-/manage_w`, `employee-svc/view_r` | The role will now appear in the **Roles List** and can be assigned to employees. # Manage Employees & their Roles Easily onboard team members to your platform by creating employee profiles and assigning the appropriate roles. Each employee can be assigned one or more roles, which in turn determine their permissions across the system. While managing employee accounts, it's important to know that **some employee accounts may already be present in the system** for example, users who have been invited through other tools or workflows. Your role as an admin is to: * **Review the existing list of employees** * **Assign appropriate roles to them** * **Create new employee profiles only when necessary**, avoiding duplication This ensures secure, role-based access without redundant or conflicting entries. *** Adding employees enables you to: * Provide access to the right modules (e.g., Ledger, Payments, Employee Management) * Assign pre-defined roles with specific permissions * Manage user activity and status centrally *** 1. Navigate to **Access Management > Employees** and click **"Add New"** to open the employee creation modal.\ ![](https://1792085566-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkIq1PGbSmC3vQR1DFPNM%2Fuploads%2Fgit-blob-d8a19d6bdad0b73d4446fd59b2f36d8c145f1d51%2Fimage.png?alt=media) 2. Fill in Employee Details * **Active Toggle**: Enable this to activate the employee's account upon creation. * **Name**: Enter the employee’s first name (required). * **Last Name**: Enter the employee’s surname (optional but recommended). * **Email**: Add the employee's work email address (required). * **Select Roles**: Choose one or more roles that match the employee’s job function. Roles will determine what permissions the user has. 3. Click **Add an employee** to save the profile. The employee will now appear in your employee list, along with their assigned roles and access level. *** ### Tips & Best Practices * **Employees can hold multiple roles** to reflect cross-functional responsibilities. * **Roles control permissions** make sure each role has only the necessary access. * Use the **Active toggle** to enable or disable access without deleting user data. *** ### Example | **Employee** | **Role(s)** | **Access** | | ------------ | -------------------------- | ---------------------------------------------- | | Name 1 | Finance Manager | Can approve payments and view postings | | Name 2 | Treasury Admin, HR Manager | Can manage employees and post transactions | | Name 3 | Support Agent | View customer profiles and transaction history | *** # Bulk Employee Upload If you need to create multiple employee profiles at once, Console allows you to upload a complete employee list using a CSV file. This is useful when onboarding a large workforce, configuring environments for testing, or migrating employee data into the system. **Bulk upload is irreversible,** once employees are added, they cannot be deleted, only deactivated. *** ### To bulk upload employees: In Console, go to: 1. **Access Management > Employees** 2. Then click the **Upload CSV** button in the top right corner. The upload screen will appear:\\
*** ### Preparing the CSV File Create a CSV file with the following structure. Each row should represent one employee record. Ensure the data is accurate, as mistakes can lead to partial or failed imports. | Column | Required | Description | | ---------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Username | Yes | Employee’s email address | | First Name | Optional | First name of the employee | | Last Name | Optional | Last name of the employee | | Roles | Optional (roles must already exist, should it be a pratice to verify the roles exist) | Comma-separated list of role identifiers (e.g., `ROLE_ADMIN`, `ROLE_PAYMENTS_OPS`) | You can download a blank template to get started: {% file src="/files/TfkaLTYj80cxqupXNVzO" %} ### Uploading Your File 1. Drag and drop your prepared CSV file into the upload area or click **Choose file**. 2. Click **Continue** to begin the import. **Note**: * Maximum file size is **2 MB** * Only **CSV files** are supported * Up to **1,000 rows** can be uploaded in one file *** ### Frontend Validation Before uploading starts, the system will check for: * **File type**: Only `.csv` files are accepted * **File size**: Files larger than 2MB will be rejected **Errors:** * *Unsupported file type*: "Please upload a CSV file." * *File too large*: "The maximum file size allowed is 2 MB. Please upload a smaller file." *** *** ### Import Outcomes #### **Import Successful** All rows were valid and imported. A confirmation will show the number of employees added (e.g., “1,023 employees imported”). #### **Import Partially Completed** Some rows were invalid, and others were successfully imported. You’ll see a detailed breakdown of errors: | Row | Name | Surname | Error | | --- | ----- | ------- | ------------------------- | | 247 | Alex | Smith | Surname cannot be empty | | 264 | Erica | Berg | Email is invalid | | 341 | | | Couldn’t process this row | Only valid entries are processed. You can fix the errors and re-upload just the failed entries. #### **Import Failed** No employees were imported due to: * Unsupported file format * Corrupted CSV (e.g., binary data) * Incorrect structure *** ### Tips for a Clean Import * If the file contains usernames that already exist in the system, those rows will fail with a uniqueness error. Avoid re-uploading the same file without removing previously imported usernames. * Use consistent formats for values (no trailing spaces, correct casing) * Avoid uploading test data to production * Review roles before assigning these impact access permissions * Deactivated employees cannot be removed, only reactivated if needed *** # XYB Ledger The **Ledger Platform** provides a secure, real-time foundation for recording and managing financial transactions. Built for accuracy, transparency, and compliance, it serves as the single source of truth for all postings, balances, and account movements across your systems. **Key Highlights:** * Core ledger capabilities including transaction recording, balance tracking, and postings * Customizable Chart of Accounts to reflect your financial structure * Support for both real-time and batch transaction processing * Developer-friendly integration via CLI tools and APIs * Centralized console for operational visibility and access control [Click below to get started with XYB Ledger](https://docs.xyb.co/Li4lZ7ZS1Ajzg5ERNSOj/xyb-ledger). The platform is designed to scale with your institution's needs, whether you're managing retail accounts, internal postings, or cross-platform financial events. Its immutability ensures audit readiness, while its flexibility allows for seamless adoption into your existing infrastructure. By implementing the Ledger Platform, financial institutions gain full control and visibility over their transactional landscape, improving data integrity, operational efficiency, and regulatory alignment. # Payments The **Payments Framework** is designed to support secure, and scalable payment operations. Whether you're handling high-volume batch transactions or low-latency real-time payments, the framework provides the flexibility and control needed for modern financial institutions. **Key Highlights:** * Real-time and batch processing for domestic and international payments * Multi-currency support with built-in FX handling * Automated payment approvals based on customizable thresholds * Integrated reconciliation with ledger alignment and reporting * Fraud and compliance monitoring using rule-based and AI-driven checks The framework allows institutions to define payment workflows tailored to internal policies, regulatory requirements, and customer expectations. From payment initiation to final settlement, each step can be configured and monitored for accuracy and efficiency. By implementing the Payments Framework, banks can simplify operations, strengthen compliance, and offer faster, smarter payment experiences to their customers. # Accounts The **Accounts Framework** provides a foundational layer for managing financial accounts across a variety of products and use cases. It supports everything from individual deposit accounts to complex, hierarchical account structures, all within a secure, configurable, and scalable architecture. **Key Highlights:** * Support for multiple account types, including grouped and standalone accounts * Full account lifecycle handling (active, dormant, closed, etc.) * Built-in controls for balances, limits, and interest-bearing configurations * Automated calculation of interest and fees for both deposits and loans * Role-based access control (RBAC) for secure data handling Designed for easy integration, the framework allows institutions to define and customize account rules, hierarchies, and behavior. It also includes tooling to manage interest logic, fee triggers, and account monitoring with minimal operational overhead. By implementing the Accounts Framework, banks and financial service providers can ensure consistency, transparency, and compliance in how customer accounts are created, maintained, and reported. # Credit Our Credit Services Suite offers a modular and API-driven approach to managing the full credit lifecycle. From origination to scoring, contract management, and servicing, the platform integrates easily with your existing systems while supporting a wide range of credit products and customer experiences. Whether you're enhancing your retail lending operations or expanding into new segments, the suite is built for flexibility and compliance. **Key Highlights:** * Modular services for origination, scoring, contract, and servicing * Event-driven architecture with real-time notifications * Easily integrates with internal systems via APIs and messaging * Pre-built support for customer, fee, and collateral management * Designed to align with regulatory and operational requirements Each module operates independently or as part of a broader ecosystem, allowing for phased adoption and quick wins. The platform supports dynamic configuration, enabling product teams to launch, adjust, or sunset offerings without deep technical intervention. With robust backend capabilities and seamless customer-facing integration, the Credit Services Suite empowers institutions to accelerate innovation, improve turnaround times, and reduce operational complexity. # XYB Platform 1.1 Release Notes Release Date: 4/7/2025. Find out the top product/platform updates, performance improvements, and bug fixes from this release. ## V 1.1 Release Highlights {% embed url="" fullWidth="true" %} ## 1. Product Configuration ### Highlights * **Improved Product Configuration Usability:** Addition of a **templates component** enables reusable config structures and **custom timezone support** ensures time-accurate setups for global markets. * **Streamlined Import/Export FlowsL** Introduction of a new **Import** function and improvements to the **export** function make importing and exporting configurations smoother, clearer, and more actionable. * **Enhanced UI Consistency & Error Handling:** Major polish across dialogs, modals, and layout, including **standardized error handling**, **refined country value input**, **product version navigation**, and more intuitive controls like **disabled draft buttons** and **close actions**.
Supporting Improvements and Fixes * **Auditing & Schema Tracking:** More **granular audit logging** of sort/filter actions; schema versioning improvements; removal of unnecessary enforcement logic on product versions. * **Dialog & Interaction Enhancements:** Fixes and improvements for dialog triggers, range date pickers, version navigation, and product ref copy logic. * **Theme & CSS Fixes:** Resolution of theme override conflicts, post-CSS prefix issues, and **CSS isolation bugs.** * **Visual/UI Bug Fixes:** Corrections to icons, infinite loop behavior, export dialog rendering, toast re-renders, and ProductCard integration. * **Permission Evaluation:** Logic updated to use **token credentials** for evaluating permissions rather than identity directly. * **Versioning Documentation:** Documentation added to clarify **versioning logic** and integration standards for downstream teams.
## 2. Ledger ### Highlights * **Improved Status Management in Account Creation:** Users and systems can now **set account status during account creation**, providing more control during onboarding and reducing the need for subsequent patch operations. * **Better Context in Ledger Responses:** The **source of the transaction** is explicitly returned in the response as a `target` field, making it part of the formal record adding more transparency and traceability to ledger transactions and status transitions. * **Multilingual Support for Wallet Management: Estonian translations** and other localization enhancements have been added for wallet management and UI display.
Supporting Improvements and Fixes * **Service Schema Publishing:** Ledger service now publishes its **service configuration schema**, initial setup requests, and supports consuming configuration via topics with application-specific metadata (e.g., `appName`). * **Global Configuration Enhancements:** A `source` column was added to the `global_configuration` table for improved auditing and configuration lineage. * **OpenAPI Documentation Fix:** Missing OpenAPI definitions were corrected to ensure all service endpoints are well-documented for integrators and developers. * **Ledger Telemetry & Spring Boot Updates:** Telemetry and Spring Boot libraries were upgraded for better performance monitoring and platform compatibility. * **Permission Handling:** Ledger now uses **role-based permission evaluation**, aligning with other services in the platform. * **Several Database & Indexing Improvements**
## 3. Payments ### Highlights * **Dynamic Payment Field Enhancements & Currency Handling:** New support for **GBP and EUR payment routes**, **dynamic payment field migration** from legacy services, and **currency filters and sorting** in pay-history allow for a more intuitive, tailored, and localized user experience across international payment flows. * **Improved Payment History Interface:** Users can now benefit from **page restoration**, **shortcuts**, enhanced **filtering**, **associated payment visibility**, and table layout improvements.
Supporting Improvements and Fixes * **Kafka & Topic Enhancements:** Schema-related topics, Kafka consumer group naming, and partitioning logic were refined for more reliable messaging and improved integration with the rest of the data pipeline. * **Rate Initialization & Exchange Rate Improvements:** Bulk endpoints for initializing rates, validations for currency codes, new FX pairs (e.g., USD/GBP), and logic for incremental updates instead of destructive overwrites make currency rate handling more resilient. * **Auditability and Telemetry:** Role-based permission evaluation, logging libraries, telemetry integration, and metrics support have been expanded, enabling stronger observability for all services. * **Several Bug Fixes and improvements**
## 4. Accounts ### Highlights * **Wallet Linking and External References:** The account system now supports **direct links to wallets**, streamlining financial product connectivity. An **External Reference column** has been added to each account, allowing client systems or partners to associate their own reference IDs, which improves integration flexibility and visibility. * **Improved Page State and UI Experience:** A new **page state restoration** feature helps users return to previously selected views, filters, or scroll positions when navigating back and forth.
Supporting Improvements and Fixes **Auditing & Traceability:** Added **JPA listeners** and an `updatedBy` field to element entities to track who made changes. Controllers now include improved **information auditing** for better trace logs. **Account Metadata Improvements:** Added support for referencing the **account owner**, allowing stronger linkages between accounts and customer identity profiles. **Visual and UI Theming Fixes:** Adjustments were made to **theme overrides**, ensuring consistent styling across platforms and improved alignment with design systems.
# XYB Platform 1.2 Release Notes Release Date: 16/09/2025. Find out the top product/platform updates, performance improvements, and bug fixes from this release. {% embed url="" %} ### Design and Launch Credit Products You can now offer loans, BNPL, credit cards, credit lines, and more, managing the full lending lifecycle from setup to contract disbursement and management. * Configure core services like contracts, collaterals, interest, accounts, and entities to define your credit rules. * Design products with repayment logic and operationalize them through contracts, disbursements, and collections in one place. Watch this video to learn more about XYB Credit: {% embed url="" %} ### Payments: Expanded Workflow Coverage and Richer Payment History Payments now support more flexible workflows and improved history tracking, giving you better visibility and control over outgoing and internal payment operations. * You can configure and test payment flows with new schema versions, support for credit collections, FX payment handling, and enhanced workflow scripts with integration tests. * You can track payments in detail through improved payment history pages, including entity navigation, associated postings, payment details components, and task-linked payment pickers.\\ [Learn more about Payment Workflows.](/xyb-platform-1/xyb-payments/payment-setup/payment-workflows) ### Product Configuration: Approval Process for Better Governance Customers can now manage product configuration more efficiently with new change request flows, version controls, and improved reference handling. These enhancements streamline how you roll out, review, and approve configuration changes. * You can raise and track change requests with status transitions and approvals for added governance. [Learn more about approvals](/xyb-console/approvals-and-policies). * You can manage product versions more easily with draft-to-active transitions, pre-approval dialogs, and improved product reference validation. [Learn more about managing products.](/xyb-console/product-configurations/managing-products-in-the-xyb-console) ### Console: Improved Navigation, Dashboards, and Menu Management The XYB Console now includes richer navigation options and improved dashboards, making it easier to manage entities, track modules, and access core configuration tools. These updates enhance usability and visibility across your environment. * You can navigate more efficiently with new submenus for workflows, lending contracts, data management, and lending-day changes. * You can track metrics and module counts directly in updated dashboards, with support for scroll improvements, font switching, and customizable widgets. [Learn more about the XYB Console.](/xyb-console/get-started-with-xyb-console)\\ ### Ledger: Improved Performance and Agent Management The ledger services now include stronger data integrity safeguards and enhanced support for managing agent references, ensuring accurate postings and resilient balance handling. These updates help keep your financial records consistent and auditable. [Learn more about XYB Ledger.](https://docs.xyb.co/xyb-platform-1/xyb-ledger/) ### Access Management: Improved Role and Employee Controls Access management now offers improved visibility and fine-grained controls for managing user access, roles, and permissions across your organization. These updates make it easier to securely assign roles and manage employee access at scale. [Learn more about Access Management.](/xyb-console/access-and-permissions-overview) *** # XYB Platform 1.3 Release Notes Release Date: 10/10/2025. Find out the top product/platform updates, performance improvements, and bug fixes from this release. #### API Key Management You can now manage the full API key lifecycle: register, revoke, and rotate API keys.[ Learn more about API Key management](/the-platform/xyb-platform-overview/platform-authentication) #### Task Management * You can now create and manage tasks directly within the console, improving how teams plan, assign, and track work. * Define custom task types, assign owners, update statuses, and review task history to maintain full visibility of operational progress.\ [Learn more about task management.](/xyb-console/create-and-manage-tasks) #### Credit / Contract Enhancements * **Day Changes View:** A new console view to track daily processing, when day change executions start, their duration, outcome (success/failure), and detailed execution logs. [Learn more here.](/credit/create-and-manage-contracts/viewing-and-managing-day-changes-in-the-console) #### Entity Access Control * Enhanced entity settings now allow administrators to manually control customer (or entity) app access. [Learn more about managing entities](/xyb-console/understanding-entities-in-xyb). #### **Ledger: Enhanced Wallet Controls, Data Reliability, and Interest Services** * Data publishing flows have been enhanced to improve reliability and consistency, ensuring accurate and timely financial reporting. * Ledger services now also support registering interest services as agents, enabling more comprehensive handling of interest-bearing accounts and transaction logic.\ Learn more about [**XYB Ledger**](https://docs.xyb.co/xyb-platform-1/xyb-ledger/). #### Payments: Improved Transaction Handling and Balance Flexibility * Payments now provide enhanced control and visibility across transaction operations, ensuring smoother payment processing and reconciliation. * Support for negative balance handling has been added, enabling greater flexibility in payment operations and settlement management. Learn more about [**Payment Workflows**](/xyb-platform-1/xyb-payments/payment-workflows-and-automations/payment-workflow-overview). #### Performance Improvements * Dashboard metrics have been expanded to capture module-level insights, giving you clearer visibility into system performance and usage trends. * The console also includes updates to component libraries, improved caching, and refreshed templates for a smoother, more consistent user experience. * **Mobile app**: Session management has been improved with extended token validity and stability fixes, ensuring smoother and more reliable mobile access. # XYB Platform 1.4 Release Notes Release Date: 29 October 2025 Find out the top product/platform updates, performance improvements, and bug fixes from this release. ### Workflow Automation Engine The new automation designer offers a cleaner canvas, smarter node interactions, and powerful analytics to help you design, monitor, and iterate with confidence. #### New and Improved Nodes We’ve expanded node capabilities to include **Webhook Triggers**, **HTTP Requests**, and enhanced **Task and Condition nodes**. You can now easily integrate with external systems, configure dynamic payload mappings, and build multi-branch logic right from the canvas.\ Learn more: [Trigger Nodes in Workflows](/xyb-console/workflow-management/building-blocks-of-a-workflow/trigger-nodes-in-workflows), [Task and Condition Nodes](/xyb-console/workflow-management/building-blocks-of-a-workflow/task-and-condition-nodes) #### Run and Analytics Views Monitor workflow performance in real time with **Run Analytics**. The new views provide visibility into success rates, run velocity, and failure trends, directly from the canvas or Versions table. You can drill into individual runs, view error traces, and retry failed executions without leaving the designer.\ Learn more: [Track Live Stats and Errors for Workflows](/xyb-console/workflow-management/track-live-stats-and-errors-for-workflows) #### Version Control Manage your automation lifecycle with **Workflow Version Control**. Create draft versions, request approvals, and activate or suspend workflows with full transparency. Each version now clearly follows a lifecycle (Draft, Active, Suspended, Terminated) for safer iteration and change management.\ Learn more: [Workflow Version Control](/xyb-console/workflow-management/workflow-version-control) *** ### Data Management & Compliance XYB Console supports a policy-controlled data deletion process that helps institutions comply with privacy regulations such as GDPR. You can initiate and manage data deletion requests governed by approvals to ensure sensitive actions like removing personal data are audited and reviewed by the right stakeholders. Detailed data deletion reports can be generated post-deletion, including entity information, initiators, approvers, and timestamps. Learn more: [Data Deletion Process](/xyb-console/file-vault) *** ### Nordic Revolving Credit Product You can now **create a Nordic Revolving Credit Line product** directly in the Console using the new *Credit Line* product type. Configure **tiered payout fees, subcontract amortization rules, and repayment terms** to match Nordic market requirements. The product supports **parent-child contract structures**, allowing multiple drawdowns under a single facility with consolidated schedules and full visibility into limits, balances, and repayments. Learn more: [Nordic Revolving Credit Line - Overview](#nordic-revolving-credit-product) *** ### Ledger & Financial Operations Enhanced ledger operations with improved reliability and data consistency. Key improvements include: * Unified status transitions across Account and Ledger services * Fixed synchronization between ledger and search services * Day change process now properly links credit contract transactions with invoice IDs * Improved instruction persistence under high load conditions *** ### Template Service Enhancements More flexibility and control over document templates across the platform. New features include a service registry endpoint, multi-service placeholder support, and dropdown service selector in the UI. Services can now listen for template updates and persist relevant details for streamlined report generation. *** ### Business Intelligence Dashboards New dashboard widgets provide enhanced business insights. The dashboard library now includes full-screen widget support and complete Arabic language support with right-to-left (RTL) display. Lending dashboards feature contract limit tracking, main and child contract listings, and aggregated usage amounts with improved debt portfolio reporting. *** \\ # XYB Platform 1.5 Release Notes Release Date: 19 November 2025 Find out the top product/platform updates, performance improvements, and bug fixes from this release. #### 1. Reconciliantion Foundation * A new **Ledger Data Extract workflow** node is now available in the Console under **Workflows > Automations**. This node retrieves ledger data for a selected period and saves it as a CSV file in **File Vault**. It eliminates the need for manual ledger exports and ensures the most up-to-date data is available for reconciliation. [Learn more](https://docs.xyb.co/xyb-ledger/integrate-with-xyb-ledger/understanding-reconciliation-in-xyb/ledger-data-extract-workflow) * **File Vault Upload Enhancements:** You can now upload reconciliation statement files directly through **File Vault** in the Console. The upload flow validates your CSV format, captures metadata (such as file source, date, and dataset), and stores the file securely for reconciliation. All uploaded and system-generated files are now visible in File Vault, making it easier to track, download, or review reconciliation inputs. [Learn more.](/xyb-console/file-vault) #### 2. Improvements to Credit Contracts and Management * **Nordic Credit Line Enhancements:** Several improvements were made to Nordic revolving credit, including fixes to payment holiday rules, fee calculation issues, and subcontract behaviour. Term updates, section layouts, and activation flows are now more reliable, ensuring Nordic credit products behave consistently and accurately across all scenarios. [Learn more.](/credit/use-case-tutorials/nordic-revolving-credit-line-overview) * **Improved Alerts and Notifications:**\ Credit-related alerts now trigger more consistently and at the right moments. Users receive timely updates on key contract events, helping them stay informed without needing to manually check contract pages. * **Stronger Ledger Integration:**\ Credit contracts now synchronise more closely with ledger activity. Incoming transactions and financial events associated with credit contracts are captured more accurately, improving reconciliation and reducing manual review. #### 3. Workflow Enhancements * **New and Improved Workflow Nodes:** Added a new **Account Creation node** that enables automated onboarding and activation flows inside Workflows. In addition, several existing nodes have been improved, including enhanced branching options in the Condition node and a fix to the HTTP Request node to ensure variables are correctly passed through during workflow execution. [Learn more](/xyb-console/workflow-management/building-blocks-of-a-workflow). * **Ledger-Integrated Workflow Improvements:** Workflows now include end-to-end support for ledger-driven automations through the new **Ledger Data Extract node** and deeper integration with File Vault (as mentioned above under Reconciliation Foundation). These updates allow workflows to schedule ledger extracts, process dataset-based exports, publish trigger events, and seamlessly store or retrieve files via File Ops. * **UI Improvements for Workflow Management:** Navigation and visibility within Workflows have been enhanced, including sidebar improvements for viewing workflow runs and a new error-details modal for faster troubleshooting. * **Technical and Reliability Improvements:** Workflow execution is now more robust thanks to distributed locking for node definitions, better support for shared field requirements across nodes, and backend enhancements informed by service-function analysis. Integration updates such as File Ops service linkage and new entity-based triggers further strengthen workflow reliability across the platform. # XYB Platform 1.6 Release Notes ### 1. Improvements to Credit Contracts and Management **Nordic Revolving Credit - Flexible Repayment & Credit Options** This release introduces **more flexible repayment and credit management capabilities** for Nordic Revolving Credit products. Customers can now manage their loans more dynamically through early repayments, additional payouts, payment holidays, and write-offs, improving both customer experience and operational control. *** * **Partial Payback:** Customers can now make a **partial repayment** on an active credit contract, allowing them to reduce the outstanding balance without closing the contract. The contract continues using the **Instalment** calculation method, and the instalment amount is automatically recalculated after the partial payment. [Learn how to execute partial payback.](https://docs.xyb.co/platform-release-notes/release-updates-and-announcements/spaces/3cyJXtDL0DgAGdkhCKYE/pages/H1VxWzzul7uDEW4cV4Ix#id-1.-partial-payback) * **Full Repayment**: Customers can now **fully repay their loan before maturity**, allowing them to close the contract early. Once the full repayment is processed, the contract is **automatically closed** and no further instalments are generated. [Learn more](https://docs.xyb.co/platform-release-notes/release-updates-and-announcements/spaces/3cyJXtDL0DgAGdkhCKYE/pages/H1VxWzzul7uDEW4cV4Ix#id-2.-early-repayment-full-payoff). * **Extra Payout:** Customers can receive an **extra payout** under an existing revolving credit line, increasing the available credit without creating a new contract. The system creates a **new subcontract** for the payout and updates the credit limit accordingly. [Learn how to initiate extra payout](https://docs.xyb.co/platform-release-notes/release-updates-and-announcements/spaces/3cyJXtDL0DgAGdkhCKYE/pages/H1VxWzzul7uDEW4cV4Ix#id-4.-extra-payout). * **Payment Holiday:** Customers can be granted a **payment holiday**, allowing them to temporarily pause repayments for a defined period. During the holiday, invoices are automatically rescheduled and the loan term is extended by the duration of the pause.[ Learn how to configure a payment holiday](/credit/create-and-manage-contracts/manage-credit-contracts-and-terms/how-to-configure-a-payment-holiday). * **Write-Off Support** This release adds support for writing off outstanding loan balances when repayment is no longer expected. Write-off amounts are correctly reflected in financial views and ledger transactions are created to ensure accurate accounting and reporting. [Learn how to write-off a contract](/credit/create-and-manage-contracts/manage-credit-contracts-and-terms#write-off). *** ### 2. SSO & Access Management **Customers can now configure self-service Single Sign-On (SSO) for the XYB Console themselves** using their existing identity provider, such as Okta, Microsoft Entra ID (Azure AD), Google Workspace, or any SAML 2.0–compatible provider. The setup is fully self-service and guides administrators through creating a SAML application in their IdP and completing the connection in the console. XYB provides all required metadata and includes a built-in **connection test** to validate the setup before activation. Once enabled, your configured identity provider becomes the login method for all users in the organisation. [Learn how to setup SSO for your organization](/the-platform/xyb-platform-overview/sso-setup-placeholder). ### 3. Workflow Orchestration Performance Improvements We’ve improved how workflows run across the platform to make complex processes more **reliable, flexible, and easier to evolve**. Workflows now support conditions, parallel and asynchronous steps, and are automatically discovered and managed across services. This allows processes to be visualised, monitored, and extended more easily over time. These improvements also enable advanced use cases such as running reconciliations through configurable workflows instead of fixed logic. [Learn more about workflows](/xyb-console/workflow-management). ### 4. Improvements and Fixes * **Improved internal reconciliation foundations**, enhancing how data is streamed, matched, aggregated, and reported to support future reconciliation capabilities. * **Increased reliability of workflow execution**, including better handling of complex conditions, parallel steps, and state transitions across services. * **Fixed multiple issues related to credit schedules and repayments**, improving accuracy in repayment calculations and invoice handling. * Improved console performance, including significantly **faster load times on the ledger posting page** and other frequently used views. # XYB Platform 1.7 Release Notes Release Date: 22/01/2026. Find out the top product/platform updates, performance improvements, and bug fixes from this release. ### Improvements to Credit Contracts and Credit Operations This release enhances how credit contracts and related entities are managed, with smarter contract term changes, improved collateral handling, and fixes across core credit product flows. * **Smarter Credit Contract Term Changes**\ Support has been added for increasing loan amounts on active credit schedules, alongside improved handling of overpayments, early and partial repayments, and full contract terminations. Schedules, balances, invoices, and interest calculations are now consistently recalculated using the latest known balances across all supported change scenarios. * **Improved Early Repayment and Termination Handling**\ Early repayment logic has been aligned and validated, ensuring accurate invoice creation, correct balance movements, and proper deletion of future invoices when contracts are fully repaid or terminated. * **Interest Calculation Improvements Across Term Changes**\ Interest calculation logic has been strengthened for cases where interest rates change during active contracts or term reductions, ensuring correct accrued and future interest amounts even after partial repayments or schedule recalculations. * **General Credit Product & Fee Improvements**\ Fixes have been made to contract activation date handling, extra payout treatment in microloans, and fee management in draft terms. These changes reduce operational friction and ensure product behaviour aligns with accounting and business expectations.
**1.7.1 Hotfix** * **Improved APR validation during Extra Payouts**\ APR checks now run earlier during Extra Payout term creation, preventing unexpected validation failures later (e.g., when updating or removing fees after the term is created). * **More reliable interest tracking during contract term activation**\ When a new contract term is activated, the system now creates a new Interest Tracker for the new term period and correctly closes the previous tracker, ensuring interest accrual aligns with the latest active term. ### Workflow Enhancements This release significantly expands workflow capabilities, bringing the Console closer to the true execution model used across Payments and Automations. Workflows now better reflect real multi-service orchestration, observability, and safe change management. * Expanded workflow node model and configuration, including grouped participants and improved node details. * Improved payment workflow configuration and templates, including plan-based setup and updated workflow APIs. * Enhanced workflow execution visibility with runs, statistics, and trace support. * Improved workflow and automation list views, canvas interactions, and node configuration sidebars ### Localisation Improvements This release introduces improved localisation capabilities across the XYB Console, making it easier to manage, update, and validate translated content across services. * Added a localisation menu in the console to view and manage translation keys across platform services. * Introduced translation jobs with clear progress tracking, batch execution, and success/failure visibility for each language. * Enabled dynamic language switching in the console UI, allowing users to change language without reloading or restarting sessions. [Learn more about localisation in the XYB Console.](/xyb-console/managing-languages-and-translations-in-the-xyb-console) ### UI Improvements and Fixes * Improved table responsiveness across multiple Console views, including responsive columns, sticky table actions, and better handling of wide datasets on smaller screens. * Enhanced mobile and tablet usability through improved overflow handling, scrolling behaviour, and layout stability for data-heavy views. * Updated button sizing and spacing in headers and secondary actions to improve visual consistency and touch interaction. # XYB Platform 1.8 Release Notes ### Improvements to Credit Contracts and Credit Operations This release strengthens credit lifecycle management, improves collateral modelling and LTV accuracy, and enhances console performance and operational stability across contracting workflows. * **Credit Lifecycle & Term Change Refinements**\ Changes to payment structure on active schedules are now supported, including principal frequency, interest frequency, payment day, schedule type, and penalty/interest conventions. Schedule and repayment edge cases (bullet loans, extra payouts, full repayment, termination dates) have been resolved to ensure consistent recalculation of balances, APR, invoices, and repayments. [Learn more about managing credit contracts and terms.](/credit/create-and-manage-contracts/manage-credit-contracts-and-terms) * **Collateral Engine & LTV Refactor**\ The collateral data model has been improved (subtypes, status changes, relationships) alongside console UX enhancements such as continuous-scroll search. LTV values are now reliably calculated and recalculated when contract principal changes, delivering a more accurate and maintainable collateral view with improved linking and discoverability. [Learn more about collaterals.](/credit/configure-and-create-credit-products/configure-global-settings-for-credit-products/configure-and-create-collaterals) [Learn more about XYB Credit.](https://docs.xyb.co/credit/) # XYB Platform 2.0 Release Notes **Release date:** March 20, 2026 ### New Features * **Risk Engine dashboard:** A new interface for reviewing and managing risk checks, giving you visibility into how transactions are being screened. * **Admin dashboard:** A new overview dashboard with at-a-glance stats, tables, and cards summarizing key account activity. * **Cash positions and balances view:** See a consolidated view of your cash positions and account balances directly in the platform. * **Payee (beneficiary) management:** Create, edit, approve/reject, and block or unblock payees, with full support for all required beneficiary details. * **Payment initiation and approval workflow:** Initiate payments, route them for approval, and approve or reject them, with four-eye (dual-control) approval support built in. * **Change request approvals:** A new change request list and detail view lets designated approvers review and approve/reject pending changes. * **User groups and roles & permissions screen** — Organize users into groups and manage granular roles and permissions from a dedicated screen. * **Commercial Portal login and shell:** A new, separately branded login experience and application shell for the commercial portal, including support for users with access to multiple accounts. * **Card management:** Initial card management tools, including card replacement, cancellation, activation, and PIN view requests. * **Session timeout warning:** You'll now be warned before your session times out due to inactivity. * **Payment activity audit trail:** A detailed payment view now shows the full audit trail for a given payment. ### Improvements * Clarified which policies currently apply to an entity in the Entity policy view. * Deactivated employees can no longer be selected as policy approvers. * Improved visibility of approvals for managers when a request was initiated by a specialist. * User invite and edit screens now reflect accurate, up-to-date information. * General visual polish across the console: sidebar, tables, spacing, borders, focus states, and empty-state messaging. * Roles displayed in business selection now show all of a user's actual roles, not just one. * Users can now be assigned multiple roles at once. * Added a "Feature disabled" message in place of a generic "Not found" error for features that aren't yet available to you. ### Bug Fixes * Fixed charts in the console showing outdated data when switching between them. * Fixed rejected payments incorrectly staying in "in processing" status on the Activity screen. * Fixed an issue where the payment initiation form was not visible in the web app. * Fixed errors thrown on the Accounts page when a statement was missing. * Fixed missing localizations for beneficiary dynamic fields. * Fixed an "unknown component" error that could appear in beneficiary policy setup. # XYB 2.1 Platform Release Notes ## XYB Platform 2.1 Release Notes #### 1. Account Statements **Downloadable Statements in CSV, BAI2, and PDF** This release introduces the ability to generate and download account statements directly from the platform, giving treasury and finance teams a self-service way to produce records for reconciliation, reporting, and sharing with counterparties or auditors. * **CSV format:** Suitable for general reporting and import into spreadsheets or internal tools. * **BAI2 format:** Designed for direct use with treasury management and bank reconciliation systems. * **Formatted PDF:** A branded, readable statement suitable for sharing externally with counterparties or auditors. * **Statement history:** All generated statements are saved and accessible from a dedicated list view within the platform, so you can retrieve past statements at any time. #### 2. Treasury Dashboards and Roles **Role-Specific Views for Treasury Teams** This release introduces role-specific dashboards and a new Treasury Manager role, giving treasury teams a focused view of the information most relevant to their work. * **CFO Dashboard:** A high-level view of cash positions, payment volumes, and approval status. * **AP Manager Dashboard:** Visibility into the change request queue, pending approvals, and team activity. * **AP Specialist Dashboard:** A focused view of payment initiation status and outstanding actions. * **Admin Dashboard:** Platform-level visibility for administrators. * **Treasury Manager role:** A new role that can be assigned to users through the standard user management flow, unlocking access to the relevant dashboard views. #### 3. Payment Controls and Approvals **Stronger Risk Checks and Clearer Approval Feedback** Payments now go through an additional risk check before entering the approval workflow, and approvers can provide structured feedback when rejecting a request. * **Risk assessment at submission:** Payments are now risk-assessed as soon as they're submitted, rather than only at execution — reducing the chance of duplicate approvals or incorrectly routed payments. * **Structured rejection reasons:** When rejecting a change request, approvers can now select a reason code alongside their written comments. The reason is visible to the person who raised the request and is captured in the audit record for future reference. #### 4. Credit and Collateral **Expanded Credit Product Configuration and Collateral Management** This release includes a set of improvements to credit product management and collateral workflows, aimed at supporting more complex lending structures and reducing manual work. * **Updated Euribor base rates:** Base rates are now pulled from an updated data source and display correctly under each contract. * **Expanded credit line and guarantee configuration:** Credit line and guarantee products now support additional configuration options for more complex lending structures. * **Automatic commitment interest invoicing:** Commitment interest schedule invoices can now be generated automatically, reducing manual effort for revolving credit and commitment-based lending. * **Pledgee management:** Pledgee details and status can now be managed directly within the collateral module. * **Customer Due Diligence (CDD):** CDD workflows are now available to support onboarding and ongoing compliance requirements. #### 5. Improvements and Fixes * Improved payment and beneficiary workflows, including the ability to select which payment details to use when a payee has multiple accounts on file, and a live balance display on the payment form. * Strengthened platform controls, with auditing now in place for key actions and automated notifications for credit contract events. * Redesigned console navigation with clearer groupings, smoother transitions, and improved visual consistency across the platform. * Fixed a range of issues across payments, approvals, credit contracts, collateral, access management, and the console — including incorrect badge behaviour on new payees, errors in contract creation and download, role changes not removing previous permissions, and several UI display issues. # XYB Platform 2.2 Release Notes XYB Platform 2.2 is our biggest release to date. It's centred on three things: a much larger and more capable automation node library, the groundwork for automated bank reconciliation through composable workflows, and a new generation of dashboard widgets for treasury and operations users. Alongside this, we've introduced an AI-powered invoice assistant (early access), tightened anomaly detection on payments, and completed a platform-wide hardening pass covering permissions, observability, and dependency security. #### 1. Automation & Workflow Nodes **A Larger, More Flexible Node Library for the Workflow Builder** The composable workflow builder has been substantially expanded, giving you more building blocks to model complex processes without custom development. * **New node types:** Wait and Sync nodes join refreshed Task, HTTP Request, Webhook, Slack, Code, and Message nodes, alongside a new internal-event trigger. * **Better organisation:** Nodes can now be grouped by type and carry custom icons, making larger workflows easier to navigate. * **Cleaner configuration:** Node configuration fields are now driven dynamically, and input/output variable handling has been simplified across the board. * **Safer evolution:** Nodes can be deprecated cleanly over time without breaking workflows that are already running. #### 2. Automated Reconciliation — Backend Foundation **Laying the Groundwork for Automated Bank Reconciliation** This release delivers the backend foundation for automated bank reconciliation, built as a composable workflow rather than a fixed, hardcoded process — so reconciliation logic can be configured and extended over time rather than requiring a new release for every change. * **Configurable, not hardcoded:** Reconciliation can now be initialised with runtime configuration instead of relying on a single fixed profile. * **Annotated results:** Reconciliation output is written back as an annotated file showing each original row alongside its outcome (for example, matched or requiring attention). * **First user-facing step:** A new "run reconciliation automatically on upload" option is available on the bank statement upload screen. The full Reconciliation experience — a dedicated section for managing profiles and reviewing reconciliation runs — is still in development and will follow in a future release. #### 3. Dashboard Widgets **New Widgets for Treasury and Operations** The Console dashboard has been extended with new widgets, giving treasury and operations teams clearer, more focused visibility into platform activity. * **Payment Volume Overview:** A summary view of payment activity over time. * **Payment Success Rate:** Visibility into how payments are performing. * **Partner Adapter Health:** Status visibility into the health of connected payment partners. * **Refreshed entity and ledger widgets:** The previous entity and ledger cards have been split into more focused, individually customisable widgets. #### 4. Account Statements **Redesigned Statement Screens, with Retry Support** The account statements experience has been redesigned to align with our updated design system, and now includes a retry option for when generation doesn't succeed the first time. * **Redesigned generation flow:** The statement page and the single/multi statement generation dialogs have a refreshed look and feel. * **Retry failed statements:** If a statement fails to generate, you can now retry it directly from the statement page — no need to start over. * **Clearer scheduling:** Scheduled and manually generated statements are now clearly distinguished, and statement scheduling can target a specific wallet and template. #### 5. Treasury, Payees & Banking Coordinates **More Control Over Payee and Payment Details** Payee and banking coordinate management is now more flexible, with several improvements aimed at reducing risk and giving you more control. * **Deactivate and reactivate coordinates:** Banking coordinates can now be deactivated and reactivated as needed. Deactivated coordinates are automatically removed from the list of available payment destinations. * **Safer approvals:** If a payment's destination coordinate is deactivated while it's still pending four-eye approval, the payment is now automatically rejected rather than proceeding. * **No more per-payee currency limits:** The previous restriction limiting which currencies could be used per payee has been removed. * **Richer address details:** Beneficiary addresses now support apartment/suite information. * **Mandatory comment on block:** Blocking a payee now requires a comment, improving the audit trail behind that decision. #### 6. AI Invoice Assistant (Early Access) **A New Way to Process Invoices** We've introduced an AI-powered invoice assistant, available to early-access partners. A new "My invoices" view in the web app lets you upload invoices and have key details extracted automatically, reducing manual data entry. Access is currently gated while we roll this out gradually — reach out to your XYB contact if you'd like to be considered for early access. #### 7. Risk & Anomaly Detection **Sharper Detection, Clearer Signals** * **New off-hours detection rule:** Payments created outside of expected hours are now flagged as part of the risk engine's rule set. * **Refreshed anomaly badges:** Badges covering new payee, payee details changed, off-hours activity, multiple payments in a day, high amount, and cross-border payments have been refactored for clarity. * **More reliable high-amount detection:** A previously inconsistent trigger for the high-amount rule has been corrected. #### 8. Improvements and Fixes * **MFA:** Improved phone number handling, more consistent policy enforcement, and admin experience improvements; the magic-link email template has also been refreshed. * **Collateral:** Collateral value now updates automatically when product haircut configuration changes, and a foreign exchange reference rate can be configured to drive value recalculation. * **Interest:** Fixed and variable base-rate handling has been improved in the day-change process, and an issue where automatic variable interest changes could drop a principal payment from the schedule has been fixed. * **Product configuration:** Fixed cases where terminating a draft version could leave a product with no active version, and corrected how boolean and integer fields are saved. * **Web app & Console polish:** A range of smaller fixes, including more stable list behaviour while scrolling, a fixed "Back to account selection" link, resolved login screen flicker, fixed blank pages that could appear after a platform update, and a number of translation, tooltip, and button-placement corrections. # XYB Platform 2.3 Release Notes #### 1. Batch, Scheduled & Backdated Payments **A Richer Toolset for Initiating Payments** This release significantly expands what you can do on the payment initiation side, with support for batch payment files, scheduled and postponed payments, backdated payments, and reusable payment drafts and templates. * **Batch payment upload:** Import and submit batch payment files — including payroll-style runs — via CSV upload. * **Scheduling:** Schedule individual and batch payments for a future date, or postpone a payment as needed. * **Backdated payments:** Create backdated payments where your business process requires it. * **Drafts & templates:** Save payments as drafts to finish later, and store frequently used payment setups as reusable templates. * **End-to-end traceability:** Batch identifiers are stored and displayed in payment history, so grouped payments remain traceable from submission through to completion. #### 2. Approvals & Rejection Handling **More Control Over How Approvals Are Configured and Resolved** The four-eye approval experience has been extended with per-operation approver configuration, a clearer rejected-approvals flow, and the ability to cancel an approval request. * **Per-operation approvers:** Approval policies can now be bound to specific operations, with approvers configured per operation for beneficiary approvals. * **Rejected-approvals view:** When a payment or payee is rejected, you can now review, discard, or resubmit it through a dedicated rejected-approvals screen. * **Cancel a request:** Initiators can now withdraw an approval request before it's actioned. * **Full audit trail:** The four-eye approval flow now carries a complete audit trail from submission through to resolution. #### 3. Treasury Web App & Console **Broad Usability and Consistency Improvements** The treasury web app and operator console receive a wide set of usability and consistency improvements. * **Asset position view:** A new view for tracking asset positions. * **Rejected approvals & unfinished payments:** Dedicated views for reviewing rejected approvals and payments left in an unfinished state. * **Source account visibility:** The source account is now shown on the Activity screen. * **Maintenance-mode banner:** A banner now appears during scheduled maintenance windows. * **Clearer access control:** Navigating directly to an area you don't have access to now shows a proper "Access Denied" page instead of a blank screen. * **Consistent language:** Text casing and wording have been standardised across the console. #### 4. Automations & Reconciliation **Safer Workflow Management and Improved Reconciliation** The workflow automation studio and reconciliation tooling have been substantially improved. * **Safer import/export:** Automation workflows can now be imported and exported more safely, with a dry-run preflight check that validates a workflow before it runs. * **Graceful version handling:** Node version mismatches are now handled gracefully instead of causing failures. * **Advanced node section:** Nodes are now organised into a recategorised, easier-to-navigate advanced section. * **Automated, annotated reconciliation:** Reconciliation runs can now be automated and produce annotated output, with a new results-and-details page for reviewing outcomes. #### 5. Credit, Collateral & Entities **Continued Maturity Across Lending and Entity Management** * **Automatic pledgee updates:** Pledgee status now updates automatically as loans approach maturity. * **Scheduled invoicing:** Principal, interest, and fee invoices can now be generated automatically on a schedule based on product parameters. * **Refined maturity handling:** Contract maturity and termination logic has been refined for greater accuracy. * **Redesigned entity experience:** The entity picker and business detail views have been redesigned as part of an underlying rework of our entity data model. #### 6. Improvements and Fixes * **Stronger authentication:** Added passcode and biometric sign-in support, plus step-up verification on sensitive payment and beneficiary operations. * **More reliable payments and payees:** Stricter session validation, more accurate payee approval status, and correct handling when a new account is added to an existing payee. * **Improved automations:** Fixes to condition nodes, message-template selection, and workflow editing states. * **Fixed a wide range of issues** across payments, approvals, credit and collateral, the treasury web app, ledger, access management, and the console — including server errors on payment creation, duplicate company and user entries, broken date-range filters, pagination defects, and several display and layout issues. # XYB Platform 2.4 Release Notes ## #### 1. Ledger Precision Upgrade **Exact Accuracy for Large Balances and High-Precision Assets** This release delivers a platform-wide upgrade to how monetary amounts are stored and calculated, ensuring accuracy for very large balances and high-precision assets. * **No more precision limits:** Ledger values across the platform have been migrated to arbitrary-precision numeric handling, removing previous limits on the size and precision of amounts. * **Crypto asset support:** This upgrade underpins support for high-precision and crypto assets, including ETH and BTC, now available in the ledger currency selector. * **Exactness at scale:** Balances, postings, and interest calculations remain exact even for very large or high-precision amounts. #### 2. Product Configuration Enhancements **Easier, More Reliable Configuration** Product configuration becomes easier and more reliable to work with, with clearer data handling and improved display. * **Persistent across tabs:** Configuration entered across multiple tabs is now preserved as you move between them. * **Scoped validation:** Validation errors in one tab no longer block saving unrelated changes elsewhere. * **Clearer terminology:** "Banking providers" has been renamed to "Banking coordinates" for clarity. * **Easier service selection:** The add-service dialog is now alphabetically ordered and searchable. * **Richer display:** Configuration screens now show additional metadata to give you more context at a glance. #### 3. Deposit & Credit Products **An Expanding Product Set** The credit and deposit product set continues to expand. * **Deposit products:** A new deposit product data model has been introduced. * **Credit line term changes:** Credit lines now support term changes, with accrued interest calculated automatically. * **Separated accounts:** Payout and repayment accounts on credit contracts are now separated, and account selection within credit contracts has been improved. * **Open an account from the entity view:** Businesses can now open an account directly from the entity view after adding a product. #### 4. Entities & Onboarding **More Flexibility and Clearer Structure** Entity management gains more flexibility and clearer structure. * **Extended entity types:** "Application" is now "API", with new "MCP" and "AI Agent" types added. * **Role-aware views:** Entity views now adapt to show only the tabs relevant to each entity's role and available services. * **Richer onboarding data:** Economic activity and tax residency can now be captured at entity creation. * **New Owner role and dashboard:** A tailored role and dashboard give single-operator businesses a treasury experience suited to how they actually work. #### 5. Localisation & Reconciliation **Broader Language Coverage, Progress Toward Automated Reconciliation** Localisation coverage and reconciliation tooling both move forward. * **Expanded translations:** Translated content now extends to configuration and policy screens across the platform. * **Language consistency:** British-to-American English inconsistencies have been corrected across the app. * **Reconciliation pilot:** A pilot program defines the scope and flow for automated reconciliation ahead of a wider rollout. #### 6. Improvements and Fixes * **More accurate statements and balances**, including a fix to an inverted closing-balance sign and correct decimal handling on posting detail and payment views. * **Improved mobile experience**, with fixes to Android home, cards, statements, payment calculation, and onboarding flows. * **Steadier treasury web app**, resolving load failures on the asset position and statements pages and stabilising the account balances view. * **Fixed a wide range of issues** across product configuration, templates, automations, entities, access management, and the console — including tab persistence, template selection, filter counts, tooltips, and numerous table and layout issues. # XYB Platform 2.5 Release Notes #### 1. Reconciliation Console **Reconciliation Becomes a First-Class, Reviewable Workflow** This release delivers a full reconciliation experience in the Console, moving reconciliation from a background process into a first-class, reviewable workflow. * **Dedicated activity view:** Operators can now view reconciliation activity in a dedicated list. * **Drill into a run:** Each run can be reviewed across accounts and transactions tabs. * **Resolve exceptions directly:** Exceptions can be resolved in place — creating a missing account, creating a matching payment, or re-running matching. * **Reusable profiles and run sets:** Reconciliation is organised around reusable profiles and run sets, with per-profile display columns, coverage checks before a run, and clear exception counts throughout. #### 2. Enterprise SSO: SCIM Provisioning **Automated User and Group Management for Enterprise Customers** Enterprise identity management is significantly strengthened with SCIM 2.0 user and group provisioning, complementing existing SAML 2.0 single sign-on. * **Automated provisioning:** Identity providers can now automatically provision and de-provision users and groups. * **Role sync:** Role membership stays in sync automatically, with access managed centrally from your identity provider. * **Clear ownership:** SCIM-managed roles are shown as read-only in the Console, so it's always clear where a role is being controlled from. * **Broad compatibility:** Provisioning has been validated against major identity providers. #### 3. Payment Timeline & Failed Payment Handling **Full Visibility into Where a Payment Stands** Payments become far more transparent, with a full status timeline and clearer handling of failures. * **Detailed status timeline:** Payment history now includes a detailed timeline of status events, so you can see exactly where a payment is in its lifecycle — including payments that are stuck or delayed. * **Correct handling of failures:** Failed payments are now handled correctly in the ledger, ensuring postings do not remain pending when a payment fails. #### 4. Payment Rails: Wire, BAI2 & BTRS3 **Expanded Rail Coverage and Standards-Compliant Reporting** Payment rail coverage expands with wire file generation and standards-compliant reporting. * **Wire support:** Wire files can now be composed to the ISO 20022 pacs.008 standard. * **BAI2 and BTRS3 reporting:** Reporting files can now be generated from unified platform data, including full ACH addenda linkage. * **Two-step authorisation:** Two-step authorisation is now supported for partner payments. #### 5. Terms & Conditions Management **Manage, Version, and Track Acceptance of Customer Terms** A new terms-and-conditions capability lets banks manage, version, and capture acceptance of customer terms. * **Authoring and versioning:** Terms can be authored and versioned with four-eye approval. * **Template integration:** Terms integrate with the existing template system. * **Customer acceptance:** Terms are presented to customers for acceptance, with a full audit trail of who accepted which version and when. #### 6. Improvements and Fixes * **Redesigned payment activity screen** in the web app, with batches shown in activity and clearer payment detail. * **More reliable treasury workflows**, including fixes to scheduled payments, batch approvals, payee and account editing, and statement imports. * **More accurate money display**, with exact decimal handling on payment volume and posting search surfaces. * **Fixed a wide range of issues** across payments, beneficiaries, cards, policies, reconciliation, and the console — including card activation, top-up, policy visibility, and numerous treasury web app display and saving issues. # XYB Platform 2.6 Release notes #### 1. Open Banking **Connect External Accounts and Move Money Between Them** This release introduces open banking on the platform, allowing customers to connect their accounts at other banks and move money between them. * **Link external accounts:** Customers can link an external bank account and see aggregated balances and transactions alongside their XYB accounts. * **Top up and pay from elsewhere:** Top up from a linked bank, or initiate a payment funded from an account held elsewhere. * **Full consent journey:** Granting, viewing, and revoking access is covered end to end, with a connected-apps view so customers can see exactly which third parties hold access and withdraw it at any time. * **XYB as a provider:** The platform also now serves as a provider, exposing XYB-held accounts and payments to authorised third parties, with a bank picker, provider directory, and institution catalogue included. #### 2. Identity Verification **A Provider-Agnostic Verification Engine with Back-Office Visibility** Identity verification becomes a first-class, provider-agnostic capability with back-office visibility. * **Multiple providers, one interface:** A new identity verification engine supports multiple verification providers behind a single interface, with runtime failover between them if one is unavailable. * **Back-office visibility:** Operators gain a verifications view on the entity record, showing verification history and evidence. * **Policy integration:** Verification outcomes now feed policy decisions directly, so a journey can require a verified identity before proceeding. #### 3. Enterprise Identity: Ping Identity **PingOne as a Login and MFA Provider** Ping Identity (PingOne) is now supported as both a primary login provider and a multi-factor authentication provider. * **Direct authentication:** Banks using PingOne can authenticate customers directly against it. * **MFA and step-up:** Enrol and activate MFA devices, and issue standalone step-up challenges. * **Authorisation delegation:** Delegate authorisation decisions to PingOne Authorize, and use PingOne Verify as an identity verification provider. * **Configurable per entity:** Provider selection is configurable per entity, so different customer populations can use different identity providers on the same platform. #### 4. OAuth 2.0 and OpenID Connect **A Standards-Compliant Authorisation Server** A standards-compliant authorisation server is now part of the platform. * **Full OAuth/OIDC support:** The platform issues and manages OAuth 2.0 grants with OpenID Connect support, including pushed authorisation requests, private key JWT client authentication, the client credentials grant, a UserInfo endpoint, and token revocation to RFC 7009. * **Scoped and configurable:** Grants are bound to the resource server they were issued for, and token lifetimes are configurable per product. * **Fully audited:** The full grant lifecycle is audited. #### 5. Multi-Ledger Support **Run More Than One Ledger, with Full Control Over Routing** Banks can now run more than one ledger behind the platform and control which ledger each product and payment uses. * **Multi-ledger account creation:** Accounts can be created across multiple configured ledgers with all-or-nothing completion. * **Configurable targets:** Ledger targets can be set per product and per payment, with an allow-list controlling which ledgers a given payment may reach. * **Traceable end to end:** Payments carry the product version and ledger target from submission through execution, and per-ledger activity is separately observable. #### 6. Reconciliation: Scheduling and Resolution **From Manual Runs to Scheduled, Self-Service Reconciliation** Reconciliation moves from manual runs to scheduled, self-service operation with a guided resolution flow. * **Scheduled runs:** Reconciliations can now be scheduled on a configured cadence, with runs that wait for their data rather than failing, and clear reporting of waiting, started, and missed windows. * **Guided resolution:** Exception resolution is driven by a catalogue of resolution modes with typed, pre-filled fields drawn from the row being resolved. * **Approval-aware:** Resolutions that require four-eye approval link directly to the pending approval. * **Configurable and recoverable:** Reconciliation profiles can be configured per business customer, a failed run set can be re-run as a fresh run, and every reconciliation carries a queryable audit trail. #### 7. Device Binding **Link, Manage, and Revoke Customer Devices** Customers' devices can now be linked to their identity, managed, and revoked. * **Secure linking:** Device linking uses an SMS verification ceremony, with a configurable limit on linked devices per customer. * **Linked at onboarding:** A customer's first device is linked automatically during onboarding. * **Operator management:** Operators can search and manage devices across customers from the console, and revoking a device immediately ends its sessions. * **Full audit trail:** Every link and revoke leaves a durable record. #### 8. Payments: ACH, Wire and Live Balances **More Transparency and Broader Rail Coverage** Payment operations gain more transparency and better rail coverage. * **Upfront timing information:** Customers can see ACH and wire cutoff times and same-day handling before they submit, choose a payment tier, and see the settlement batch a payment falls into. * **Broader ACH support:** WEB debit origination is now supported on ACH. * **Flexible wire addressing:** Wire beneficiary addresses can be supplied in structured or unstructured format. * **Live balances:** Account balances can now be retrieved live from the banking provider, with ledger, available, and float balances mapped and validated against the platform ledger. #### 9. Improvements and Fixes * **More reliable approval enforcement**, including fixes where payee creation bypassed a configured approval policy and where assessment-policy thresholds were not applied. * **A clearer payment audit trail**, showing the approver rather than the payment creator on approval events, and payment method on payments awaiting approval. * **Numerous console display fixes**, covering overlapping table columns, clipped detail tables, unscrollable filters, and names shown as raw references instead of readable values. * **Fixed a range of issues** across payments, treasury, cards, reconciliation, terms and conditions, and the console, including FedWire payment failures, card search filters, enquiry search, statement scheduling, and payment history search. # Welcome to XYB Payments! Welcome to the XYB Payments Platform! A modern, API-first payment orchestration layer built for banks, fintechs, and financial institutions who want full control over how money moves. Whether you're sending payroll, processing user transfers, or integrating card payouts, our platform helps you **build it faster, scale it confidently, and stay compliant.** ***
Getting StartedXYB Payments overviewcard-getting-started.png
Payment Setup & ArchitectureUnderstanding the XYB Payment Ecosystemcard-integrate.png
Workflows & Payment LifecyclesPlanning your Payments Infrastructurecard-workflow.png
Payment Operations & SupportBuild a Customer Facing Fund Transfer Flowuser ops.png
# XYB Payments overview Welcome to the XYB Payments Platform! A modern, API-first payment orchestration layer built for banks, fintechs, and financial institutions who want full control over how money moves. Whether you're sending payroll, processing user transfers, or integrating card payouts, our platform helps you **build it faster, scale it confidently, and stay compliant.** *** ### What You Can Do With the Payments Platform, you can: * **Send Payments Anywhere**\ Domestic, international, internal transfers, with support for cards, bank accounts, and payment partners. * **Orchestrate Complex Workflows**\ Define how payments are processed: risk checks, ledger steps, approvals, settlement rules, all fully customizable. * **Integrate with Core Banking**\ Seamless connections with account, card, and ledger services to enrich, validate, and manage payments end to end. * **Track Every Step**\ From creation to settlement, monitor the full lifecycle of each payment with real-time visibility. * **Take Action When Needed**\ Cancel, retry, roll back payment operations can be triggered manually or programmatically. *** ### How It Works (At a Glance) Here’s what happens when you initiate a payment: 1. **You send a payment request** using our API, including details like sender, amount, and receiver. 2. **We validate and enrich the data** by fetching account, card, and beneficiary details from your ecosystem. 3. **We identify the workflow**, i.e., what steps are required for this payment type (e.g., ledger auth, risk check). 4. **The Payment Engine takes over** to orchestrate all steps: reserving funds, calling partners, and updating statuses. 5. **You get real-time updates** as the payment moves through the pipeline. 6. **Once complete**, payment data is stored in the Payment History service and made available via APIs or admin tools. 7. **If needed**, use Payment Operations UI to intervene (cancel, retry, etc.). (coming soon) *** ### Built for Developers We’ve designed this platform to be: * **API-first** with detailed OpenAPI documentation * Easy to test in sandbox environments * Fully event-driven (via Kafka) for real-time use cases * Extensible with custom workflows and adapters *** ### Key Components | Component | Role | | ---------------------- | ---------------------------------------------------------------- | | **Payment Service** | Entry point receives and validates payment request | | **Payment Engine** | Orchestrates the full payment workflow | | **Workflow Engine** | Defines and configures how each payment should be processed | | **Payment History** | Stores finalized payments for end-user visibility and audits | | **Payment Operations** | Allows support teams to cancel, retry, or manage payments | | **Adapters** | Integrations with third-party payment partners (e.g., Visa, TCC) | *** ### Typical Use Cases * **Fintech App**: Offer real-time SEPA and internal transfers to users across Europe * **Marketplace Platform**: Payout seller earnings to cards and bank accounts * **Corporate Treasury**: Automate bulk payroll, vendor payments, and FX transfers * **Regulated Institution**: Perform multi-step approval flows with full audit trails # 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.
StepWhat Happens
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
*** # Understanding the XYB Payment Ecosystem The XYB Payment Ecosystem powers modern, real-time, and multi-channel payments, from initiation to clearing and settlement, through a modular, scalable architecture. This guide gives you a high-level overview of how payments are created, processed, orchestrated, and stored using XYB’s services.
### Who Uses What? | Audience | Touchpoints | | -------------------------- | -------------------------------------------------- | | **Client developers** | Payment API, adapter contracts, snapshot consumers | | **Treasury/support teams** | Payment operations UI (e.g. rollback, cancel) | | **Compliance & Risk** | Risk engine integrations, audit trails | | **Partners** | Adapters and contracts | *** # 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 # Add and Manage Beneficiary Accounts Adding a beneficiary is a critical step in any payment workflow. With XYB’s Beneficiary APIs, developers can securely collect, verify, and manage recipient details, adapting to local compliance rules across countries and payment types. Instead of hardcoding forms for every region, you can use our API to dynamically fetch required fields, validate inputs, and keep your front-end flexible. *** ### Workflow Overview Here’s how you should implement beneficiary creation in your system: | Step | Description | API | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | 1. Identify Customer | Assign or generate an `identityReference` for the logged-in customer. This will link all beneficiaries to that customer. | *Handled by your system* | | 2. Fetch Dynamic Field Requirements | Get the required fields (based on country, currency, payment method) for account creation. | `GET /api/v1/fields/{identityReference}/contact-account` | | 3. Build the Beneficiary Form | Dynamically render the form based on the above specs. Some fields may be mandatory, optional, or conditional. | Front-end logic | | 4. Submit Beneficiary | Send beneficiary data to create them. | `POST /api/v1/beneficiary/identity/{identityReference}` | | 5. Handle Dynamic Coordinates (if needed) | For payment types like SWIFT/BSB, collect additional fields via dynamic schema. | `POST /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates` | | 6. (Optional) Verify with OTP | Some beneficiary account types require OTP verification before activation. | `GET` + `POST` verification endpoints | | 7. Ready for Payment | Once verified and stored, the beneficiary and their accounts can be used in any payment request. | | *** ### Fetch Dynamic Field Specifications Use this endpoint to get field requirements based on `identityReference`: ``` GET /api/v1/fields/{identityReference}/contact-account ``` #### Response ```json { "groups": [ { "label": "Bank Details", "fields": [ { "name": "iban", "label": "IBAN", "required": true, "type": "string", "validation": { "regex": "..." } }, { "name": "bic", "label": "BIC", "required": false, "type": "string" } ] } ] } ``` #### What to Do Render a form based on this JSON. Required fields should be validated and included in your `POST` request. Optional fields can be skipped. *** ### Create a Beneficiary ``` POST /api/v1/beneficiary/identity/{identityReference} ``` #### Sample Request Body ```json { "first_name": "Alice", "last_name": "Smith", "organization_name": null, "contacts": [ { "email": "alice@example.com", "mobile_prefix": "+44", "mobile_number": "7000000000" } ], "addresses": [ { "address": "123 Main St", "city": "London", "country": "GB", "post_code": "W1A 1AA" } ], "coordinates": { "banking": { "iban": "GB82WEST12345698765432" }, "currency_code": "EUR" } } ``` #### Required Fields * At least one name field: `first_name` or `organization_name` * At least one account coordinate * Optionally include contact and address for verification or policy requirements *** ### Optional: Add Dynamic Coordinates If the country or currency requires additional information: ``` POST /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates ``` Use this if the earlier coordinate creation step requires extra dynamic fields like: * BSB codes (Australia) * SWIFT codes (international wires) * IFSC codes (India) The `CreateBeneficiaryCoordinateDynamicRequest` format will match what was returned in dynamic specs. *** ### OTP Verification (If Required) Some destinations require user verification (e.g., SMS OTP): **Send OTP** ``` GET /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification ``` **Submit OTP** ``` POST /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid} { "otp": "123456" } ``` *** ### Final Validation Before using the beneficiary in a payment, validate their data against the target payment route: ``` POST /api/v1/fields/{identityReference}/payment/validate ``` This ensures: * All required fields are populated * No regulatory violations * The beneficiary is ready to receive money *** Bonus: Video – Integrating Beneficiary Flow into Send Money UI > [Watch Video: Building a Beneficiary Form and Connecting to Payment Flow](https://chatgpt.com/g/g-p-67f79876be508191bbaafa9de483213f-ultimate-payments/c/67fcc1f8-16b8-8005-838a-ae5262dab908#) This short tutorial walks you through: * Creating a customer ID (`identityReference`) * Dynamically building a form using `/contact-account` specs * Submitting the beneficiary * Using them in a real payment request *** ### Key Reminders * Store the `beneficiary_id` and `beneficiary_account_id` after creation * A single `identityReference` may have multiple beneficiaries * Dynamic specs are region-, currency-, and policy-aware. Use them instead of hardcoding # Build a Customer Facing Fund Transfer Flow ### Overview This article shows how developers can build a payment flow where end users initiate a fund transfer, and the backend handles validation and moves funds from the sender to the beneficiary.\ By calling XYB’s Payments APIs, developers can retrieve sender and beneficiary information, load dynamic form fields, trigger built-in compliance and validation checks, and rely on the platform to process the payment and update downstream systems. Here's an overview of a typical payment workflow:
{% hint style="info" %} **Use case flexibility**\ You can tailor this workflow for various payment methods, currencies, and compliance requirements by leveraging XYB’s dynamic field specification APIs. {% endhint %} *** ### Prerequisites Before you begin, make sure: * You have an active `identityReference` for the payer (the customer or entity). [Learn more about linking entities.](/xyb-console/understanding-entities-in-xyb) * A beneficiary has been created and linked to the identity. [Learn how to create a beneficiary.](/xyb-platform-1/xyb-payments/payment-setup/add-and-manage-beneficiary-accounts) * Your payment infrastructure is ready (e.g., ledger, workflows, compliance rules are active). [Learn more here](/xyb-platform-1/xyb-payments/getting-started-with-payments/planning-your-payments-infrastructure). {% hint style="warning" %} **Note:** If any of the above conditions aren’t met, the payment request will fail validation or execution. {% endhint %} *** ### Step-by-Step Workflow 1. Render a UI in your frontend where the user can select the payer account (linked customer entity as mentioned above) and the beneficiary (already created). 2. Call the following API to get the dynamic fields needed for this specific payment. ```http GET /api/v1/fields/{identityReference}/payment?beneficiaryAccountIdOptional={uuid} ``` * **Path Parameter**: `identityReference` (payer's entity) * **Query Parameter**: `beneficiaryAccountIdOptional` (optional but recommended) \ **Result:** You get a JSON response containing all required field groups, input formats, validation patterns, and visibility conditions for this payment.
Sample Response ```json { "fields": [ { "name": "iban", "label": "IBAN", "type": "string", "required": true, "validationPattern": "^[A-Z]{2}\\d{2}[A-Z0-9]{1,30}$", "visible": true }, { "name": "purpose_code", "label": "Purpose", "type": "dropdown", "required": false, "options": ["SALA", "PENS", "GOVT"], "visible": true }, { "name": "tax_id", "label": "Tax ID", "type": "string", "required": false, "visible": false } ] } ```
3. Use the response to build a dynamic form for the user to fill. This form is customer-facing and should allow entry of details like IBAN, routing number, and payment purpose. {% hint style="info" %} * Show only the required fields for that scenario * Apply the field order and input validation (e.g. regex, required flags) * Implement visibility logic for conditional fields (e.g. show SWIFT fields only when needed) {% endhint %} 4. Call the validation API once the customer submits the form to validate all the information provided. ```http POST /api/v1/fields/{identityReference}/payment/validate ``` **Sample Request body:** ```json { "beneficiary_account_uuid": "...", "beneficiary_uuid": "...", "currency": "EUR", "fields": { "iban": "DE1234567890", "purpose_code": "SALA" } } ``` #### Field Reference
FieldTypeRequiredDescription
beneficiary_account_uuidstringYesUUID of the account receiving funds.
beneficiary_uuidstringYesUUID of the recipient party.
currencystringYesISO 4217 currency code (e.g., EUR, USD).
fields.ibanstringYesInternational Bank Account Number of the recipient.
fields.purpose_codestringOptional/Required (depends on currency & destination)Purpose classification (e.g., SALA for salary).
Sample Success and Error Responses #### Success Response ```json { "status": "valid", "validation_id": "val_abc123", "messages": [] } ``` #### Error Response ```json { "status": "invalid", "messages": [ { "field": "iban", "error": "Invalid IBAN format for the selected country" }, { "field": "purpose_code", "error": "Missing required field for EUR payments" } ] } ```
{% hint style="success" %} * Validation is **synchronous** and returns immediately with the validation result. * This API is typically called **after the customer submits a form** but **before the actual payment request** is made. * Only proceed if the validation passes. Return error messages to the customer if needed. {% endhint %} *** 5. Call the main payment initiation API to initiate a payment request after all validations are complete. **Endpoint:** ```http POST /api/payments/ ``` **Sample Request** ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "mandate": "user_001", "basis": { "from_account": "acc_123", "to_account": "acc_456" }, "attributes": { "reference": "Invoice #4598", "notes": "Urgent payment" }, "party_amount": { "value": 250.00, "currency": "USD" } } ``` **Request Body Parameters**
FieldTypeRequiredDescription
idstring (UUID)YesUnique identifier for the payment request
mandatestringYesReference to the user or entity initiating the payment
basisobjectYesDetails of the party and beneficiary accounts
attributesobjectYesDynamic key-value pairs from your frontend form
party_amountobjectConditionalAmount to be debited from the initiating party
other_party_amountobjectConditionalAmount to be credited to the beneficiary
Sample Success and Error Responses #### Sample Success Response ```json { "payment_id": "pay_abc789", "status": "initiated", "timestamp": "2025-07-22T10:30:00Z" } ``` #### Error Response Example ```json { "error": "invalid_mandate", "message": "Mandate user_001 does not exist or lacks permissions." } ```
*** ### Outcome Once the payment is successfully submitted: * XYB initiates the fund transfer * Transaction is routed via the configured adapter (e.g. SEPA, SWIFT, internal) * Ledger and account balances are updated * Transaction statuses are reflected in the Console and API responses **To understand the end-user experience, watch this video demonstration of a payment flow in XYB’s white-labeled mobile banking app.** {% embed url="" %} ### Also check out: {% content-ref url="/pages/3aMNMNc9uQh8Ax8l0cx7" %} [Configure Third-Party Adapter](/xyb-platform-1/xyb-payments/payment-setup/configure-third-party-adapter) {% endcontent-ref %} {% content-ref url="/pages/3KgQRN6BmkxcSaQwtgw8" %} [Broken mention](broken://pages/3KgQRN6BmkxcSaQwtgw8) {% endcontent-ref %} # Understanding PaymentRequest Schema # Common Validation Errors & How to Fix Them # 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 # Using Payment History & Event Tracking # Understanding Snapshots & Deltas # Payment History APIs (Querying Transactions) # Real-Time Events (Kafka Topics & Webhooks) # Building Customer-Facing UIs With Events # Payment Workflows **Payment Workflows** in the XYB Console are prebuilt, configurable flows designed to automate and control the lifecycle of a payment from initiation through validation, creation, authorization, and final clearance. These workflows allow you to: * Standardize payment logic across your platform * React dynamically to failures or alternate states * Integrate payment activity with other services like tasks, alerts, and ledger updates
*** ### What You Can Define Within a payment workflow, you can visually orchestrate how the system handles different events and states. For example: * What happens when a payment is *requested*? * How should the system respond if validation fails? * When is a payment marked as *authorized* or *cleared*? * What happens when a payment is *failed*? Each of these can be represented as a node in the workflow, giving you full control over execution logic. *** ### Key Components * **Start** node: The entry point to the flow * **Payment state nodes**: Represent transitions like `REQUESTED`, `VALIDATED`, `CREATED`, `AUTHORIZED`, `FAILED`, or `CLEARED` * **Conditional branches**: Define what happens based on success or failure * **End** node: Marks the conclusion of a path You can customize the logic between these nodes using platform events, variables, and service calls to enforce business rules. ### Who Is It For? Payment workflows are typically used by: * **Ops teams**, to define and adjust how payments behave * **Product managers**, to prototype and test payment logic * **Compliance or risk teams**, to introduce additional steps based on payment data *** # Standard Payment Flow - Tutorial Learn how to configure and activate a **Standard Outbound Payment Flow,** a built-in workflow for handling the end-to-end lifecycle of outbound payments: from request, validation, and creation to authorization and clearance. #### Step 1: Create a New Workflow 1. Go to **Workflows** > **Payments** 2. Click + **New Workflow**.
3. In the **Plan** dropdown, select **Payment flow plan**. This is a pre-defined template that covers the full lifecycle of an outbound payment, handling validation, creation, authorization, and clearance steps automatically within the platform. 4. Give your workflow a name, e.g., Outbound EUR Payment 5. Choose a **workflow reference** (usually you can leave it as the default workflow-name unless you need to reference it programmatically) 6. Add a **description** to explain the purpose of the workflow. 7. Click **Create workflow.** #### Step 2: Configure Workflow Parameters The workflow canvas appears as you create the new workflow with pre-defined settings. This workflow defines the full lifecycle of an outbound payment—from the initial request and validation to creation, authorization, and final clearance. If validation fails, the payment is marked as invalid; if successful, it progresses through creation and authorization steps before reaching a cleared or failed state.
1. **Click Edit parameters** on top right. These parameters make the flow executable by telling it: * Which schema to use (how to interpret the payment) * How to move money across accounts (ledger movement instructions)
2\. Fill in the Schema Name and Ledger Instructions. 3. Click **Save parameters**. 4. Once reviewed, click **Activate** at the top right to make the workflow live. # Beneficiary Management APIs ## POST /api/v1/beneficiary > Create a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary":{"post":{"tags":["BeneficiaryController"],"description":"Create a beneficiary","operationId":"BeneficiaryController::createBeneficiary","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"Beneficiary"}}}} ``` ## GET /api/v1/beneficiary/coordinates/{id} > Get a coordinate by id ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/coordinates/{id}":{"get":{"tags":["BeneficiaryCoordinateController"],"description":"Get a coordinate by id","operationId":"BeneficiaryCoordinateController::getCoordinatesById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/coordinates/{id}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coords"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_coords":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"Records an IBAN, account number, etc. for an account."},"entity":{"$ref":"#/components/schemas/cda_entity_schema_entity_entity","description":"The persisted entity. Note that this field is, in general, mutable."},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the beneficiary coordinates, generated on creation."}},"required":["id","entity","coordinates"],"title":"BeneficiaryCoords"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cda_entity_schema_entity_entity":{"type":"object","properties":{"affiliation":{"type":"string","enum":["CUSTOMER","INTERNAL","EXTERNAL"],"description":"Describes the relationship the entity has with XYB."},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/cda_entity_schema_entity_aspect_entity_aspect"},"description":"The list of aspects associated with the Entity"},"reference":{"type":"string","description":"Possibly a company number, a service identifier or an employee code"},"type":{"type":"string","enum":["INDIVIDUAL","ORGANIZATION","COLLECTIVE","VIRTUAL"],"description":"The type of the entity; determines how any entity reference is interpreted."}},"required":["type","affiliation"],"title":"Entity","description":"Something or someone who owns an account, or who interacts directly or indirectly with the system."},"cda_entity_schema_entity_aspect_entity_aspect":{"type":"object","properties":{"aspect":{"$ref":"#/components/schemas/cda_entity_schema_entity_aspect_aspect","description":"Concrete aspect"},"identifier":{"type":"string","format":"uuid","description":"A unique identifier for the aspect"},"relation":{"type":"string","description":"May be used to disambiguate aspects of the same type associated with the same entity"}},"required":["identifier","aspect"],"title":"EntityAspect"},"cda_entity_schema_entity_aspect_aspect":{"type":"object","properties":{},"title":"Aspect"}}}} ``` ## POST /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates > Get additional attributes for a coordinate ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates":{"post":{"tags":["BeneficiaryDynamicCoordinateController"],"description":"Get additional attributes for a coordinate","operationId":"BeneficiaryDynamicCoordinateController::createContactAccountDynamic","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request":{"type":"object","properties":{"alias":{"type":"string"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_coordinates"},"currency":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"required":["currency"],"title":"CreateBeneficiaryCoordinateDynamicRequest"},"cac_bnficiary_schema_dynamic_coordinates":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"secondary_identification":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicCoordinates"},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}} ``` ## PATCH /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId} > Update a coordinate for a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId}":{"patch":{"tags":["BeneficiaryDynamicCoordinateController"],"description":"Update a coordinate for a beneficiary","operationId":"BeneficiaryDynamicCoordinateController::updateContactAccountDynamic","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/dynamic/{identityReference}/{idRef}/coordinates/{coordinateId}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_create_beneficiary_coordinate_dynamic_request":{"type":"object","properties":{"alias":{"type":"string"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_coordinates"},"currency":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"required":["currency"],"title":"CreateBeneficiaryCoordinateDynamicRequest"},"cac_bnficiary_schema_dynamic_coordinates":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"secondary_identification":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicCoordinates"},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}} ``` ## POST /api/v1/beneficiary/identity/{identityReference}/ > Create beneficiary with identity ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/":{"post":{"tags":["BeneficiaryIdentityController"],"description":"Create beneficiary with identity","operationId":"BeneficiaryIdentityController::createBeneficiaryWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}} ``` ## GET /api/v1/beneficiary/identity/{identityReference}/list > Get all beneficiaries by identity ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/list":{"get":{"tags":["BeneficiaryIdentityController"],"description":"Get all beneficiaries by identity","operationId":"BeneficiaryIdentityController::getBeneficiaryList","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}} ``` ## GET /api/v1/beneficiary/identity/{identityReference}/payments > Get recently paid beneficiaries ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/payments":{"get":{"tags":["BeneficiaryIdentityController"],"description":"Get recently paid beneficiaries","operationId":"BeneficiaryIdentityController::getRecentlyPaidBeneficiaries","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/payments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_payment"}}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_payment":{"type":"object","properties":{"beneficiary_coordinate_id":{"type":"string","format":"uuid","description":"Beneficiary coordinate id related to this payment"},"beneficiary_id":{"type":"string","format":"uuid","description":"Beneficiary id related to this payment"},"created_at":{"type":"string","format":"date-time"},"payment_key":{"type":"string","description":"A unique identifier payment"}},"required":["payment_key","beneficiary_id","created_at"],"title":"BeneficiaryPayment"}}}} ``` ## POST /api/v1/beneficiary/identity/{identityReference}/sync > Sync beneficiaries ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/sync":{"post":{"tags":["BeneficiaryIdentityController"],"description":"Sync beneficiaries","operationId":"BeneficiaryIdentityController::syncContactBeneficiaries","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_sync_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/sync"}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_sync_request":{"type":"object","properties":{"contact_hashes":{"type":"array","items":{"type":"string"},"uniqueItems":true,"description":"The contact hashes of a customer phonebook that will be synced."}},"required":["contact_hashes"],"title":"BeneficiarySyncRequest","description":"Request to sync contacts of a customer phonebook with list of beneficiaries."}}}} ``` ## GET /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid} > Resend verification OTP to a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}":{"get":{"tags":["BeneficiaryVerificationController"],"description":"Resend verification OTP to a beneficiary","operationId":"BeneficiaryVerificationController::resendVerification","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"verificationUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coordinate_verification_response"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_coordinate_verification_response":{"type":"object","properties":{"beneficiary_coordinate_uuid":{"type":"string","format":"uuid"},"beneficiary_uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["VERIFIED","PENDING","FAILED"]},"verification_uuid":{"type":"string","format":"uuid"}},"required":["status","beneficiary_uuid","beneficiary_coordinate_uuid","verification_uuid"],"title":"BeneficiaryCoordinateVerificationResponse"}}}} ``` ## POST /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid} > Verify OTP for a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}":{"post":{"tags":["BeneficiaryVerificationController"],"description":"Verify OTP for a beneficiary","operationId":"BeneficiaryVerificationController::verifyCoordinate","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"verificationUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coordinate_verification_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/verification/{verificationUuid}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coordinate_verification_response"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_coordinate_verification_request":{"type":"object","properties":{"otp":{"type":"string","description":"One time passcode for beneficiary coordinate verification"}},"required":["otp"],"title":"BeneficiaryCoordinateVerificationRequest"},"cac_bnficiary_schema_beneficiary_coordinate_verification_response":{"type":"object","properties":{"beneficiary_coordinate_uuid":{"type":"string","format":"uuid"},"beneficiary_uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["VERIFIED","PENDING","FAILED"]},"verification_uuid":{"type":"string","format":"uuid"}},"required":["status","beneficiary_uuid","beneficiary_coordinate_uuid","verification_uuid"],"title":"BeneficiaryCoordinateVerificationResponse"}}}} ``` ## GET /api/v1/beneficiary/identity/{identityReference}/{idRef} > Get a beneficiary by idRef ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}":{"get":{"tags":["BeneficiaryIdentityController"],"description":"Get a beneficiary by idRef","operationId":"BeneficiaryIdentityController::getBeneficiaryWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}} ``` ## PATCH /api/v1/beneficiary/identity/{identityReference}/{idRef} > Update beneficiary with identity ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}":{"patch":{"tags":["BeneficiaryIdentityController"],"description":"Update beneficiary with identity","operationId":"BeneficiaryIdentityController::updateBeneficiaryWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}} ``` ## POST /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/ > Add a coordinate to a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/":{"post":{"tags":["BeneficiaryIdentityCoordinateController"],"description":"Add a coordinate to a beneficiary","operationId":"BeneficiaryIdentityCoordinateController::createCoordinateWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pay_entry_schema_account_coords"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_account_schema_account_coordinates"}}}}}}}},"components":{"schemas":{"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_account_schema_account_coordinates":{"type":"object","properties":{"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"Records an IBAN, account number, etc. for an account."},"external":{"type":"object","additionalProperties":{"type":"string"},"description":"Strictly optional external information for account coordinates."},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the account, generated on creation."},"tags":{"type":"array","items":{"type":"string"},"description":"Strictly optional application-scoped tags for the account coordinates."}},"required":["id","coordinates"],"title":"AccountCoordinates"}}}} ``` ## DELETE /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId} > Delete a coordinate from a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}":{"delete":{"tags":["BeneficiaryIdentityCoordinateController"],"description":"Delete a coordinate from a beneficiary","operationId":"BeneficiaryIdentityCoordinateController::deleteCoordinateWithIdentity","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}"}}}}}} ``` ## POST /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category} > Add a category to a coordinate ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category}":{"post":{"tags":["BeneficiaryIdentityCoordinateController"],"description":"Add a category to a coordinate","operationId":"BeneficiaryIdentityCoordinateController::addCoordinatePaymentCategory","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"category","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/category/{category}"}}}}}} ``` ## GET /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification > Send verification OTP to a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification":{"get":{"tags":["BeneficiaryVerificationController"],"description":"Send verification OTP to a beneficiary","operationId":"BeneficiaryVerificationController::sendVerification","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/identity/{identityReference}/{idRef}/coordinates/{coordinateId}/verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_coordinate_verification_response"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_coordinate_verification_response":{"type":"object","properties":{"beneficiary_coordinate_uuid":{"type":"string","format":"uuid"},"beneficiary_uuid":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["VERIFIED","PENDING","FAILED"]},"verification_uuid":{"type":"string","format":"uuid"}},"required":["status","beneficiary_uuid","beneficiary_coordinate_uuid","verification_uuid"],"title":"BeneficiaryCoordinateVerificationResponse"}}}} ``` ## GET /api/v1/beneficiary/{idRef} > Get a beneficiary by idRef ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}":{"get":{"tags":["BeneficiaryController"],"description":"Get a beneficiary by idRef","operationId":"BeneficiaryController::getBeneficiary","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"Beneficiary"}}}} ``` ## DELETE /api/v1/beneficiary/{idRef} > Delete a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}":{"delete":{"tags":["BeneficiaryController"],"description":"Delete a beneficiary","operationId":"BeneficiaryController::deleteBeneficiary","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}"}}}}}} ``` ## PATCH /api/v1/beneficiary/{idRef} > Update a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}":{"patch":{"tags":["BeneficiaryController"],"description":"Update a beneficiary","operationId":"BeneficiaryController::updateBeneficiary","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_details"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_request":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}},"alias":{"type":"string"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}},"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"The coordinates to initially assign to the account."},"external_reference":{"type":"string"},"first_name":{"type":"string"},"identity_reference":{"type":"string"},"last_name":{"type":"string"},"organization_name":{"type":"string"}},"title":"BeneficiaryRequest"},"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_bnficiary_schema_beneficiary_details":{"type":"object","properties":{"additional_fields":{"type":"object","additionalProperties":{"type":"string"}},"alias":{"type":"string"},"beneficiary_internal_coordinates":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_internal_coordinate"}},"contact_hash_list":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"dynamic_beneficiary_coords":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords"}},"external_reference":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"last_name":{"type":"string"},"organization_name":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at"],"title":"BeneficiaryDetails","description":"Details of a beneficiary with list of external and internal coordinates."},"cac_bnficiary_schema_beneficiary_internal_coordinate":{"type":"object","properties":{"account_uuid":{"type":"string","format":"uuid","description":"A globally unique identifier for the account."},"currencies":{"type":"array","items":{"type":"string"},"description":"List of currencies accepted for the account."},"is_verified":{"type":"boolean","description":"A globally unique identifier for the account."},"last_payment_date":{"type":"string","format":"date-time","description":"Last payment date"}},"required":["account_uuid","currencies","is_verified","last_payment_date"],"title":"BeneficiaryInternalCoordinate","description":"Internal coordinate values of a beneficiary."},"cac_bnficiary_schema_dynamic_beneficiary_coords":{"type":"object","properties":{"alias":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_coordinate_id":{"type":"string","format":"uuid"},"coordinates":{"$ref":"#/components/schemas/cac_bnficiary_schema_dynamic_beneficiary_coords_routing"},"currency":{"type":"string"},"first_name":{"type":"string"},"is_verified":{"type":"boolean"},"last_name":{"type":"string"},"last_payment_date":{"type":"string","format":"date-time"},"organization_name":{"type":"string"},"payment_type":{"type":"string"},"primary_coordinate_formats":{"type":"array","items":{"type":"string"}},"primary_coordinates":{"type":"array","items":{"type":"string"}}},"required":["beneficiary_coordinate_id","currency"],"title":"DynamicBeneficiaryCoords"},"cac_bnficiary_schema_dynamic_beneficiary_coords_routing":{"type":"object","properties":{"aba":{"type":"string"},"account_code":{"type":"string"},"account_number":{"type":"string"},"address":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"beneficiary_verification_type":{"type":"string"},"bic":{"type":"string"},"branch_code":{"type":"string"},"bsb":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"curp":{"type":"string"},"iban":{"type":"string"},"ifsc":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"purpose_code":{"type":"string"},"rfc":{"type":"string"},"sort_code":{"type":"string"},"state":{"type":"string"}},"title":"DynamicBeneficiaryCoordsRouting"}}}} ``` ## GET /api/v1/beneficiary/{idRef}/additional-attributes > Get additional attributes for a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/additional-attributes":{"get":{"tags":["BeneficiaryController"],"description":"Get additional attributes for a beneficiary","operationId":"BeneficiaryController::getBeneficiaryAdditionalDetails","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/additional-attributes","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}} ``` ## GET /api/v1/beneficiary/{idRef}/address > Get addresses for a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/address":{"get":{"tags":["BeneficiaryAddressController"],"description":"Get addresses for a beneficiary","operationId":"BeneficiaryAddressController::getAddresses","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/address","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address"}}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_address":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id"],"title":"BeneficiaryAddress"}}}} ``` ## POST /api/v1/beneficiary/{idRef}/address > Add an address to a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/address":{"post":{"tags":["BeneficiaryAddressController"],"description":"Add an address to a beneficiary","operationId":"BeneficiaryAddressController::addAddress","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_address"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_address_request":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"}},"required":["address","city","country","state","post_code","neighbourhood"],"title":"BeneficiaryAddressRequest"},"cac_bnficiary_schema_beneficiary_address":{"type":"object","properties":{"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"neighbourhood":{"type":"string"},"post_code":{"type":"string"},"state":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id"],"title":"BeneficiaryAddress"}}}} ``` ## DELETE /api/v1/beneficiary/{idRef}/address/{addressId} > Delete an address from a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/address/{addressId}":{"delete":{"tags":["BeneficiaryAddressController"],"description":"Delete an address from a beneficiary","operationId":"BeneficiaryAddressController::deleteAddress","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"addressId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/address/{addressId}"}}}}}} ``` ## GET /api/v1/beneficiary/{idRef}/contact > Get contacts for a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/contact":{"get":{"tags":["BeneficiaryContactController"],"description":"Get contacts for a beneficiary","operationId":"BeneficiaryContactController::getContact","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/contact","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact"}}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_contact":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":"string"},"id":{"type":"string","format":"uuid"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","email","mobile_prefix","mobile_number","created_at"],"title":"BeneficiaryContact"}}}} ``` ## POST /api/v1/beneficiary/{idRef}/contact > Add a contact to a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/contact":{"post":{"tags":["BeneficiaryContactController"],"description":"Add a contact to a beneficiary","operationId":"BeneficiaryContactController::createContact","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact_request"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_contact"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_contact_request":{"type":"object","properties":{"email":{"type":"string"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"}},"required":["email","mobile_prefix","mobile_number"],"title":"BeneficiaryContactRequest"},"cac_bnficiary_schema_beneficiary_contact":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":"string"},"id":{"type":"string","format":"uuid"},"mobile_number":{"type":"string"},"mobile_prefix":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","email","mobile_prefix","mobile_number","created_at"],"title":"BeneficiaryContact"}}}} ``` ## DELETE /api/v1/beneficiary/{idRef}/contact/{contactId} > Delete a contact from a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/contact/{contactId}":{"delete":{"tags":["BeneficiaryContactController"],"description":"Delete a contact from a beneficiary","operationId":"BeneficiaryContactController::deleteContact","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"contactId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/contact/{contactId}"}}}}}} ``` ## GET /api/v1/beneficiary/{idRef}/coordinates > Get coordinates for a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/coordinates":{"get":{"tags":["BeneficiaryCoordinateController"],"description":"Get coordinates for a beneficiary","operationId":"BeneficiaryCoordinateController::getCoordinate","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/coordinates","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/cac_account_schema_account_coordinates"}}}}}}}}},"components":{"schemas":{"cac_account_schema_account_coordinates":{"type":"object","properties":{"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"Records an IBAN, account number, etc. for an account."},"external":{"type":"object","additionalProperties":{"type":"string"},"description":"Strictly optional external information for account coordinates."},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the account, generated on creation."},"tags":{"type":"array","items":{"type":"string"},"description":"Strictly optional application-scoped tags for the account coordinates."}},"required":["id","coordinates"],"title":"AccountCoordinates"},"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."}}}} ``` ## POST /api/v1/beneficiary/{idRef}/coordinates > Add a coordinate to a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/coordinates":{"post":{"tags":["BeneficiaryCoordinateController"],"description":"Add a coordinate to a beneficiary","operationId":"BeneficiaryCoordinateController::createCoordinate","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pay_entry_schema_account_coords"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_account_schema_account_coordinates"}}}}}}}},"components":{"schemas":{"pay_entry_schema_account_coords":{"type":"object","properties":{"acceptor":{"$ref":"#/components/schemas/pay_entry_schema_acceptor"},"banking":{"$ref":"#/components/schemas/schema_payment_banking_coords_carrier"},"external":{"type":"object","additionalProperties":{"type":"string"}},"internal":{"$ref":"#/components/schemas/pay_entry_schema_internal_coords"},"reference":{"type":"string"}},"title":"AccountCoords","description":"A standard way of transmitting account coordinates between services."},"pay_entry_schema_acceptor":{"type":"object","properties":{"acquirer_id":{"type":"string","description":"The id of the acquirer on the card network"},"facilitator_id":{"type":"string","description":"The id of the payment facilitator (sub acceptor)"},"id":{"type":"string","description":"The id of the acceptor on the card network"},"mcc":{"type":"string","description":"The merchant category code, four numerical digits 0000-9999"},"terminal_id":{"type":"string","description":"Unique id identifying the terminal used"}},"title":"Acceptor","description":"A merchant qualified to accept credit or debit cards as payment"},"schema_payment_banking_coords_carrier":{"type":"object","properties":{"account_code":{"type":"string","description":"Used to record the combined account number and routing code (CLABE in MX)"},"account_number":{"type":"string","description":"Account number."},"account_type":{"type":"string","description":"Account type - has a national meaning in GT, IS, BR and BG."},"balance_account_number":{"type":"string","description":"The balance account according to the chart of accounts - used in Belarus. See https://www.nbrb.by/engl/payment/ibanbic"},"bank_code":{"type":"string","description":"The national bank code (as opposed to BIC.)"},"bic":{"type":"string","description":"The BIC code"},"bic_bank_code":{"type":"string","description":"The 4 letter SWIFT bank code."},"bic_branch_code":{"type":"string","description":"The 3 character SWIFT branch code."},"bic_location_code":{"type":"string","description":"The 2 character SWIFT location code."},"branch_code":{"type":"string","description":"Branch code (sort-code in UK, guichet-code in FR.)"},"country_code":{"type":"string","description":"Required in the absence of a BIC or IBAN"},"currency":{"type":"string","description":"Used in GT, MU & SC (two character in GT, three character elsewhere.)"},"iban":{"type":"string","description":"The account coordinates as an IBAN"},"national_id":{"type":"string","description":"National identifier - IS kennitala."},"owner_account_number":{"type":"string","description":"Used to identify individual accounts in Brazil."},"routing_code":{"type":"string","description":"Identifies the bank for an account, often combines institution and branch data."}},"title":"BankingCoordsCarrier","description":"Banking coordinates."},"pay_entry_schema_internal_coords":{"type":"object","properties":{"account_id":{"type":"string","format":"uuid","description":"The XYB assigned id for the account. This is not necessarily the id assigned by the ledger holder."},"account_reference":{"type":"string","description":"The reference for the account"},"card_id":{"type":"string","format":"uuid","description":"The XYB assigned card id for the account."},"contact_account_id":{"type":"string","description":"A id that reference a contact account."},"currency_code":{"type":"string","description":"The denomination of funds within the account."},"legacy_account_id":{"description":"The legacy XYB assigned id for the account.","type":"integer","format":"int64"},"wallet_address":{"type":"string","description":"The XYB ledger wallet address of wallet in ledger"},"wallet_code":{"type":"string","description":"The XYB ledger wallet code of account."}},"title":"InternalCoords","description":"Account coordinates that are used to conveniently identify accounts within the XYB system."},"cac_account_schema_account_coordinates":{"type":"object","properties":{"coordinates":{"$ref":"#/components/schemas/pay_entry_schema_account_coords","description":"Records an IBAN, account number, etc. for an account."},"external":{"type":"object","additionalProperties":{"type":"string"},"description":"Strictly optional external information for account coordinates."},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the account, generated on creation."},"tags":{"type":"array","items":{"type":"string"},"description":"Strictly optional application-scoped tags for the account coordinates."}},"required":["id","coordinates"],"title":"AccountCoordinates"}}}} ``` ## DELETE /api/v1/beneficiary/{idRef}/coordinates/{coordinateId} > Delete a coordinate from a beneficiary ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/beneficiary/{idRef}/coordinates/{coordinateId}":{"delete":{"tags":["BeneficiaryCoordinateController"],"description":"Delete a coordinate from a beneficiary","operationId":"BeneficiaryCoordinateController::deleteCoordinate","parameters":[{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}},{"name":"coordinateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/beneficiary/{idRef}/coordinates/{coordinateId}"}}}}}} ``` ## GET /api/v1/fields/{identityReference}/contact-account > Get contact account field specifications ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/fields/{identityReference}/contact-account":{"get":{"tags":["PaymentFieldsController"],"description":"Get contact account field specifications","operationId":"PaymentFieldsController::getContactAccountFieldSpecifications","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/fields/{identityReference}/contact-account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_payment_dynamic_fields_spec"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_payment_dynamic_fields_spec":{"type":"object","properties":{"spec":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_currency_specification"}}},"required":["spec"],"title":"DynamicFieldsSpec"},"pay_entry_schema_fieldspec_currency_specification":{"type":"object","properties":{"field_groups":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_field_group"}},"field_order":{"type":"array","items":{"type":"string"}}},"required":["field_order","field_groups"],"title":"CurrencySpecification"},"pay_entry_schema_fieldspec_field_group":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_field"}},"localized_name":{"type":"string"}},"required":["localized_name","fields"],"title":"FieldGroup"},"pay_entry_schema_fieldspec_field":{"type":"object","properties":{"additional_info":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_additional_info"},"input":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_input"},"input_pattern":{"type":"string"},"localized_hint":{"type":"string"},"localized_name":{"type":"string"},"option_decorations":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_option_decoration"}},"tags":{"type":"array","items":{"type":"string"}},"visibility_conditions":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_condition"}}},"required":["localized_name","localized_hint","additional_info","tags","input_pattern","visibility_conditions","option_decorations","input"],"title":"Field"},"pay_entry_schema_fieldspec_additional_info":{"type":"object","properties":{"link":{"type":"string"},"localized_text":{"type":"string"}},"required":["localized_text"],"title":"AdditionalInfo"},"pay_entry_schema_fieldspec_input":{"type":"object","properties":{"constraints":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_payment_field_constraint"}},"key":{"type":"string"},"options":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_option"}},"required_conditions":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_condition"}},"tags":{"type":"array","items":{"type":"string"}},"type":{"type":"string"}},"required":["key","type","tags","constraints","required_conditions","options"],"title":"Input"},"pay_entry_schema_fieldspec_payment_field_constraint":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"title":"PaymentFieldConstraint"},"pay_entry_schema_fieldspec_option":{"type":"object","properties":{"key":{"type":"string"},"properties":{"type":"object","additionalProperties":{"type":"string"}}},"required":["key","properties"],"title":"Option"},"pay_entry_schema_fieldspec_condition":{"type":"object","properties":{"depends_on":{"type":"string"},"selected_option":{"type":"string"},"selected_options":{"type":"array","items":{"type":"string"}},"type":{"type":"string"}},"required":["depends_on","type","selected_option","selected_options"],"title":"Condition"},"pay_entry_schema_fieldspec_option_decoration":{"type":"object","properties":{"key":{"type":"string"},"localized_name":{"type":"string"}},"required":["key","localized_name"],"title":"OptionDecoration"}}}} ``` ## GET /api/v1/fields/{identityReference}/payment > Get payment creation field specifications ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/fields/{identityReference}/payment":{"get":{"tags":["PaymentFieldsController"],"description":"Get payment creation field specifications","operationId":"PaymentFieldsController::getPaymentCreationFieldSpecifications","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"beneficiaryAccountIdOptional","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/fields/{identityReference}/payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_payment_dynamic_fields_spec"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_payment_dynamic_fields_spec":{"type":"object","properties":{"spec":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_currency_specification"}}},"required":["spec"],"title":"DynamicFieldsSpec"},"pay_entry_schema_fieldspec_currency_specification":{"type":"object","properties":{"field_groups":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_field_group"}},"field_order":{"type":"array","items":{"type":"string"}}},"required":["field_order","field_groups"],"title":"CurrencySpecification"},"pay_entry_schema_fieldspec_field_group":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_field"}},"localized_name":{"type":"string"}},"required":["localized_name","fields"],"title":"FieldGroup"},"pay_entry_schema_fieldspec_field":{"type":"object","properties":{"additional_info":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_additional_info"},"input":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_input"},"input_pattern":{"type":"string"},"localized_hint":{"type":"string"},"localized_name":{"type":"string"},"option_decorations":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_option_decoration"}},"tags":{"type":"array","items":{"type":"string"}},"visibility_conditions":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_condition"}}},"required":["localized_name","localized_hint","additional_info","tags","input_pattern","visibility_conditions","option_decorations","input"],"title":"Field"},"pay_entry_schema_fieldspec_additional_info":{"type":"object","properties":{"link":{"type":"string"},"localized_text":{"type":"string"}},"required":["localized_text"],"title":"AdditionalInfo"},"pay_entry_schema_fieldspec_input":{"type":"object","properties":{"constraints":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_payment_field_constraint"}},"key":{"type":"string"},"options":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_option"}},"required_conditions":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_condition"}},"tags":{"type":"array","items":{"type":"string"}},"type":{"type":"string"}},"required":["key","type","tags","constraints","required_conditions","options"],"title":"Input"},"pay_entry_schema_fieldspec_payment_field_constraint":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"title":"PaymentFieldConstraint"},"pay_entry_schema_fieldspec_option":{"type":"object","properties":{"key":{"type":"string"},"properties":{"type":"object","additionalProperties":{"type":"string"}}},"required":["key","properties"],"title":"Option"},"pay_entry_schema_fieldspec_condition":{"type":"object","properties":{"depends_on":{"type":"string"},"selected_option":{"type":"string"},"selected_options":{"type":"array","items":{"type":"string"}},"type":{"type":"string"}},"required":["depends_on","type","selected_option","selected_options"],"title":"Condition"},"pay_entry_schema_fieldspec_option_decoration":{"type":"object","properties":{"key":{"type":"string"},"localized_name":{"type":"string"}},"required":["key","localized_name"],"title":"OptionDecoration"}}}} ``` ## POST /api/v1/fields/{identityReference}/payment/validate > Validate payment creation ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/fields/{identityReference}/payment/validate":{"post":{"tags":["PaymentFieldsController"],"description":"Validate payment creation","operationId":"PaymentFieldsController::validatePaymentCreation","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_beneficiary_payment_creation_validation"}}},"required":true},"responses":{"200":{"description":"Response to /api/v1/fields/{identityReference}/payment/validate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_payment_payment_validation_error_response"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_beneficiary_payment_creation_validation":{"type":"object","properties":{"beneficiary_account_uuid":{"type":"string","format":"uuid"},"beneficiary_uuid":{"type":"string","format":"uuid"},"currency":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}},"required":["beneficiary_uuid","beneficiary_account_uuid","currency","fields"],"title":"BeneficiaryPaymentCreationValidation"},"cac_bnficiary_schema_payment_payment_validation_error_response":{"type":"object","properties":{"violations":{"type":"array","items":{"$ref":"#/components/schemas/cac_bnficiary_schema_payment_localised_payment_field_violation"},"uniqueItems":true}},"required":["violations"],"title":"PaymentValidationErrorResponse"},"cac_bnficiary_schema_payment_localised_payment_field_violation":{"type":"object","properties":{"key":{"type":"string"},"localized_message":{"type":"string"}},"required":["key","localized_message"],"title":"LocalisedPaymentFieldViolation"}}}} ``` ## POST /api/v1/sync/interrupt > Interrupt the synchronization process ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/sync/interrupt":{"post":{"tags":["CustomerUpdateSyncController"],"description":"Interrupt the synchronization process","operationId":"CustomerUpdateSyncController::interruptSync","responses":{"200":{"description":"Response to /api/v1/sync/interrupt"}}}}}} ``` ## POST /api/v1/sync/manual > Manually initiate the synchronization process ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/sync/manual":{"post":{"tags":["CustomerUpdateSyncController"],"description":"Manually initiate the synchronization process","operationId":"CustomerUpdateSyncController::doManualSyn","responses":{"200":{"description":"Response to /api/v1/sync/manual"}}}}}} ``` # Payment Request Flow APIs ## GET /api/v1/fields/{identityReference}/payment > Get payment creation field specifications ```json {"openapi":"3.0.3","info":{"title":"eneficiary Service","version":"0.8.3-7e7350e"},"paths":{"/api/v1/fields/{identityReference}/payment":{"get":{"tags":["PaymentFieldsController"],"description":"Get payment creation field specifications","operationId":"PaymentFieldsController::getPaymentCreationFieldSpecifications","parameters":[{"name":"identityReference","in":"path","required":true,"schema":{"type":"string"}},{"name":"beneficiaryAccountIdOptional","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Response to /api/v1/fields/{identityReference}/payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/cac_bnficiary_schema_payment_dynamic_fields_spec"}}}}}}}},"components":{"schemas":{"cac_bnficiary_schema_payment_dynamic_fields_spec":{"type":"object","properties":{"spec":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_currency_specification"}}},"required":["spec"],"title":"DynamicFieldsSpec"},"pay_entry_schema_fieldspec_currency_specification":{"type":"object","properties":{"field_groups":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_field_group"}},"field_order":{"type":"array","items":{"type":"string"}}},"required":["field_order","field_groups"],"title":"CurrencySpecification"},"pay_entry_schema_fieldspec_field_group":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_field"}},"localized_name":{"type":"string"}},"required":["localized_name","fields"],"title":"FieldGroup"},"pay_entry_schema_fieldspec_field":{"type":"object","properties":{"additional_info":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_additional_info"},"input":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_input"},"input_pattern":{"type":"string"},"localized_hint":{"type":"string"},"localized_name":{"type":"string"},"option_decorations":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_option_decoration"}},"tags":{"type":"array","items":{"type":"string"}},"visibility_conditions":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_condition"}}},"required":["localized_name","localized_hint","additional_info","tags","input_pattern","visibility_conditions","option_decorations","input"],"title":"Field"},"pay_entry_schema_fieldspec_additional_info":{"type":"object","properties":{"link":{"type":"string"},"localized_text":{"type":"string"}},"required":["localized_text"],"title":"AdditionalInfo"},"pay_entry_schema_fieldspec_input":{"type":"object","properties":{"constraints":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_payment_field_constraint"}},"key":{"type":"string"},"options":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_option"}},"required_conditions":{"type":"array","items":{"$ref":"#/components/schemas/pay_entry_schema_fieldspec_condition"}},"tags":{"type":"array","items":{"type":"string"}},"type":{"type":"string"}},"required":["key","type","tags","constraints","required_conditions","options"],"title":"Input"},"pay_entry_schema_fieldspec_payment_field_constraint":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"title":"PaymentFieldConstraint"},"pay_entry_schema_fieldspec_option":{"type":"object","properties":{"key":{"type":"string"},"properties":{"type":"object","additionalProperties":{"type":"string"}}},"required":["key","properties"],"title":"Option"},"pay_entry_schema_fieldspec_condition":{"type":"object","properties":{"depends_on":{"type":"string"},"selected_option":{"type":"string"},"selected_options":{"type":"array","items":{"type":"string"}},"type":{"type":"string"}},"required":["depends_on","type","selected_option","selected_options"],"title":"Condition"},"pay_entry_schema_fieldspec_option_decoration":{"type":"object","properties":{"key":{"type":"string"},"localized_name":{"type":"string"}},"required":["key","localized_name"],"title":"OptionDecoration"}}}} ``` # Payment Operations Overview # Using the Console for Payment Management # Permissions & Role-Based Access Control (RBAC) # Understanding Payment Statuses # Page 5 # Payment Workflow Overview Payment workflows define how money moves through a financial platform. They orchestrate logic across multiple services such as ledger, risk, account verification, and external payment providers. In the XYB platform, workflows make it possible to define custom, dynamic payment flows without writing new backend code. These workflows are not just automations that react to events they **control how a payment happens**, step by step. **Why Use Workflows for Payments?** * **Custom behavior per client or product**: Payment workflows can be tailored for different transaction types, currencies, or risk profiles. * **Operational control**: Business teams can change the payment behavior without deploying code. * **Traceability**: Each step in the workflow is logged, auditable, and observable. * **Flexibility**: Insert risk checks, ledger evaluations, routing decisions, or manual approvals at any point.
**Example: Outgoing FX Payment** Workflow steps might include: 1. Validate payment request format 2. Perform ledger balance check 3. Run risk screening 4. Determine appropriate payment provider 5. Initiate payment 6. Update payment status 7. Log result for observability Each step is defined using a sequence of actions and conditions in a workflow plan. Parameters allow dynamic logic per client or product. **Integration with Platform Services** Payment workflows integrate with: * **Ledger**: Check balances, book transactions, validate journal entries * **Risk**: Perform KYC, AML, and fraud checks * **Wallets**: Handle internal transfers * **Payment Providers**: Route to SEPA, SWIFT, instant, or custom rails Each of these services acts as a participant in the workflow and can be configured independently. **Versioning and Control** Workflows are defined as part of a **Plan** in a **Workflow Family**. This allows version-controlled logic that can be activated, rolled back, or tailored for different clients. For example, Client A may use `fx-transfer-v1` while Client B uses `fx-transfer-v2`. **State Tracking and Observability** All payment workflows report state transitions (e.g. INITIATED → AUTHORIZED → SETTLED). Services track the current state and can expose this to end users. Execution logs, error handling, and audit trails are captured for each workflow instance. **Best Practices** * Use parameters for flexibility instead of hardcoded logic * Separate flows by product type to maintain clarity * Insert `log.atInfo()` checkpoints in key transitions * Handle timeouts and retries at the service level, not inside workflows * Keep the initial state and terminal states clearly defined # Payment Workflow Use Cases Workflows in the XYB platform are designed to support a wide range of operational and business-critical scenarios. By enabling teams to automate logic across services, workflows reduce manual effort, improve response time, and ensure consistency across processes. Below are key use cases already supported or planned within the platform, categorized by domain. **1. Operations & Task Management** * **Auto-Unassign Tasks on Employee Deactivation** * Trigger: Employee status change * Action: Reassign or unassign tasks to prevent backlog from inactive users * **Auto-Create Tasks on Entity Events** * Trigger: EntityCreated or other domain event * Action: Create follow-up investigation or onboarding tasks * **Close Tasks for RiskClosed Customers** * Trigger: Customer status change to "RiskClosed" or "Closed" * Action: Automatically close related tasks **2. Payments & Ledger** * **Outgoing FX Payment Execution** * Steps: Risk check, ledger validation, routing, provider selection, status update * **Anomaly Detection Response** * Trigger: Ledger anomaly event * Action: Create task or alert for compliance follow-up * **Transaction Threshold Alerts** * Trigger: Large transaction (above threshold) * Action: Flag, create task, or escalate **3. Onboarding & Entity Management** * **Auto-Create Wallet or Account** * Trigger: EntityCreated * Action: Automatically set up financial account * **Send SMS After Onboarding Step Completion** * Trigger: Onboarding milestone event * Action: Call external messaging API **4. Risk & Compliance** * **Escalate Based on Risk Score** * Trigger: Customer risk score exceeds threshold * Action: Create high-priority review task * **KYC Document Follow-Up** * Trigger: Incomplete document submission * Action: Generate reminder task **5. Internal Tools & DevOps** * **Notify on Service Deployment Completion** * Trigger: Deployment event (via webhook or pipeline) * Action: Notify via Slack or dashboard update * **Rotate Secrets Periodically** * Trigger: Cron or schedule (future support) * Action: Rotate access keys, update config **Template and Reuse Strategy** Workflows can be templatized for reuse: * Payment status update templates * Onboarding event processors * Entity creation packages (wallet + tasks) Templates reduce duplication, standardize processes, and improve onboarding for new teams or clients. # How to Design a Workflow: Best Practices and Patterns Designing an effective workflow is about balancing structure, flexibility, and clarity. In the XYB platform, workflows give teams control over core logic but with that power comes responsibility to ensure workflows are maintainable, observable, and secure. This guide outlines key principles and common patterns to help teams design workflows that scale. **1. Define the Goal** Start with a clear, outcome-focused goal: * What process are you trying to automate? * What services will be involved? * What is the desired end state? Example: > "When a customer is flagged RiskClosed, close all associated investigation tasks." **2. Choose the Right Trigger (if applicable)** Some workflows begin with a service event, others are internal processes. Determine whether your workflow is: * Service-driven (e.g. entity created, payment initiated) * Scheduled (e.g. rotate secrets weekly) * Manual (e.g. operator triggers the flow) **3. Break It Into Steps** Decompose the workflow into logical stages: * Input validation * Risk or eligibility checks * Routing or decision branches * Execution actions (create task, update status) Use **sequence** contexts for ordered steps, and **selection** contexts to branch. **4. Use Parameters for Flexibility** Avoid hardcoding logic inside a workflow. Use parameterized values for things like: * Thresholds (e.g. transaction size limits) * Recipient accounts or task templates * Provider selection Parameters can be adjusted per workflow version or client without code changes. **5. Handle Failures Gracefully** Services should handle retries and timeouts, but workflows should: * Detect known error conditions * Set workflow states appropriately * Avoid infinite loops or recursion Workflows can use the ENDING state or terminal transitions to mark completion. **6. Reuse Through Templates** Abstract repeated logic into reusable templates. Examples: * Standard ledger validation block * Common risk escalation flow * Account + wallet creation bundle Templates reduce duplication and improve quality. # Outgoing FX Payment Workflow Build a payment workflow that safely and dynamically handles an outgoing FX transaction. This includes risk checks, balance validation, routing to the right provider, and updating the final status. **Who is this for?** Product teams and operations leads who need control over how different payment types (e.g. FX, SEPA, SWIFT) behave at runtime. **Workflow Summary** * Trigger: Service-initiated payment (contextual, not event-driven) * Actions: 1. Validate payment data 2. Perform ledger check 3. Run risk checks 4. Select provider 5. Send payment 6. Update status 7. Log result **Step-by-Step Guide** 1. **Create a New Workflow** * Go to the Workflows section in the Console * Click "Create Workflow" * Name: `fx-payment-execution` * Choose family: `payments` * Choose or create plan: `fx-transfer` 2. **Add Initial Validation Node** * Node type: Conditional or Validation * Confirm required fields like `amount`, `currency`, `recipient` 3. **Add Ledger Balance Check** * Node type: HTTP call or internal service call to `ledger` * Action: Verify account has sufficient funds * If insufficient: Route to terminal state `REJECTED` 4. **Add Risk Evaluation Step** * Node type: Internal service or HTTP call to `risk engine` * Provide context (amount, customer, destination country) * Handle flags or required holds as needed 5. **Select Payment Provider** * Node type: Selection context * Criteria: Based on currency, amount, region * Output: Set `provider_id` 6. **Initiate the Payment** * Node type: HTTP call to `payment-router` * Include all required metadata from earlier steps 7. **Update Final Payment Status** * Node type: Status update * Values: `SETTLED`, `SENT`, or fallback to `FAILED` 8. **Add Logging Nodes** * Use `log.atInfo()` after each key transition * Capture values like `payment_id`, `provider_id`, or final state 9. **Define Initial and Terminal States** * Initial: `PENDING` * Terminal: `SETTLED`, `REJECTED`, `FAILED` 10. **Activate the Workflow** * Save your workflow * Validate paths * Set state to `ACTIVE` **Tips** * Use parameters for dynamic thresholds and provider rules * Create variants (v2, v3) for SEPA, instant, or crypto rails * Include a retry or error-handling node outside payment call **Troubleshooting** * Use execution logs to trace status updates * Check message content to ensure required fields are passed **Outcome**\ The workflow will fully control how an FX payment is validated, routed, executed, and finalized, with full traceability and custom behavior per use case. *** Next tutorial: Auto-Create Account When Entity is Created # XYB Accounts **A modular, ledger-agnostic, and event-driven core banking platform for building and scaling account-based financial products.**
Getting Started with Accountscard-getting-started.pngXYB Accounts Overview
Configure Account Typescard-workflow.pngSetting Up Product Configuration for Accounts
Account Management Workflowscard-integrate.pngManaging Account Lifecycle in XYB
API Referencecard-api.pngAPI Quick Reference Guide
# XYB Accounts Overview **XYB Accounts** is a core banking component designed to help financial institutions, fintechs, and banks **create, manage, and scale customer and business accounts.** With XYB Accounts, you can design and launch current accounts, savings accounts, multi-currency and global account products tailored to your business needs through endlessly flexible configurations.
*** ## How it Works XYB Accounts are configured and operated in the following ways: ### a) Product Configuration via Console Use the **web-based Console** to define the structure and behavior of your account products.\ This includes: * Naming and describing your product (e.g., "Retail GBP Wallet") * Setting default currency, jurisdictions, initial states * Linking rules for balance behavior, lifecycle transitions, and sweeping * Attaching services like balance management or access control * Customizing metadata using the Schema Builder > Think of it as designing reusable templates for account creation. ### b) Operate with APIs & Kafka Events Once your product is configured, you can use **REST APIs** to: * Create and manage accounts * Attach wallets and banking coordinates (IBAN, BIC, etc.) * Query balances and lifecycle status * Trigger account updates or transitions (e.g., suspend, close) XYB also emits **Kafka events** for: * Account creation and updates * Balance changes * Lifecycle transitions * Compliance-triggered suspensions > These events can integrate with fraud engines, analytics, notifications, and more. ### c) Integrate with Internal (XYB) or External Components XYB’s account engine is **ledger-agnostic and modular**. You can: * Use XYB’s built-in ledger * Bring your own core ledger (e.g., Thought Machine, TCS BaNCS) * Integrate with 3rd-party payment partners (e.g., LHV, CurrencyCloud) * Plug into existing KYC, policy, or notification systems > Integration complexity is abstracted away using adapters, so your core setup remains clean and API-first. *** ### Key Benefits * **Multi-access:** Accounts support a multi-user model where multiple entities can be linked to a single account. This enables collaborative account management scenarios such as finance teams, business accounts, or technical admins * **Ledger Agnostic**: Use XYB’s built-in ledger, or bring your own e.g., Thought Machine or TCC. * **Configurable Products**: Define reusable templates for each type of account, controlling everything from wallet setup to ledger group. * **Entity-Centric**: Accounts are linked to legal entities, enabling complex structures like joint accounts or B2B hierarchies. * **Real-Time & Event-Driven** * Kafka events on account creation, updates, and balance changes. * Instant integration with downstream services like risk engines, customer portals, and reporting tools. * **Modular and Headless** * Use only what you need just the accounts layer, or the full stack with ledger and payments. * Embed account functionality into your own UI, or use XYB’s micro-frontend components (MFE). *** *** # Accounts Lifecycle XYB Accounts is the **engine behind every financial account** created through your platform. Whether you're onboarding a new customer, setting up a savings wallet, or integrating with a ledger, this is the system doing the heavy lifting. ### 1. Define an Account in Product Configuration Product Configuration capability in our XYB Console provides a no-code way to define what your account product looks like. For example, a product configuration might define: * Which **wallets** the account should have (e.g. EUR, USD) * What **ledger provider** to use (XYB, TM, etc.) * Whether **banking coordinates** (IBAN, BIC) should be created * If the account should support **interest**, **statements**, or **multi-currency** * What the **jurisdiction** is, and which attributes to track This configuration ensures that **every account matches the needs of your business** whether you’re building for retail customers, businesses, or niche fintech use cases. *** ### 2. Creating the Accounts Based on the product configuration for accounts, an account is created (usually via API or onboarding flow): * The **customer entity** is attached to the account * A **unique reference** (ID) is assigned * Product rules are applied: * A default wallet (or multiple wallets) is created * Ledger mappings are initialized * Optional banking coordinates are generated * Custom metadata and tags are saved This process is **automated and fast**. Accounts can be created programmatically or through a user interface, and everything is tracked. *** ### 3. Account Management Once created, the account becomes **active** and can be used across the platform. From here, teams and systems can: * **View the account** in the console dashboard * **Search** for accounts using reference, name, ID, or tags * **Monitor balances** for each wallet linked to the account * **Add banking details** like IBAN or account number * **Update account attributes**, like risk profile or visibility settings * **Pause or close the account** when needed Each account has a **status** (`Open`, `Suspended`, etc.) which controls how it behaves. *** ### 4. Ongoing Sync: Ledgers, Balances, Events The account system stays in sync with: * The **ledger service:** to keep balances up to date * The **wallets service** reflect currency-specific balances * The **payments service** to route transfers using coordinates * **Kafka events:** so other services know when changes happen (e.g., account created, state updated, wallet balance changed) This ensures real-time accuracy across your platform. *** ### Typical End-to-End Flow Let’s look at a real-world example: #### Customer Onboarding > A customer signs up for your product \ > The system creates an account \ > Wallets for EUR + GBP are automatically added \ > A ledger account is mapped \ > IBAN is generated \ > Account appears in your UI dashboard and is ready to use Or... #### Risk Scenario > A suspicious transaction occurs \ > Ops team suspends the account \ > All wallets are frozen \ > A Four-Eye approval workflow is triggered \ > Account is reactivated after review *** # Planning Your Account Structure & Setup Before you create your first customer account, it’s important to **design your account setup**. This ensures the service fits your product, compliance needs, and financial architecture, whether you’re using all of XYB or integrating your own systems. *** ### Why Planning Matters XYB Accounts is not just a database of users. It's a **configurable engine** that manages how funds, identities, and financial behavior are structured in your platform. Without planning, you might: * Create accounts that don’t align with your ledger * Miss critical metadata needed for compliance or reporting * End up with wallets that don’t match how your customers operate *** ### Key Questions to Ask Before You Begin | Category | Questions to Consider | | ------------------------- | ----------------------------------------------------------------------------- | | **Product Intent** | What is this account used for? (Retail, savings, FX, crypto?) | | **Structure** | How many wallets per account? Multi-currency? Default currency? | | **Compliance** | What data is required? (jurisdiction, KYC, entity linkage?) | | **Lifecycle** | What should happen when an account is suspended, reopened, or closed? | | **Integrations** | Are you using your own ledger? Own payments stack? Or XYB’s? | | **Statements & Balances** | Do you need daily statements? Global balance views? Kafka push notifications? | *** ### Components You Need to Think Through #### 1. **Product Configuration** Every account in XYB is tied to a **product configuration**. This config defines: * Wallet currencies and codes * Ledger and banking providers * Visibility rules * Default attributes * Jurisdiction and compliance controls Example: A "Premium Retail Account" product might include: * EUR + USD wallets * TCC for banking coordinates * Statement push enabled * Four-Eye policy for state changes *** #### 2. **Ledger Strategy** You can: * Use **XYB Ledger** (built-in) * Use **Thought Machine** or **other third-party ledgers** * Skip ledger linkage entirely if you just need metadata + identity Make sure your **ledger and wallet codes** are planned to match how your accounting or transaction processing works. *** #### 3. **Wallet Strategy** Accounts in XYB can hold multiple wallets, and you define: * Which currencies are supported * Which wallet is the "default" * Whether a wallet should be auto-created on account creation * How wallets sync with ledger balances Tip: Plan for both **current** and **future currencies:** wallet creation can be additive later, but metadata compatibility matters. *** #### 4. **Banking Coordinates** You can attach banking details like: * IBAN * BIC * Routing codes * Account numbers These are often provided by a third-party like **CurrencyCloud**, or generated internally based on rules. Plan for: * Which fields are needed per region (IBAN vs routing code) * How many coordinates per account * Which tags or external references you’ll need *** #### 5. **Entity & Jurisdiction Mapping** Every account must belong to an **owning entity,** a customer, business, or organization. The system allows for: * Multiple accounts per entity * Mandates to define ownership * Jurisdiction-specific fields for compliance Make sure your **Entity Service** is integrated (XYB provides one), or align your internal customer model. *** #### 6. **Four-Eye Workflows (Optional)** For extra control, you can enforce: * Approval steps for suspending/finalizing accounts * Policy-based conditions (e.g., certain account types require approval) You can configure this later, but it’s best to know upfront if you want **compliance controls baked in**. *** ### Planning Summary | Setup Area | Required? | Configured Via | Notes | | ------------------- | --------- | ---------------------------- | ------------------------------------------------ | | Product Config | Yes | Product Factory / Config API | Core definition of behavior and wallets | | Ledger Provider | Optional | Product config + Strategy | Can be XYB, TM, or none | | Wallets | Yes | Config + Account creation | Defines currencies + linkage to ledger | | Banking Coordinates | Optional | Config or Manual | Based on payments integration needs | | Entities | Yes | Entity Service | Each account must belong to an entity | | Four-Eye Policies | Optional | FourEye Policy Service | Enforced via Kafka + internal approval workflows | *** # Accounts Quick Start Guide This article walks through the **entire customer experience** with XYB's Accounts capabilities—from setup to production. It includes touchpoints across the hosted developer environment, APIs, and the configuration console. *** #### 1. Starting Point: Access to the Platform As a customer of XYB: * You are onboarded into a **hosted developer environment**, with secure access to: * **API credentials and sandbox URLs** * A **web console** for **product configuration** You receive a **fully isolated instance** with the capability to configure and simulate the full account lifecycle. *** #### 2. Product Configuration (via Console) **What happens:** You define **account products** through the **Product Configuration Console**. **Key actions:** * Create **account product definitions** (e.g., "Retail GBP Account", "FX Wallet") * Assign: * Default currency * Supported jurisdictions * Initial state * Optional flags like "silent statement push" * Link accounts to services (e.g., balance management, account rules) Interface used: * **Products tab** in the Console: define names, references, descriptions. * **Services tab**: attach service behavior (e.g., wallet rules, lifecycle rules). * **Schema Builder**: customize metadata, tags, or compliance rules. Outcome:\ This product becomes **the template** for account creation via API or UI. *** #### 3. API Integration: Account Lifecycle After configuration, you begin integrating with XYB’s **Accounts APIs**. **Use cases:** * Create new accounts * Fetch accounts by ID or owner * Attach banking coordinates (like IBANs) * Query live balances or statements **Typical flow:**
StepAPI ActionDescription
1POST /accountCreate a new account for a user using a configured product
2GET /account/{id}Retrieve full account details
3PATCH /account/{id}/attributesAdd metadata like tax tags, product overrides
4POST /account/{id}/coordinatesAttach internal or banking coordinates
5GET /account/{id}/walletsFetch real-time balances
6POST /account/{id}/stateChange state (e.g. block, close) with audit trail
*** #### 4. Real-Time Monitoring & Testing As a developer or product owner: * You test your integration in **XYB's sandbox** environment. * Use tools like: * **Query explorer** in the Console * **Transaction simulators** * **Schema validation checks** * API responses include: * Account UUIDs * Wallet balance snapshots * Audit logs and timestamps You can simulate full flows like account blocking, attribute changes, or balance sweeping via test hooks. *** #### 5. Account States, Rules & Governance Accounts support a **comprehensive lifecycle**: | State | Use case | | ----------------------- | ------------------------------------------------- | | `PENDING` | Initial creation | | `OPEN` | Account is usable | | `SUSPENDED_IN/OUT` | Temporarily frozen for incoming or outgoing funds | | `BLOCKED` | Restricted due to compliance or fraud | | `CLOSED` / `TERMINATED` | Final state after deactivation | You define **rules and status transitions** in the Console (e.g., “when UNDERAGE, map to SUSPENDED”). All transitions are API-triggered and audited. Some require **approval workflows** if configured. *** #### 6. Advanced Features: Wallets & Sweeping Every account has: * One or more **wallets** (currency-specific balance holders) * Support for: * **Live balances** (`/wallets`) * **Global consolidated balances** (`/wallets/gcb`) * **Sweeping rules** to automate fund movement across wallets Customers can: * Configure rules for wallet prioritization (e.g., auto-drain secondary balances) * View balance composition via wallet APIs * Manage sweeping via APIs or backend logic *** #### 7. Moving to Production Once tested: * You switch to **live environment endpoints** * XYB enables: * Access control and role-based permissioning * Secure certificate handling for production * Rate limits, SLAs, and logging All product configurations carry over—no need to redefine products. *** #### Summary: End-to-End Experience | Stage | Customer Touchpoint | Purpose | | ------------- | ----------------------------- | -------------------------------------------- | | Kickoff | Hosted developer environment | Get started with sandbox access | | Configuration | Product Console | Define account types and behaviors | | Integration | API Suite | Programmatically create and manage accounts | | Testing | Sandbox + Query tools | Validate flows and simulate edge cases | | Advanced | Wallets, sweeping, attributes | Add financial logic and operational metadata | | Production | Live switch + access control | Move to real-world usage with stability | # Setting Up Product Configuration for Accounts Once you’ve planned your account structure including wallet strategies, ledger linkage, and metadata, the next step is to define all of that in a **Product Configuration**. This configuration is what XYB Accounts reads before creating each account. It acts as your **blueprint**, ensuring accounts are built exactly the way you intend with all the right defaults, wallets, and behaviors. *** XYB Accounts depends on product config to know: * What kind of wallet(s) to create * Which banking or ledger strategy to use (XYB, TM, TCC) * Whether to enable features like statement pushes or four-eye * What metadata and currency setup should be enforced * How to interpret owner and jurisdiction fields Without this config, account creation will return an error. *** ### What Goes Into a Product Configuration? Here’s a breakdown of key components you define in your config: | Field/Section | Purpose | | ----------------------- | ------------------------------------------------- | | `productId` + `version` | Uniquely identifies the configuration | | Ledger provider | XYB / Thought Machine / Other | | Banking provider | TCC / LHV / Other | | Wallet setup | Currencies, wallet codes, auto-create flags | | Jurisdiction rules | For compliance and tax logic | | Visibility attributes | For frontend and UX | | Default metadata | Risk level, category, customer tier, etc. | | Silent push flags | Enable/disable event-driven balance notifications | *** ### How to Create the Product Configuration #### Option 1: Use Admin Tools Some clients have access to a **UI configuration console** (internal tool) where they can define new products. {% embed url="" %} > If you’re onboarding as a full XYB platform client, reach out to your onboarding team for access. *** #### Option 2: Use Product Config API You can programmatically define configs using: ``` POST /api/v1/product-configuration ``` With a payload like: ```json { "productId": "abc-123", "version": "1.0", "serviceName": "cac-account-svc", "components": [ { "identifier": "wallet_config", "components": [ { "identifier": "default_currency", "components": [{ "iso3": "EUR" }] }, { "identifier": "wallet_currencies", "components": [ { "iso3": "EUR" }, { "iso3": "USD" } ] } ] }, { "identifier": "ledger_config", "components": [ { "identifier": "ledger_providers", "components": [{ "identifier": "XYB" }] }, { "identifier": "wallet_code", "value": "DEFAULT" } ] } ] } ``` Need a detailed schema? Link to the API documentation here. *** #### Option 3: Preload Configs via Onboarding For some deployments, initial configs are **predefined** by XYB and shipped as part of your environment setup. You just need to: * Review them * Add versions as needed * Link account creation to the correct `productId` + `version` *** ### Once Configured, You Can... Start creating accounts via: * `POST /account` API * Internal tools or portals * Automation scripts *** *** # Create New Accounts After you’ve planned your account structure and configured your product, you’re ready to create your first customer account using XYB. *** ### Prerequisites Make sure you’ve completed: * Product Configuration: Your account product must exist (with `productId` and `version`). * Entity Creation: The customer entity (owner of the account) must be available. * Authentication: You have access to XYB APIs via secure credentials. *** ### Create Account via API #### Endpoint ``` POST /api/v2.0/account ``` #### Sample Request Body ```json { "reference": "user-123", "name": "John Smith's Account", "productId": "f5e6a3aa-xxxx-yyyy-zzzz-abcdefghijkl", "productVersion": "1.0", "currency": "EUR", "owner": { "type": "INDIVIDUAL", "affiliation": "PERSONAL", "reference": "entity-xyz" }, "tags": ["PREMIUM", "EU"], "attributes": { "risk_level": "LOW", "kyc_status": "VERIFIED" }, "coordinates": { "banking": { "iban": "DE89370400440532013000" } } } ``` #### Sample Response ```json { "id": "2f3a...fd91", "reference": "user-123", "name": "John Smith's Account", "status": "OPEN", "productUuid": "...", "wallets": [...], "owner": {...} } ``` #### Error Codes * `405` - Account already exists with this reference or coordinates * `400` - Validation failure (missing or mismatched data) Learn more about [Account Management APIs](/xyb-platform-1/accounts/account-operations-apis). *** *** ### Creating Accounts via UI If you want to allow **end-users** or **internal agents** to trigger account creation via your own frontend: 1. Build a form to collect: * Owner reference * Account name * Currency * Product ID + version * Optional tags or attributes 2. Post the form data to your backend 3. Call the `POST /account` endpoint using backend service logic 4. Show success, redirect, or display the new account data *** ### What Happens Behind the Scenes? When you create an account: * XYB validates product config and entity * Creates account + default wallet(s) * Links ledger account if configured * Assigns banking coordinates (if provided) * **Publishes Kafka event `account-created.`You can subscribe to this event or query the account at any time.** [**Learn more about the Accounts Kafka topics.**](/xyb-platform-1/accounts/kafka-topics-quick-reference-guide) ### # Integration with Banking Components Accounts don’t work in isolation, rather it integrates with other banking components to function as a complete financial layer. We categorize these integrations into: #### 1. Internal Integrations These are native XYB services that work in tandem with the Accounts Services | Internal Component | Role in Integration | | ------------------------- | ----------------------------------------------------------------------------------- | | **Ledger Service** | Provisions wallets, manages wallet states, and broadcasts balance events via Kafka. | | **Wallet Service** | Creates and manages default and additional wallets per account. | | **Entity Service** | Every account is tied to an entity (individual or business). | | **Product Config** | Drives account behavior (ledger strategy, default currencies, wallet types). | | **Four-Eye Service** | Enforces approval flows on sensitive account state changes. | | **Notification Services** | Publishes events like balance updates or account creation via Kafka. | *** #### 2. Third-Party Integrations These integrations extend functionality such as issuing banking coordinates or linking external payment rails. | Third-Party Integration | Role | | ----------------------- | --------------------------------------------------------------------------- | | **Currency Cloud** | Issues IBANs and banking details for accounts. | | **Card Processors** | (If integrated) Link wallets to virtual/physical card issuance. | | **Payment Gateways** | Use account coordinates for payouts, settlements, and more. | | **KYC/AML Providers** | (Via Entity/Onboarding module) Used to verify the entity linked to account. | *** # Managing Account Lifecycle in XYB Once a customer account is created, it lives through different **states** depending on the actions taken by your team, your users, or automated workflows. *** ### What Is the Account Lifecycle? Every account in XYB has a `status`. This reflects whether the account is active, blocked, or closed. The account status impacts: * Whether money can be sent or received * Whether wallets remain open or suspended * What is shown in dashboards or statements *** ### States in the Lifecycle | State | Description | | --------------- | ----------------------------------------------------- | | `PENDING` | Initial state during creation. Not active yet. | | `OPEN` | Account is active and can transact. | | `SUSPENDED_IN` | Account cannot **receive** funds. | | `SUSPENDED_OUT` | Account cannot **send** funds. | | `SUSPENDED` | Account cannot send or receive. | | `CLOSED` | Temporarily closed. Can be reopened if policy allows. | | `FINALIZED` | Permanently closed. Cannot be reopened. | *** ### How to Change an Account's State #### Endpoint ``` POST /api/v2.0/account/{idRef}/state ``` #### Request Payload ```json { "state": "SUSPENDED", "reason": "Manual hold due to risk flag", "employeeUsername": "john_doe" } ``` #### Response Returns `AccountStateChange` object with: * `previousState` * `newState` * `timestamp` * `performedBy` *** ### Four-Eye Approval Workflow For sensitive state transitions (e.g. closing an account), you can enable **Four-Eye Policies**: * Create change request * Wait for approval (second actor) * Auto-apply if approved, or discard if rejected This happens **automatically** if your product or policy config requires it. *** ### Use Case Examples #### Suspend an Account ```json { "state": "SUSPENDED", "reason": "KYC expired" } ``` #### Reopen an Account ```json { "state": "OPEN", "reason": "Customer re-verified" } ``` #### Close an Account Permanently ```json { "state": "FINALIZED", "reason": "Account closed by user request" } ``` *** ### State Sync with Wallets & Ledger * Wallets are **automatically synced** with account state. * Ledger behavior (e.g., status update) is handled via strategy-specific logic. * All state transitions are **recorded** and available for audit. *** ### Events You Can Listen To XYB emits Kafka events such as: * `account.status-change.v1` These can be used to trigger: * UI updates * Email notifications * Fraud engine checks *** ### UI / MFE Integration In the XYB micro-frontend or your custom UI, you can: * Show current account state * Display full state history * Trigger lifecycle changes via dropdowns/forms *** # Account Wallet Management Overview An **account** **wallet** represents a currency-specific balance container under an account. Wallets hold funds, track balances in real time, and support transactions in specific currencies. Every account must have at least one wallet (usually created automatically), and can support multiple additional wallets as needed (e.g., for multi-currency). *** Wallet creation in XYB is fully automated and tied to your **Product Configuration**. Once you define the wallet strategy for your account product including default currency, additional currencies, and wallet codes XYB will auto-provision these wallets during account creation. This means no separate API call is required to create wallets. When you create an account using the standard API, the system references your product setup, creates the associated wallets, and links them to the correct ledger. [Learn how to configure wallets in Product Configuration](/xyb-platform-1/accounts/configure-accounts/setting-up-product-configuration-for-accounts)\ [Read more on creating accounts](/xyb-platform-1/accounts/configure-accounts/create-new-accounts) *** #### View Wallet Balances You can view all wallet balances using the following endpoints: * **Get all balances:**\ `GET /api/v2.0/account/{idRef}/wallets` * **Get a specific wallet:**\ `GET /api/v2.0/account/{idRef}/wallets/{walletType}/{currency}` Each wallet returns: * **Available balance**: Funds ready to be used * **Hold balance**: Funds temporarily on hold * **Account balance**: Total including holds and available * **Last updated timestamp** This data can be used in your portals, statements, or notifications. *** #### Global Customer Balance (GCB) If your account has multiple wallets, XYB can calculate a **Global Customer Balance** (GCB) - a consolidated balance across all wallets, normalized into a single currency. * Use:\ `GET /api/v2.0/account/{idRef}/wallets/gcb`\ Or specify wallet type and currency for filtered views. GCB is particularly useful for: * Presenting a single unified balance to users * Simplifying reconciliation across multiple currencies *** #### Wallet Sweeping: Automate Balance Movement Wallet **sweeping** lets you configure rules to move funds between wallets automatically, for example, clearing a reserve wallet into the default wallet when thresholds are met. How it works: * The ledger emits balance updates. * Account service detects available funds in secondary wallets. * If rules match (e.g., “sweep if > 100 USD”), funds are moved. * The resulting balance is updated and broadcast. Sweeping is managed automatically by XYB’s backend. You can define rules via internal logic or work with the XYB team during onboarding to customize it. *** #### Summary: Wallet Lifecycle at a Glance | Action | Trigger | Tool/Endpoint | | ---------------------- | -------------------------------- | ---------------------------------- | | Define wallet strategy | Product Configuration | Console or API (`/product-config`) | | Create wallets | Account creation | `POST /api/v2.0/account` | | View balances | Any time | `GET /account/{id}/wallets` | | Consolidated GCB | Real-time | `GET /account/{id}/wallets/gcb` | | Automate sweeping | Based on rules & balance updates | Managed internally | *** --- [Next Page](https://docs.xyb.co/llms-full.txt/1)