# CashXChain Documentation — Full reference CashXChain is the infrastructure for the money of tomorrow. Built first for cross-border and B2B payments, designed to scale to every payment a modern business sends or receives. Source: https://docs.cashxchain.com Generated: 2026-05-10T23:16:06.823Z Production API: https://api.cashxchain.com Sandbox API: https://api.sandbox.cashxchain.com Sandbox and production are fully separated — separate accounts, API keys, auth, web apps, and developer portals. No shared session, no SSO between environments. --- # How it works Source: https://docs.cashxchain.com/docs/introduction/how-it-works Description: Learn how CashXChain orchestrates fiat, stablecoin, partner rails, FX, and compliance metadata. # How CashXChain works CashXChain turns complex payments into a simple business workflow. The hardest cases — cross-border, multi-currency, multi-rail — drive the design, but the same workflow scales down to local and same-currency payments. A customer creates an account, completes onboarding, requests a quote, submits a payment instruction, and listens for webhook events. Behind that simple workflow, CashXChain prepares the transaction, enriches it with compliance metadata, evaluates available rails, and routes the instruction to regulated execution partners. ## Three-layer model CashXChain is designed around three layers. ### 1. Client layer The client layer is the interface used by businesses and platforms. It can be the CashXChain dashboard, a white-label partner experience, a treasury system, an ERP integration, or a direct API client. The client layer captures business intent: - Who is paying? - Who is receiving? - What amount and currency should move? - What is the purpose of payment? - What invoice, order, or internal reference should be attached? - How urgent is the payment? ### 2. Instruction and orchestration layer The CashXChain backend validates the request, applies account permissions, attaches compliance metadata, creates a ledger record, requests quotes, evaluates route availability, and prepares partner-specific instructions. This layer does not require the end user to understand which rails are involved. It presents a unified payment workflow while keeping a complete audit trail of the decision path. ### 3. Partner execution layer Licensed partners perform regulated activities where required. Depending on corridor, currency, customer type, and payment method, this can include custody, fiat collection, stablecoin issuance or redemption, local payout execution, AML screening, sanctions screening, Travel Rule obligations, and final settlement. CashXChain tracks the partner execution lifecycle and normalizes the result back into a consistent payment status model. ## Example payment flow 1. A German SME wants to pay a supplier in Kenya. 2. The SME creates a beneficiary and requests an FX quote. 3. CashXChain returns the expected recipient amount, fee estimate, route, and quote expiry. 4. The SME submits the payment with an idempotency key. 5. CashXChain validates the instruction, attaches metadata, and selects the best available route. 6. A regulated partner performs required checks and executes the relevant collection, conversion, settlement, or payout step. 7. CashXChain emits webhook events as the payment moves through screening, processing, settlement, and completion. 8. The SME downloads a statement and reconciles the payment against the invoice. ## Invisible blockchain CashXChain can use blockchain settlement where it improves speed, cost, or resilience. The business user still sees currencies, balances, quotes, references, statements, and counterparties. Blockchain addresses, gas management, and transaction signing are abstracted away by the platform and its partners. ## Multi-rail routing CashXChain evaluates routes using practical criteria: - Currency pair and corridor. - Available local payout methods. - Partner availability and operating hours. - Expected speed and cut-off windows. - FX quote quality and slippage risk. - Fee structure. - Compliance requirements. - Risk score. - Liquidity availability. The result is a payment route that balances speed, cost, reliability, and compliance. --- # Key features Source: https://docs.cashxchain.com/docs/introduction/key-features Description: Explore the core capabilities of CashXChain. # Key features CashXChain combines a developer-friendly API, a business-grade payment model, and a compliance-aware orchestration layer. ## API-first infrastructure Every core workflow is available through the API: accounts, onboarding sessions, balances, FX quotes, beneficiaries, payments, webhooks, statements, and audit records. The dashboard uses the same concepts as the API, which keeps operational and technical teams aligned. ## Fiat-native user experience Business users work in familiar terms: EUR, USD, local currencies, invoices, suppliers, customers, statements, and payment references. They do not need to manage wallets, gas, seed phrases, or blockchain explorers. ## Multi-currency balances CashXChain gives businesses a unified view of balances across currencies, accounts, wallets, and partner rails. Balances can be available, pending, reserved, or restricted depending on settlement state and compliance review. ## Quote-driven FX FX is handled through explicit quotes. A quote defines the source amount, target amount, rate, spread, fee, expiry time, and route assumptions. This gives finance teams predictability before committing to a transaction. ## Payment orchestration CashXChain normalizes many operational steps into one lifecycle: instruction created, checks initiated, authorized, processing, settling, completed, failed, returned, or cancelled. Teams integrate once and support multiple corridors, currencies, and payment types over time — starting with the cross-border and B2B cases that benefit most. ## Webhooks and event timeline Real-time events help platforms automate customer messaging, reconciliation, exception handling, and internal operations. Each event includes stable identifiers, timestamps, environment, resource type, and signature headers for verification. ## Compliance-aware architecture CashXChain collects and structures information required for business verification, beneficiary setup, risk assessment, purpose of payment, and partner execution. Regulated partners perform regulated checks and execution where required. ## Audit trail and reconciliation Every payment has a timeline, metadata, references, related quote, fee breakdown, partner status mapping, and downloadable statements. This makes CashXChain suitable for finance teams that need traceability rather than consumer-style payment history. ## Sandbox-first integration The sandbox environment lets developers create accounts, simulate onboarding states, request quotes, send test payments, receive webhooks, and validate operational edge cases before production. --- # Overview Source: https://docs.cashxchain.com/docs/introduction/overview Description: CashXChain is the payments infrastructure for the money of tomorrow. # CashXChain Documentation **CashXChain is the infrastructure for the money of tomorrow.** It is the payments orchestration layer for modern businesses — built first for the corridors and workflows banks handle worst, and designed to scale to every payment a modern business sends or receives. We focus first on cross-border and B2B payments, because that is where existing infrastructure is the most painful: slow settlement, opaque pricing, manual reconciliation, and unpredictable compliance holds. The platform, API, and operations are not limited to those workflows — the same primitives apply to platform payouts, marketplace flows, treasury operations, and any payment a business sends or receives at scale. Companies use CashXChain to create accounts, prepare payments, request FX quotes, route transactions across available rails, receive lifecycle notifications, export statements, and maintain an auditable record of every instruction. ## The core idea CashXChain follows the principle of invisible blockchain: the user works with familiar currencies, counterparties, invoices, references, and business workflows, while the platform orchestrates modern settlement infrastructure in the background. A typical payment may involve a fiat collection rail, a regulated stablecoin settlement rail, an FX conversion, a local payout partner, and compliance metadata. CashXChain exposes that complexity through one coherent API and dashboard. **Faster than banks. Safer than crypto.** ## What CashXChain provides - A single API for modern payment workflows. - Multi-currency account and balance views. - Quote-driven FX and route selection. - Payment instruction creation and lifecycle tracking. - Webhooks for real-time operational updates. - Audit trails, statements, references, and reconciliation exports. - Compliance metadata collection and routing to regulated partners. - A fully isolated sandbox environment for safe integration testing. ## What CashXChain is not CashXChain is not a self-custody crypto wallet for consumers. It is not a speculative trading product. It does not ask business users to manage seed phrases, gas tokens, or blockchain addresses. CashXChain is also designed as an orchestration and technology layer. Regulated activities such as custody, payment execution, local settlement, screening, and Travel Rule obligations are performed by licensed partners where required. CashXChain prepares instructions, structures metadata, routes requests, and provides a consistent operational layer for customers. ## Who should read these docs - Developers integrating the CashXChain API. - Finance and treasury teams evaluating payment operations. - Product teams embedding payouts or collections into a platform. - Compliance teams reviewing KYB, AML, screening, and audit controls. - Operations teams managing payment exceptions, returns, and reconciliation. ## Start here If you are new to CashXChain, read [How it works](./introduction/how-it-works), then follow the [Integration Quickstart](./integration/quickstart). Developers can go directly to [API Getting Started](./api/getting-started). --- # Roadmap Source: https://docs.cashxchain.com/docs/introduction/roadmap Description: Future product direction for CashXChain. # Roadmap CashXChain is positioned as the infrastructure for the money of tomorrow. The product evolves from a focused launch in cross-border and B2B payments — the hardest cases — toward a general-purpose payment operating layer for businesses and platforms. This roadmap describes product direction. Availability of specific corridors, currencies, rails, and regulated services depends on partner enablement, customer risk review, licensing, and production readiness. ## Phase 1: Core platform and sandbox The first phase focuses on the foundational payment model: - Business account onboarding. - API keys and environment separation. - Payment instruction creation. - FX quote workflow. - Ledger and balance views. - Webhook delivery. - Statements and reconciliation exports. - Sandbox simulation for developers. ## Phase 2: Production launch corridors The production launch focuses on high-friction cross-border and B2B corridors where speed, cost, and operational clarity matter most: - EU to US business payments. - EU to Asia supplier payments. - EU to Africa payout and supplier corridors. - EUR and USD first-class support. - Stablecoin settlement behind a fiat-native UX. - Local payout support through regulated partners. ## Phase 3: Platform and embedded finance integrations CashXChain will expand distribution through platforms and systems used by finance teams: - ERP integrations. - Treasury Management System integrations. - Marketplace and platform payout integrations. - White-label onboarding and hosted payment experiences. - Team roles, approval workflows, and audit exports. ## Phase 4: Multi-rail optimization The routing engine will become increasingly adaptive: - More banking and payout partners. - More stablecoin and blockchain settlement rails. - More local payout schemes. - Better quote comparison. - Liquidity forecasting and treasury automation. - Fallback routing during partner downtime or corridor restrictions. ## Phase 5: Global Payment OS The long-term vision is a programmable operating layer for business money movement: - Programmable treasury rules. - Automated supplier payment policies. - Escrow and milestone settlement workflows. - Embedded working-capital and liquidity products through partners. - Rich compliance automation. - Global APIs for platforms building financial workflows. ## Documentation roadmap The documentation will expand alongside the platform. Future additions may include OpenAPI files, SDK reference pages, integration recipes, dashboard tutorials, region-specific coverage pages, and compliance implementation guides. --- # Architecture Source: https://docs.cashxchain.com/docs/product/architecture Description: CashXChain architecture for payment orchestration, partner execution, and multi-rail settlement. # Architecture CashXChain is built as a modular, API-first orchestration platform for modern payments. The architecture is shaped by the hardest cases — cross-border, multi-currency, multi-rail B2B — and applies to simpler payment workflows without modification. The architecture separates customer experience, instruction preparation, compliance metadata, route selection, and regulated execution. This separation is central to CashXChain's security, scalability, and regulatory posture. ## Architecture layers ```text Customer or Platform | v CashXChain API and Dashboard | v Instruction and Orchestration Layer | +--> Ledger and audit trail +--> FX quotes and routing +--> Beneficiary and account metadata +--> Compliance metadata preparation +--> Webhook and notification service | v Regulated Partner Execution Layer | +--> Banking and payout partners +--> Stablecoin and settlement partners +--> On/off-ramp partners +--> Screening and KYB/KYC partners | v Payment Rails and Networks ``` ## CashXChain responsibilities CashXChain is responsible for: - API and dashboard user experience. - Account and user permission model. - Instruction validation. - Route evaluation. - Quote orchestration. - Metadata structuring. - Ledger and audit trail. - Webhook normalization. - Statements and reconciliation views. - Integration tooling. ## Partner responsibilities Regulated partners perform regulated activities where required, including: - Fiat custody or safeguarded account services. - Crypto-asset custody where applicable. - Payment execution. - Stablecoin issuance, redemption, or transfer execution. - AML/CFT and sanctions screening. - Travel Rule obligations. - Local payout processing. - Banking scheme participation. ## Zero-custody design principle CashXChain's target architecture is a zero-custody and zero-disposal-authority model. CashXChain prepares and routes instructions, but user funds remain in partner-controlled infrastructure where regulated execution takes place. This principle affects product design: - No customer private keys are held by CashXChain. - No customer funds are directly controlled by CashXChain. - Partner authorization is required for execution. - If CashXChain is unavailable, funds remain accessible through the relevant partner arrangements. ## Multi-rail routing engine The routing engine evaluates cost, speed, corridor availability, compliance requirements, partner status, liquidity, and settlement characteristics. It is designed to choose the best practical route for each transaction while preserving auditability. CashXChain treats both off-chain banking rails (SEPA, SWIFT, ACH, FPS, local payout schemes) and on-chain rails (regulated stablecoins on supported chains) as first-class infrastructure. Stablecoins are also used internally as a settlement medium between partners and corridors when this produces a better outcome than bank-only routing. See [Rails](./rails) for the full list of sending and funding rails. ## Ledger-first accounting CashXChain maintains an internal ledger for operational visibility and reconciliation. The ledger reflects payment states and balance movements but does not replace partner records, bank statements, or legally required account records. ## Environment separation Sandbox and production are separated by base URL, credentials, webhook endpoints, data, and operational controls. Never reuse production secrets in sandbox or sandbox secrets in production. --- # Audit trail Source: https://docs.cashxchain.com/docs/product/audit-trail Description: Learn how CashXChain records payment, compliance, and operational events. # Audit trail CashXChain maintains a structured audit trail for accounts, beneficiaries, quotes, payments, balance movements, webhook delivery, user actions, and compliance-relevant lifecycle events. The audit trail is designed for finance, operations, compliance, and engineering teams that need to understand not just what happened, but when, why, and through which workflow. ## What is recorded Depending on resource type and account configuration, CashXChain records: - Resource creation and updates. - User, API key, or system actor. - Timestamps. - Environment. - Payment status transitions. - Quote creation and acceptance. - Beneficiary changes. - Approval decisions. - Screening and review states. - Webhook delivery attempts. - Ledger movements. - Statement generation. - Error codes and retry attempts. ## Payment timeline Every payment includes a timeline. The timeline provides normalized status changes across CashXChain and partner systems. ```json { "payment_id": "pay_6pD3...", "timeline": [ {"status": "created", "at": "2026-06-01T09:00:12Z"}, {"status": "screening", "at": "2026-06-01T09:00:13Z"}, {"status": "authorized", "at": "2026-06-01T09:00:18Z"}, {"status": "processing", "at": "2026-06-01T09:00:19Z"}, {"status": "completed", "at": "2026-06-01T09:00:42Z"} ] } ``` ## Audit exports Audit data can be exported through statements, event APIs, and dashboard reports. Enterprise customers can request additional retention, export, or integration patterns. ## Retention Retention depends on legal requirements, customer agreements, partner obligations, and data protection rules. CashXChain retains operational and compliance records for as long as required to satisfy legal, accounting, security, and regulatory obligations. ## Best practices - Use stable external references for every payment. - Store CashXChain IDs in your system of record. - Subscribe to webhooks rather than polling only. - Review audit logs after operational incidents. - Separate user roles for payment creation, approval, and admin actions. --- # FX and quotes Source: https://docs.cashxchain.com/docs/product/fx Description: Learn how CashXChain handles quote-driven currency conversion. # FX and quotes CashXChain uses quote-driven FX to make conversion costs transparent before a payment is submitted. A quote is a temporary offer that describes how much will be debited, how much the beneficiary is expected to receive, what fees apply, which route assumptions are used, and when the quote expires. ## Why quotes matter Cross-border payments — especially in B2B contexts — often fail operationally because the sender does not know the final recipient amount, total fees, or FX spread until after execution. CashXChain solves this by making quote acceptance explicit. ## Quote components A quote can include: - Source currency and amount. - Target currency and estimated amount. - FX rate. - FX spread. - CashXChain fee. - Partner or payout fee estimate. - Quote expiry timestamp. - Route type. - Expected settlement window. - Required compliance fields. ## Example quote request ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/fx/quotes \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source_currency": "EUR", "target_currency": "USD", "source_amount": "100000.00", "beneficiary_country": "US", "payment_method": "bank_transfer" }' ``` ## Quote expiry Quotes expire because FX rates, liquidity, partner fees, and route availability change. Your integration should either submit the payment before expiry or request a new quote. ## Guaranteed and indicative quotes Some quotes can be locked for a short time. Others are indicative, especially when a route depends on partner availability, local payout requirements, or compliance checks. The API indicates whether a quote is `guaranteed`, `indicative`, or `subject_to_review`. ## Conversion execution A payment can reference a quote. If the quote is valid and compatible with the payment instruction, CashXChain will use the quote assumptions to prepare the route. If the quote expired, the API returns an error and requires a new quote. ## Slippage and route changes If a payment cannot be executed under the accepted quote assumptions, CashXChain may: - Require a new quote. - Move the payment to `requires_action`. - Route through an alternative partner with equivalent or better economics. - Fail safely before execution if customer confirmation is required. ## Best practices - Display quote expiry clearly to users. - Store the `quote_id` with your invoice or payment record. - Use webhooks to track if a payment requires a new quote. - Do not assume a quote is final unless the quote response says it is guaranteed. --- # Payments Source: https://docs.cashxchain.com/docs/product/payments Description: Understand CashXChain payment workflows, statuses, and operational controls. # Payments Payments are the core resource in CashXChain. A payment represents a business instruction to move value from one account or balance to a beneficiary, with a defined amount, currency, purpose, quote, route, metadata, and lifecycle. ## Payment types CashXChain is designed to support several payment patterns: - Supplier payments: pay vendors, manufacturers, contractors, or service providers. - Platform payouts: pay sellers, freelancers, merchants, or marketplace participants. - Treasury transfers: move funds between entities, accounts, currencies, or operating balances. - Invoice payments: pay against structured invoice references. - Same-network transfers: move value between CashXChain-enabled businesses where supported. - Local payouts: settle funds through partner rails in the beneficiary currency. ## Delivery methods A payment can be delivered through any rail CashXChain supports for the corridor and account, including: - **Direct bank transfer to the beneficiary** (SEPA, SEPA Instant, FPS, ACH, wire, and equivalent local schemes). - **Local payout networks** through regulated partners. - **Stablecoin transfer** to a beneficiary on a supported chain, where set up and compliant. - **Same-network transfer** between two CashXChain-enabled accounts. Stablecoins are also used internally by CashXChain as a settlement medium between partners and corridors. The business-facing API and dashboard remain fiat-native — amounts, fees, and statements are always quoted in business currencies. See [Rails](./rails) for a full breakdown of sending and funding rails, on-chain vs off-chain routing, and how the routing engine selects between them. ## Payment lifecycle A payment moves through a normalized lifecycle even when the underlying partner or rail has its own status model. | Status | Meaning | | --- | --- | | `created` | The instruction was accepted by CashXChain. | | `requires_action` | More information, approval, or documents are required. | | `screening` | Compliance, sanctions, or risk checks are in progress. | | `authorized` | The payment is approved for processing. | | `processing` | The selected partner or rail is executing the payment. | | `settling` | Funds are moving or awaiting final confirmation. | | `completed` | The payment completed successfully. | | `failed` | The payment could not be completed. | | `cancelled` | The payment was cancelled before completion. | | `returned` | The payment was completed or sent but later returned by a downstream party. | ## Idempotency Always provide an `X-Idempotency-Key` when creating a payment. This prevents duplicate payments if your system retries after a timeout. ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/payments \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "X-Idempotency-Key: invoice-2026-1042-attempt-1" \ -H "Content-Type: application/json" \ -d '{ "source_account_id": "acct_8mJ3...", "beneficiary_id": "bnf_6rK2...", "quote_id": "fxq_9Xc2...", "amount": "25000.00", "currency": "EUR", "purpose": "supplier_payment", "reference": "INV-2026-1042" }' ``` ## Amounts and currencies Amounts are represented as strings to avoid floating-point errors. Currency codes use ISO 4217 where possible. Stablecoin settlement assets may appear in technical metadata where relevant, but business-facing fields remain fiat-first. ## Payment purpose A purpose of payment may be required depending on the corridor, amount, partner, and beneficiary country. Examples include: - `supplier_payment` - `contractor_payment` - `invoice_payment` - `marketplace_payout` - `treasury_transfer` - `software_services` - `goods_import` - `professional_services` ## Operational controls Payments can be restricted by account limits, user permissions, required approvals, risk score, corridor availability, partner availability, quote expiry, or missing beneficiary information. ## Reconciliation Each payment includes stable IDs, external references, fee breakdown, quote information, timestamps, beneficiary details, and timeline events. Use these fields to reconcile against invoices, ERP entries, and bank statements. --- # Pricing Source: https://docs.cashxchain.com/docs/product/pricing Description: Understand CashXChain pricing concepts, fees, and quote transparency. # Pricing CashXChain pricing is designed to be transparent, quote-driven, and suitable for high-volume payment workflows — including cross-border and B2B as primary cases. Pricing can vary by customer tier, corridor, currency, payment method, risk profile, partner costs, and transaction volume. Final commercial terms are defined in your agreement. ## Pricing components A transaction can include several components: | Component | Description | | --- | --- | | Transaction fee | CashXChain fee for orchestrating the payment workflow. | | FX spread | Currency conversion spread where FX is involved. | | Partner fee | Cost charged by a regulated banking, payout, on/off-ramp, or settlement partner. | | Network fee | Cost associated with a settlement network where applicable. | | Subscription fee | Monthly fee for platform, API, support, or enterprise features. | | Setup fee | One-time onboarding or integration fee for enterprise customers. | ## Quote transparency Before submitting a payment, you can request a quote. The quote shows estimated or guaranteed pricing depending on route and availability. ```json { "id": "fxq_9Xc2...", "source_amount": "100000.00", "source_currency": "EUR", "target_amount": "108420.00", "target_currency": "USD", "rate": "1.0842", "cashxchain_fee": "700.00", "fx_spread": "200.00", "partner_fee": "100.00", "pricing_type": "guaranteed", "expires_at": "2026-06-01T09:15:00Z" } ``` ## Volume-based pricing Higher-volume customers may qualify for lower transaction fees, custom FX spreads, corridor-specific pricing, or enterprise agreements. ## No hidden crypto complexity If a route uses stablecoin settlement or blockchain infrastructure in the background, the customer does not separately manage gas fees, wallets, or tokens. The total cost is presented through the quote and payment object. ## Invoices and billing CashXChain can invoice subscription fees, setup fees, and transaction fees based on the commercial agreement. Transaction-level fees are visible in payment details and statements. ## Important note Pricing shown in documentation examples is illustrative. Your actual pricing is determined by your CashXChain agreement, partner availability, payment method, risk profile, and applicable law. --- # Rails Source: https://docs.cashxchain.com/docs/product/rails Description: How CashXChain moves value — direct bank transfer, stablecoin settlement, and partner networks across on-chain and off-chain infrastructure. # Payment rails A *rail* is the underlying infrastructure that actually moves value from one place to another. CashXChain orchestrates multiple rails behind a single API and a single business workflow, and exposes enough information for finance teams to operate confidently. The platform is rail-agnostic by design. Every payment is associated with a route that may use one or more rails — chosen for speed, cost, reliability, and compliance. ## Sending rails (payouts) CashXChain can deliver a payment through any of the following, depending on corridor, currency, partner availability, and account configuration: - **Direct bank transfer to the beneficiary.** Funds arrive in the beneficiary's bank account. Underlying schemes include SEPA and SEPA Instant in the EU, FPS / Faster Payments in the UK, ACH and Fedwire in the US, and equivalent local schemes elsewhere. - **International wire.** SWIFT and correspondent banking where local rails are not available or appropriate. - **Local payout networks.** Regulated partner networks for local payouts in beneficiary currencies, including markets where bank rails are slow or unavailable. - **Stablecoin transfer.** Direct stablecoin payout to a beneficiary's address on a supported chain, where the beneficiary is set up to receive crypto-asset payouts and the corridor permits it. - **Same-network transfer.** Instant book-transfer between two CashXChain-enabled accounts. ## Funding rails (deposits) Accounts can be funded through: - **Bank transfer in.** Direct deposit, SEPA, SEPA Instant, FPS, ACH, wire, or equivalent local schemes into the account's funding details. - **Stablecoin deposit.** Inbound stablecoin transfer to a deposit address, where supported and compliant for the account. - **Internal transfer.** Movement from another CashXChain account or wallet under the same customer. The set of funding methods enabled on a given account depends on jurisdiction, partner configuration, KYB outcome, and product enablement. ## On-chain and off-chain CashXChain treats both worlds as first-class infrastructure: - **Off-chain rails** are traditional banking and payment-network rails — SEPA, SWIFT, ACH, FPS, local payout schemes, and partner internal ledgers. - **On-chain rails** are blockchain-native rails — stablecoin transfers, on-ramp and off-ramp partners, and supported public chains. Most payments use a mix. A typical cross-border flow may collect fiat off-chain, settle through a stablecoin rail in the middle, and pay out off-chain through a local partner — all of which is invisible to the business user, who sees a normal payment with a quote, a fee, and a status. ## Stablecoins Stablecoins serve two roles in CashXChain: 1. **Internal settlement.** CashXChain uses regulated stablecoins as a settlement medium between partners and corridors. This unlocks faster, cheaper, and more transparent flows than bank-only routing in many cases. The business user does not need to know which chain or asset is involved. 2. **Customer-facing rail.** Where supported and compliant, accounts can fund and pay out in stablecoins directly. This is opt-in — customers who do not want crypto exposure get fully fiat workflows. Either way, the user experience is fiat-native: amounts are quoted in business currencies, statements are issued in business currencies, and there are no seed phrases, gas tokens, or block confirmations to manage. ## Route selection The CashXChain routing engine picks a route per payment using practical criteria: - Currency pair and corridor. - Required speed, cut-off windows, and partner operating hours. - FX quote quality and expected slippage. - Total fee and partner cost. - Compliance requirements for the corridor and counterparty. - Risk score for the customer, beneficiary, and amount. - Liquidity and partner availability. - Settlement finality characteristics of the candidate rails. The chosen route is reflected in the FX quote and the resulting payment record, including expected settlement window and fee breakdown. ## Rail availability Rail availability is not uniform. It depends on: - The customer's account type, jurisdiction, and KYB state. - Enabled products and corridors on the account. - The beneficiary's country, currency, and bank or wallet setup. - Partner availability and operating hours. - Compliance requirements for the corridor. - Sandbox vs production — sandbox simulates rails rather than executing on real infrastructure. The API surfaces what is available for a given quote or payment. If a requested rail is not available, the API returns a structured error rather than silently substituting a different one. ## Best practices - Treat the rail as an outcome of routing, not as something to hard-code in your integration. Accept the route from the quote and persist the payment ID and the partner / rail references for reconciliation. - Reconcile against ledger entries and statements, not just payment statuses. - Subscribe to webhooks for `payment.completed`, `payment.returned`, and `settlement.*` events to handle rail-level outcomes. - Show users the expected settlement window from the quote, not your own estimate. - For corridors with multiple candidate rails, request a fresh quote rather than reusing an old one — rail availability and pricing change. --- # Settlement Source: https://docs.cashxchain.com/docs/product/settlement Description: Understand how CashXChain models settlement across modern and traditional rails. # Settlement Settlement is the process by which value reaches final state across the selected rails and partners. CashXChain abstracts the complexity of settlement while still exposing enough information for businesses to operate confidently. ## Settlement is route-dependent A payment may settle through different combinations of infrastructure: - Local bank transfer rails. - International wire rails. - Stablecoin settlement rails. - Partner internal ledger transfers. - Payout providers. - On/off-ramp providers. The selected route depends on the corridor, currency, amount, account status, beneficiary details, risk profile, and partner availability. ## Settlement states | State | Description | | --- | --- | | `not_started` | The payment instruction exists but settlement has not started. | | `pending_partner` | A partner has accepted the instruction or is processing it. | | `pending_network` | A network, chain, or bank rail confirmation is pending. | | `pending_payout` | Funds are ready for local payout. | | `final` | Settlement is final according to the selected route. | | `reversed` | A reversal or return occurred after processing. | | `failed` | Settlement failed before completion. | ## Speed expectations Some routes can confirm in seconds. Others depend on local banking cut-off times, beneficiary bank processing, compliance review, or partner-specific operating windows. CashXChain exposes expected settlement windows in quotes and payment details. These are estimates unless explicitly marked as guaranteed. ## Finality Finality means different things across rails. Blockchain settlement, internal partner settlement, SEPA settlement, ACH, wire, and local payout schemes each have different confirmation and return characteristics. CashXChain normalizes these differences but does not hide operational risks. If a route can be returned, recalled, or delayed, the payment timeline and risk notice will indicate that. ## Settlement references A completed payment can include several references: - CashXChain payment ID. - Customer reference. - Quote ID. - Partner reference. - Bank rail reference. - Blockchain transaction hash where relevant. - Statement line ID. ## Reconciliation Use settlement references and statements to match CashXChain payments to invoices, ERP entries, customer orders, or partner reports. --- # Wallets and balances Source: https://docs.cashxchain.com/docs/product/wallets Description: Learn how CashXChain presents balances without exposing end users to crypto complexity. # Wallets and balances CashXChain uses a wallet abstraction to present balances across currencies, accounts, partner rails, and settlement assets. The word wallet in the API refers to a logical balance container, not a requirement for end users to manage private keys. ## Business-friendly balance model A business sees balances in familiar currency terms: - Available balance: funds that can be used for eligible payments. - Pending balance: funds expected but not yet final. - Reserved balance: funds held for pending payments, fees, compliance review, or quote locks. - Restricted balance: funds that cannot currently move because of account, risk, legal, or partner restrictions. ## Logical wallets A company can have multiple logical wallets or balance containers: - Operating wallet: default working balance. - Treasury wallet: larger treasury balance or platform-level funds. - Payout wallet: funds reserved for batch payouts. - Fee wallet: fees, refunds, or platform economics. - Escrow wallet: milestone or conditional settlement workflows where supported. ## Funding an account Wallets can be funded through several rails depending on jurisdiction, partner configuration, and product enablement: - **Bank transfer in.** Direct deposit, SEPA, SEPA Instant, FPS, ACH, wire, or equivalent local schemes into the account's funding details. - **Stablecoin deposit.** Inbound stablecoin transfer to a deposit address, where supported and compliant for the account. - **Internal transfer.** Movement from another CashXChain account or wallet under the same customer. The set of methods enabled on a given account is exposed in the dashboard and through the API. See [Rails](./rails) for a full overview. ## No seed phrases CashXChain does not require business users to store seed phrases, sign blockchain transactions manually, hold gas tokens, or understand chain-specific details. Any blockchain settlement is abstracted behind the platform and partner infrastructure. ## Ledger entries Every balance change creates ledger entries. Ledger entries are immutable accounting records that describe: - The related account. - The wallet or balance container. - Debit or credit direction. - Amount and currency. - Related payment, quote, fee, adjustment, or return. - Timestamps and settlement state. - External references where applicable. ## Internal transfers Where supported, CashXChain can move funds between wallets under the same account or between enabled CashXChain accounts. Internal transfers are still logged, permissioned, and auditable. ## Partner-held funds Depending on the product configuration and jurisdiction, funds may be held, processed, or settled by regulated partners. CashXChain presents normalized balance views but does not replace the contractual or regulatory role of those partners. ## Best practices - Reconcile against ledger entries, not only payment status. - Treat pending funds as unavailable until final. - Use references that match your ERP or invoice IDs. - Subscribe to balance and payment webhooks for automation. - Apply role-based access controls for treasury users. --- # Accounts Source: https://docs.cashxchain.com/docs/platform/accounts Description: Accounts represent businesses, platforms, entities, and sub-entities in CashXChain. # Accounts An account is the main container for identity, permissions, balances, beneficiaries, payments, statements, and compliance status. ## Account types CashXChain can support several account patterns: - Business account: a company using CashXChain directly. - Platform account: a platform embedding CashXChain workflows. - Connected account: a seller, supplier, contractor, merchant, or sub-customer under a platform. - Treasury entity: an internal entity or subsidiary used for treasury operations. ## Account status | Status | Meaning | | --- | --- | | `draft` | Account data has been created but onboarding is incomplete. | | `pending_verification` | KYB or review is in progress. | | `active` | The account can use enabled products and corridors. | | `restricted` | Some functionality is limited. | | `rejected` | The account is not approved. | | `closed` | The account is no longer active. | ## Required information Required account information depends on customer type, jurisdiction, corridor, product, and partner. Typical fields include: - Legal business name. - Registration number. - Registered address. - Operating address. - Industry and business activity. - Website. - Expected monthly volume. - Source of funds. - Directors and authorized representatives. - Beneficial owners. - Supporting documents. ## Account creation example ```json { "type": "business", "legal_name": "Example Trading GmbH", "country": "DE", "registration_number": "HRB 123456", "industry": "import_export", "expected_monthly_volume": "250000.00", "expected_currencies": ["EUR", "USD"] } ``` ## Connected accounts Platforms can create connected accounts for their customers. Connected accounts may have their own verification status, beneficiaries, limits, and balances. ## Account limits Limits can apply by amount, currency, day, month, corridor, payment method, risk tier, or approval policy. Limits may change after additional review. ## Best practices - Collect complete KYB data early. - Keep business activity descriptions specific. - Store account IDs in your system. - Listen for account status webhooks. - Do not enable payments until account status and product permissions are confirmed. --- # API keys Source: https://docs.cashxchain.com/docs/platform/api-keys Description: Create, scope, rotate, and protect API keys. # API keys API keys authenticate server-side requests to the CashXChain API. ## Environments CashXChain uses separate keys for sandbox and production. - Sandbox keys start with `cx_sandbox_`. - Production keys start with `cx_live_`. Never use production keys in local development or client-side applications. ## Key scopes API keys can be scoped by permission: - `accounts:read` - `accounts:write` - `wallets:read` - `beneficiaries:write` - `quotes:write` - `payments:write` - `statements:read` - `webhooks:write` - `admin:read` Use the narrowest scope that supports your integration. ## Creating keys Admins can create keys in the dashboard or through the API where enabled. A secret is shown only once. Store it immediately in a secret manager. ## Rotation Rotate keys regularly and immediately after suspected exposure. Recommended rotation process: 1. Create a new key with the same scopes. 2. Deploy the new key to your secret manager. 3. Confirm successful API calls. 4. Revoke the old key. 5. Review logs for unexpected usage. ## Security requirements - Store keys only in server-side secret storage. - Do not commit keys to Git. - Do not expose keys in frontend code. - Restrict keys by environment and scope. - Monitor failed authentication attempts. - Revoke unused keys. ## Compromised keys If a key is compromised, revoke it immediately and contact CashXChain support if production payment capability may have been affected. --- # FX quotes Source: https://docs.cashxchain.com/docs/platform/fx-quotes Description: Platform resource model for FX quotes. # FX quotes FX quotes provide a priced and time-limited conversion proposal. ## Quote object ```json { "id": "fxq_9Xc2...", "status": "active", "source_currency": "EUR", "target_currency": "USD", "source_amount": "100000.00", "target_amount": "108420.00", "rate": "1.0842", "pricing_type": "guaranteed", "expires_at": "2026-06-01T09:15:00Z", "route": { "type": "hybrid", "estimated_settlement": "same_day" }, "fees": { "cashxchain": "700.00", "fx_spread": "200.00", "partner": "100.00" } } ``` ## Quote status | Status | Meaning | | --- | --- | | `active` | Quote can be used. | | `expired` | Quote expiry passed. | | `accepted` | Quote was attached to a payment. | | `cancelled` | Quote is no longer usable. | | `replaced` | A newer quote should be used. | ## Source amount vs target amount A quote can be source-fixed or target-fixed. - Source-fixed: you know how much the sender pays. - Target-fixed: you know how much the beneficiary should receive. Target-fixed quotes may require more precise route and fee assumptions. ## Quote expiry handling If a quote expires before payment creation, request a new quote. If a quote expires during a partner review, CashXChain may require confirmation or issue an updated quote depending on account settings. ## Corridor availability Not every currency pair or country pair is available in every environment. The API returns clear errors when a corridor is not enabled. --- # Notifications Source: https://docs.cashxchain.com/docs/platform/notifications Description: Notifications and event delivery in CashXChain. # Notifications Notifications keep your team and systems informed about account, payment, quote, balance, and webhook events. ## Notification channels CashXChain supports several notification patterns: - Webhooks for system-to-system automation. - Dashboard notifications for operations teams. - Email notifications for selected administrative and compliance events. - API polling for backup reconciliation. Webhooks are the recommended integration mechanism for production systems. ## Event categories | Category | Examples | | --- | --- | | Account | `account.updated`, `account.verified`, `account.restricted` | | Beneficiary | `beneficiary.created`, `beneficiary.requires_action`, `beneficiary.active` | | Quote | `quote.created`, `quote.expired`, `quote.accepted` | | Payment | `payment.created`, `payment.processing`, `payment.completed`, `payment.failed` | | Balance | `balance.updated`, `ledger_entry.created` | | Compliance | `review.opened`, `review.closed`, `document.required` | | Webhook | `webhook.delivery_failed`, `webhook.endpoint_disabled` | ## Notification preferences Account admins can configure which dashboard or email notifications are sent to which roles. API notifications are configured through webhook endpoints. ## Operational alerts Critical events should be monitored by your operations team: - Payment failures. - Returned payments. - Account restrictions. - Missing documents. - Webhook delivery failures. - Large balance changes. - Unusual activity alerts. ## Best practices - Use webhooks for automation. - Use dashboard alerts for human operations. - Keep email alerts focused on critical events. - Route compliance alerts to trained reviewers. - Test event handling in sandbox before production. --- # Platform overview Source: https://docs.cashxchain.com/docs/platform/overview Description: Overview of CashXChain platform resources and workflows. # Platform overview The CashXChain platform is organized around business resources that map to real payment operations. ## Core resources | Resource | Purpose | | --- | --- | | Account | A verified business, platform, entity, or sub-entity. | | User | A person with access to an account. | | API key | A credential used by a server-side integration. | | Wallet | A logical balance container. | | Beneficiary | A person or business receiving funds. | | FX quote | A priced conversion and route proposal. | | Payment | An instruction to move value. | | Statement | A reconciliation export for a period. | | Webhook endpoint | A URL that receives event notifications. | | Event | A signed notification about a resource change. | ## Typical implementation path 1. Create or access a business account. 2. Complete KYB and risk review. 3. Generate sandbox API keys. 4. Create a beneficiary. 5. Request an FX quote. 6. Create a payment using the quote. 7. Receive webhook events. 8. Reconcile with statements and ledger records. 9. Move to production after review. ## Hosted and API-only flows CashXChain supports two integration models: - API-only: your platform owns the user experience and calls CashXChain APIs from your backend. - Hosted: CashXChain provides secure hosted steps for onboarding, payment confirmation, or additional verification where required. The exact model depends on your product, jurisdiction, partner requirements, and risk review. ## Account hierarchy A platform customer may operate one master account and create connected accounts for sellers, merchants, suppliers, or internal entities. Enterprise customers may use multiple accounts for subsidiaries, treasury entities, or operational separation. ## Event-driven operations CashXChain is designed for event-driven automation. Webhooks notify your system when payments change state, account verification is updated, a balance changes, a quote expires, or an action is required. ## Production readiness Before production, CashXChain reviews your use case, expected corridors, transaction volumes, compliance model, webhook handling, error handling, and security posture. --- # Payments Source: https://docs.cashxchain.com/docs/platform/payments Description: Platform-level payment resource behavior and operational model. # Payments The platform payment resource represents a normalized instruction and lifecycle across all supported routes. ## Payment object A payment object contains: - `id`: CashXChain payment ID. - `source_account_id`: account that owns the payment. - `source_wallet_id`: balance container to debit. - `beneficiary_id`: recipient. - `quote_id`: FX quote, if conversion is involved. - `amount`: amount to debit or send. - `currency`: source currency. - `target_amount`: expected beneficiary amount, if known. - `target_currency`: beneficiary currency. - `status`: normalized lifecycle status. - `purpose`: business reason. - `reference`: customer-visible reference. - `metadata`: customer-defined key-value pairs. - `timeline`: status history. - `fees`: fee breakdown. ## Create payment flow 1. Confirm the account is active. 2. Confirm the beneficiary is usable. 3. Request a quote if FX is required. 4. Create the payment with an idempotency key. 5. Wait for webhooks. 6. Handle `requires_action`, `failed`, `returned`, and `completed` states. 7. Reconcile with statements. ## Metadata Use metadata to attach internal references: ```json { "metadata": { "invoice_id": "INV-2026-1042", "erp_vendor_id": "VEN-4481", "department": "supply_chain", "created_by": "treasury-bot" } } ``` Metadata is not a substitute for required compliance fields. Do not store sensitive secrets in metadata. ## Cancellation Cancellation is only possible while a payment is still cancellable. Once a partner or rail has executed a step, cancellation may no longer be available and a return or reversal process may be required. ## Returns A completed payment may later be returned by a beneficiary bank or downstream rail. Your system should handle `payment.returned` events and reconcile the corresponding balance movement. --- # Statements Source: https://docs.cashxchain.com/docs/platform/statements Description: Statements and reconciliation exports. # Statements Statements provide structured exports for finance, accounting, audit, and reconciliation workflows. ## Statement types CashXChain can provide: - Account statements. - Wallet statements. - Payment statements. - Fee statements. - Ledger exports. - Monthly activity reports. - Custom enterprise exports. ## Statement fields A statement line can include: - Statement line ID. - Date and time. - Account ID. - Wallet ID. - Payment ID. - Ledger entry ID. - Debit amount. - Credit amount. - Currency. - Fee amount. - FX rate. - Reference. - Counterparty. - Status. - Partner reference. ## Export formats Supported formats may include: - CSV. - JSON. - PDF summary. - Accounting-system-specific exports where available. ## Reconciliation workflow 1. Store CashXChain payment IDs and statement line IDs. 2. Use your own invoice or ERP reference in payment metadata. 3. Download statement exports for the relevant period. 4. Match payment IDs, references, amounts, fees, and currencies. 5. Investigate unmatched lines through the payment timeline. ## Availability Statement availability depends on account status, environment, and product configuration. Sandbox statements are for testing only and do not represent real financial records. ## Best practices - Reconcile daily for high-volume accounts. - Separate fees from principal amounts. - Track returned payments as separate ledger events. - Use immutable exports for audit archives. --- # Wallets Source: https://docs.cashxchain.com/docs/platform/wallets Description: Learn how CashXChain presents balances without exposing end users to crypto complexity. # Wallets CashXChain uses a wallet abstraction to present balances across currencies, accounts, partner rails, and settlement assets. The word wallet in the API refers to a logical balance container, not a requirement for end users to manage private keys. ## Business-friendly balance model A business sees balances in familiar currency terms: - Available balance: funds that can be used for eligible payments. - Pending balance: funds expected but not yet final. - Reserved balance: funds held for pending payments, fees, compliance review, or quote locks. - Restricted balance: funds that cannot currently move because of account, risk, legal, or partner restrictions. ## Logical wallets A company can have multiple logical wallets or balance containers: - Operating wallet: default working balance. - Treasury wallet: larger treasury balance or platform-level funds. - Payout wallet: funds reserved for batch payouts. - Fee wallet: fees, refunds, or platform economics. - Escrow wallet: milestone or conditional settlement workflows where supported. ## No seed phrases CashXChain does not require business users to store seed phrases, sign blockchain transactions manually, hold gas tokens, or understand chain-specific details. Any blockchain settlement is abstracted behind the platform and partner infrastructure. ## Ledger entries Every balance change creates ledger entries. Ledger entries are immutable accounting records that describe: - The related account. - The wallet or balance container. - Debit or credit direction. - Amount and currency. - Related payment, quote, fee, adjustment, or return. - Timestamps and settlement state. - External references where applicable. ## Internal transfers Where supported, CashXChain can move funds between wallets under the same account or between enabled CashXChain accounts. Internal transfers are still logged, permissioned, and auditable. ## Partner-held funds Depending on the product configuration and jurisdiction, funds may be held, processed, or settled by regulated partners. CashXChain presents normalized balance views but does not replace the contractual or regulatory role of those partners. ## Best practices - Reconcile against ledger entries, not only payment status. - Treat pending funds as unavailable until final. - Use references that match your ERP or invoice IDs. - Subscribe to balance and payment webhooks for automation. - Apply role-based access controls for treasury users. --- # Webhooks Source: https://docs.cashxchain.com/docs/platform/webhooks Description: Configure webhook endpoints and receive signed events. # Webhooks Webhooks notify your system when important events happen in CashXChain. ## Endpoint requirements Your endpoint must: - Use HTTPS. - Accept POST requests. - Return a 2xx response quickly. - Verify CashXChain signatures. - Handle duplicate events safely. - Process events asynchronously when possible. ## Event format ```json { "id": "evt_7F2...", "type": "payment.completed", "created_at": "2026-06-01T09:00:42Z", "environment": "sandbox", "resource_type": "payment", "resource_id": "pay_6pD3...", "data": { "id": "pay_6pD3...", "status": "completed" } } ``` ## Signature headers CashXChain signs webhook payloads. Example headers: ```text X-CXC-Event-Id: evt_7F2... X-CXC-Timestamp: 1780304442 X-CXC-Signature: v1=... ``` Verify the signature before trusting the payload. ## Delivery behavior If your endpoint does not return a 2xx response, CashXChain retries delivery with backoff. Events may be delivered more than once and may arrive out of order. ## Idempotency Use the event ID to deduplicate processing. Your webhook handler should be safe to run multiple times. ## Common event types - `account.verified` - `beneficiary.active` - `quote.expired` - `payment.created` - `payment.requires_action` - `payment.processing` - `payment.completed` - `payment.failed` - `payment.returned` - `balance.updated` - `statement.available` ## Testing Use sandbox to trigger test events and validate signature verification, retries, duplicate handling, and reconciliation workflows. --- # Authentication Source: https://docs.cashxchain.com/docs/api/authentication Description: Authenticate API requests securely. # Authentication CashXChain uses bearer tokens for API authentication. ## Authorization header ```text Authorization: Bearer cx_sandbox_... ``` ## Key types | Key type | Environment | Usage | | --- | --- | --- | | Sandbox key | Sandbox | Development, testing, simulated payments. | | Production key | Production | Live payment workflows. | ## Server-side only API keys must only be used from trusted server-side environments. Never expose a CashXChain API key in browser JavaScript, mobile apps, public repositories, logs, or analytics tools. ## Scopes Keys can be scoped to reduce risk. Example scopes: ```text accounts:read accounts:write beneficiaries:write quotes:write payments:write statements:read webhooks:write ``` ## Authentication errors | HTTP | Code | Meaning | | --- | --- | --- | | 401 | `authentication_required` | Missing bearer token. | | 401 | `invalid_api_key` | Key is invalid or revoked. | | 403 | `insufficient_scope` | Key lacks required permission. | | 403 | `environment_mismatch` | Key was used against the wrong environment. | ## Key rotation Rotate keys regularly and whenever you suspect exposure. ## Webhook signatures API authentication protects requests to CashXChain. Webhook signatures protect events sent from CashXChain to your system. Configure both for a secure integration. --- # Errors Source: https://docs.cashxchain.com/docs/api/errors Description: CashXChain API error structure and common error codes. # Errors CashXChain uses standard HTTP status codes and structured JSON error responses. ## Error format ```json { "error": { "code": "quote_expired", "message": "The selected FX quote has expired.", "request_id": "req_7xY...", "details": { "quote_id": "fxq_9Xc2..." } } } ``` ## HTTP status codes | HTTP | Meaning | | --- | --- | | 400 | Invalid request. | | 401 | Authentication failed. | | 403 | Permission or product access denied. | | 404 | Resource not found. | | 409 | Conflict, duplicate, or invalid state transition. | | 422 | Request is valid JSON but cannot be processed. | | 429 | Rate limit exceeded. | | 500 | Internal error. | | 503 | Temporary service or partner unavailable. | ## Common error codes | Code | Meaning | | --- | --- | | `invalid_request` | Request body or parameters are invalid. | | `authentication_required` | Missing API key. | | `invalid_api_key` | API key is invalid or revoked. | | `insufficient_scope` | API key lacks required scope. | | `resource_not_found` | Resource does not exist or is not accessible. | | `quote_expired` | FX quote is no longer valid. | | `corridor_unavailable` | Currency or country route is not enabled. | | `account_not_active` | Account cannot transact. | | `beneficiary_not_active` | Beneficiary cannot receive payments. | | `requires_action` | Additional information or approval is required. | | `idempotency_conflict` | Same idempotency key used with different body. | | `partner_unavailable` | Downstream partner is temporarily unavailable. | | `rate_limit_exceeded` | Too many requests. | ## Request IDs Every error includes a request ID where possible. Include this ID when contacting support. ## Safe retries Payment creation should always include an idempotency key. This makes network retries safe. --- # FX API Source: https://docs.cashxchain.com/docs/api/fx Description: Request FX quotes and create conversions. # FX API The FX API provides quote-driven conversion workflows. ## Create quote ```http POST /v1/fx/quotes ``` ```json { "source_currency": "EUR", "target_currency": "USD", "source_amount": "100000.00", "beneficiary_country": "US", "payment_method": "bank_transfer" } ``` ## Quote response ```json { "id": "fxq_9Xc2...", "source_currency": "EUR", "target_currency": "USD", "source_amount": "100000.00", "target_amount": "108420.00", "rate": "1.0842", "expires_at": "2026-06-01T09:15:00Z", "pricing_type": "guaranteed" } ``` ## Retrieve quote ```http GET /v1/fx/quotes/{quote_id} ``` ## Create conversion Some customers may convert balances without creating an external payment. ```http POST /v1/fx/conversions ``` ```json { "quote_id": "fxq_9Xc2...", "source_wallet_id": "wlt_eur...", "target_wallet_id": "wlt_usd..." } ``` ## Quote expiry If the quote is expired, the API returns `quote_expired`. Request a new quote and present updated pricing to the user. ## Indicative quotes For some corridors, the API may return an indicative quote. Indicative quotes require confirmation before execution. --- # Getting Started Source: https://docs.cashxchain.com/docs/api/getting-started Description: Make your first CashXChain API request. # API getting started The CashXChain API is a REST API for payments, FX quotes, accounts, balances, beneficiaries, statements, and webhooks. ## Base URLs ```text Sandbox: https://api.sandbox.cashxchain.com/v1 Production: https://api.cashxchain.com/v1 ``` Use sandbox for development and testing. Production access requires account approval and product enablement. ## Authentication Send your API key as a bearer token. ```bash curl https://api.sandbox.cashxchain.com/v1/accounts \ -H "Authorization: Bearer $CXC_API_KEY" ``` ## Create your first quote ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/fx/quotes \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source_currency": "EUR", "target_currency": "USD", "source_amount": "1000.00", "beneficiary_country": "US" }' ``` ## Create your first payment ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/payments \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "X-Idempotency-Key: demo-payment-001" \ -H "Content-Type: application/json" \ -d '{ "source_account_id": "acct_sandbox_123", "beneficiary_id": "bnf_sandbox_123", "quote_id": "fxq_sandbox_123", "amount": "1000.00", "currency": "EUR", "purpose": "supplier_payment", "reference": "DEMO-001" }' ``` ## API conventions - JSON request and response bodies. - ISO 8601 timestamps in UTC. - Amounts as decimal strings. - ISO 4217 currency codes where applicable. - Cursor-based pagination for lists. - Idempotency keys for payment creation. - Stable resource IDs with prefixes such as `acct_`, `pay_`, `fxq_`, `evt_`. ## Next steps 1. Read [Authentication](./authentication). 2. Configure [Webhooks](./webhooks). 3. Follow the [Integration Quickstart](../integration/quickstart). 4. Review [Errors](./errors) and [Rate limits](./rate-limits). --- # Payments API Source: https://docs.cashxchain.com/docs/api/payments Description: Create and manage payment instructions. # Payments API The Payments API creates and tracks payment instructions. ## Create a payment ```http POST /v1/payments ``` ```json { "source_account_id": "acct_8mJ3...", "source_wallet_id": "wlt_2Gk4...", "beneficiary_id": "bnf_6rK2...", "quote_id": "fxq_9Xc2...", "amount": "25000.00", "currency": "EUR", "purpose": "supplier_payment", "reference": "INV-2026-1042", "metadata": { "invoice_id": "INV-2026-1042" } } ``` Always send `X-Idempotency-Key`. ## Response ```json { "id": "pay_6pD3...", "status": "created", "amount": "25000.00", "currency": "EUR", "beneficiary_id": "bnf_6rK2...", "quote_id": "fxq_9Xc2...", "created_at": "2026-06-01T09:00:12Z" } ``` ## Retrieve a payment ```http GET /v1/payments/{payment_id} ``` ## List payments ```http GET /v1/payments?account_id=acct_8mJ3&limit=50 ``` ## Cancel a payment ```http POST /v1/payments/{payment_id}/cancel ``` Cancellation is only possible before the payment reaches a non-cancellable execution state. ## Payment timeline ```http GET /v1/payments/{payment_id}/timeline ``` Use the timeline for support, audit, and reconciliation. ## Webhook events Payment changes produce events such as: - `payment.created` - `payment.requires_action` - `payment.screening` - `payment.authorized` - `payment.processing` - `payment.completed` - `payment.failed` - `payment.returned` --- # Rate limits Source: https://docs.cashxchain.com/docs/api/rate-limits Description: CashXChain API rate limits and retry guidance. # Rate limits Rate limits protect platform availability and partner integrations. ## Limit model Limits may apply by: - API key. - Account. - Endpoint group. - Environment. - Customer tier. - Partner route. ## Rate limit response When you exceed a limit, the API returns HTTP 429. ```json { "error": { "code": "rate_limit_exceeded", "message": "Too many requests. Retry after the time indicated in the response headers." } } ``` ## Headers Responses may include: ```text X-RateLimit-Limit: 600 X-RateLimit-Remaining: 42 X-RateLimit-Reset: 1780304442 Retry-After: 30 ``` ## Retry strategy Use exponential backoff with jitter. Do not retry immediately in a tight loop. Recommended behavior: - Retry 429 responses after `Retry-After`. - Retry temporary 5xx responses with backoff. - Do not retry validation errors without changing the request. - Use idempotency keys when retrying payment creation. ## Webhook retries Webhook delivery retries are managed by CashXChain. Your endpoint should return quickly and process events asynchronously. ## Higher limits Enterprise customers can request higher limits based on traffic patterns, payment volume, and production readiness. --- # Sandbox vs production Source: https://docs.cashxchain.com/docs/api/sandbox-vs-production Description: Differences between test and live CashXChain environments. # Sandbox vs production CashXChain provides two **fully separated** environments — sandbox and production. Each has its own subdomains for the API, web app, developer portal, and authentication. Documentation, status, and the marketing site are shared. This separation is intentional and stricter than what many other platforms do. ## Full separation, by design There is **no shared session and no single sign-on between environments**. You sign in to each one independently. Concretely: - Separate user accounts. A sandbox account is not a production account. - Separate API keys. `cx_sandbox_...` keys never authenticate against the production API and vice versa. - Separate auth domains, web apps, and developer portals. - Separate data. No sandbox object is visible from production and no production object is visible from sandbox. - Separate webhooks. A sandbox webhook endpoint is registered only in the sandbox dashboard. Both environments are self-serve. You can register for either or both at any time — just create a separate account for each. Production registration is open without prior approval; KYB completion and product enablement gate the ability to send live payments, not the ability to sign up. The recommended flow is to start in sandbox, build and validate the integration, and then register for production when you are ready to go live. ## Environment URLs | Service | Production | Sandbox | | --- | --- | --- | | API | `https://api.cashxchain.com` | `https://api.sandbox.cashxchain.com` | | Web app | `https://app.cashxchain.com` | `https://app.sandbox.cashxchain.com` | | Developer portal | `https://dev.cashxchain.com` | `https://dev.sandbox.cashxchain.com` | | Authentication | `https://auth.cashxchain.com` | `https://auth.sandbox.cashxchain.com` | | — Sign up | `https://auth.cashxchain.com/register` | `https://auth.sandbox.cashxchain.com/register` | | — Sign in | `https://auth.cashxchain.com/login` | `https://auth.sandbox.cashxchain.com/login` | | Documentation | `https://docs.cashxchain.com` | `https://docs.cashxchain.com` | | Status | `https://status.cashxchain.com` | `https://status.cashxchain.com` | | Marketing site | `https://www.cashxchain.com` | `https://www.cashxchain.com` | The web app (`app.*`) is the operational dashboard for both environments. The developer portal (`dev.*`) is where you manage API keys, webhook endpoints, sandbox simulators, and integration settings. Authentication uses the same `/login` and `/register` paths in both environments. ## Sandbox Sandbox is for development, testing, and integration validation. It uses simulated or test partner behavior and does not move real funds. Use sandbox to test: - API authentication. - Account onboarding states. - Beneficiary creation. - FX quote requests. - Payment creation. - Payment status transitions. - Webhook delivery and retries. - Error handling. - Statement exports. ## Production Production is for live payments and real operational workflows. Sign-up is self-serve at [auth.cashxchain.com/register](https://auth.cashxchain.com/register) — you do not need prior approval to create an account. To send live payments you then need to complete KYB, accept the relevant contractual terms, pass partner and security review, and have the relevant products enabled on your account. ## Differences | Feature | Sandbox | Production | | --- | --- | --- | | Funds | Simulated | Real | | API keys | `cx_sandbox_...` | `cx_live_...` | | Webhooks | Test events | Live events | | Partner execution | Simulated or test-mode | Regulated partner systems | | KYB | Simulated states | Required review | | Statements | Test records | Operational records | ## Test scenarios Sandbox supports simulated scenarios such as: - Payment completed. - Payment failed. - Payment returned. - Quote expired. - Beneficiary requires more information. - Account restricted. - Webhook delivery failure. ## Go-live checklist Before production: - Complete KYB and account approval. - Configure production webhook endpoints. - Verify webhook signatures. - Implement idempotency. - Review rate limits. - Test failure and return handling. - Validate reconciliation exports. - Store production API keys in a secret manager. --- # SDKs Source: https://docs.cashxchain.com/docs/api/sdks Description: SDK strategy and example usage for CashXChain integrations. # SDKs CashXChain is API-first. Official SDKs will be released for common backend environments as the platform matures. ## Planned SDKs - TypeScript / Node.js. - Python. - Go. - Java / Kotlin. - PHP for platform and ERP integrations. ## Current recommendation Until an official SDK is available for your language, use HTTPS directly with a mature HTTP client. CashXChain uses simple JSON request and response bodies. ## TypeScript example ```ts const response = await fetch('https://api.sandbox.cashxchain.com/v1/fx/quotes', { method: 'POST', headers: { Authorization: `Bearer ${process.env.CXC_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ source_currency: 'EUR', target_currency: 'USD', source_amount: '1000.00', }), }); if (!response.ok) { throw new Error(await response.text()); } const quote = await response.json(); ``` ## Python example ```py import os import requests resp = requests.post( 'https://api.sandbox.cashxchain.com/v1/fx/quotes', headers={ 'Authorization': f"Bearer {os.environ['CXC_API_KEY']}", 'Content-Type': 'application/json', }, json={ 'source_currency': 'EUR', 'target_currency': 'USD', 'source_amount': '1000.00', }, timeout=30, ) resp.raise_for_status() quote = resp.json() ``` ## SDK requirements Any official SDK will support: - Request signing or bearer authentication. - Idempotency key helpers. - Pagination helpers. - Webhook signature verification. - Typed errors. - Sandbox and production environment separation. --- # Wallets API Source: https://docs.cashxchain.com/docs/api/wallets Description: Retrieve logical wallets, balances, and ledger entries. # Wallets API Wallets represent logical balance containers associated with an account. ## List wallets ```http GET /v1/wallets?account_id=acct_8mJ3 ``` ## Wallet object ```json { "id": "wlt_2Gk4...", "account_id": "acct_8mJ3...", "type": "operating", "currency": "EUR", "status": "active", "created_at": "2026-06-01T09:00:00Z" } ``` ## Get balances ```http GET /v1/wallets/{wallet_id}/balances ``` ```json { "wallet_id": "wlt_2Gk4...", "balances": [ { "currency": "EUR", "available": "98000.00", "pending": "2500.00", "reserved": "1000.00", "restricted": "0.00" } ] } ``` ## Ledger entries ```http GET /v1/wallets/{wallet_id}/ledger-entries ``` Ledger entries are the recommended source for reconciliation because they represent actual balance movements. ## Create internal transfer ```http POST /v1/wallet-transfers ``` ```json { "from_wallet_id": "wlt_source...", "to_wallet_id": "wlt_target...", "amount": "1000.00", "currency": "EUR", "reference": "Treasury rebalance" } ``` Internal transfers are available only where enabled and permissioned. --- # Webhooks API Source: https://docs.cashxchain.com/docs/api/webhooks Description: Configure webhook endpoints and receive signed events. # Webhooks API Webhooks notify your system when important events happen in CashXChain. ## Endpoint requirements Your endpoint must: - Use HTTPS. - Accept POST requests. - Return a 2xx response quickly. - Verify CashXChain signatures. - Handle duplicate events safely. - Process events asynchronously when possible. ## Event format ```json { "id": "evt_7F2...", "type": "payment.completed", "created_at": "2026-06-01T09:00:42Z", "environment": "sandbox", "resource_type": "payment", "resource_id": "pay_6pD3...", "data": { "id": "pay_6pD3...", "status": "completed" } } ``` ## Signature headers CashXChain signs webhook payloads. Example headers: ```text X-CXC-Event-Id: evt_7F2... X-CXC-Timestamp: 1780304442 X-CXC-Signature: v1=... ``` Verify the signature before trusting the payload. ## Delivery behavior If your endpoint does not return a 2xx response, CashXChain retries delivery with backoff. Events may be delivered more than once and may arrive out of order. ## Idempotency Use the event ID to deduplicate processing. Your webhook handler should be safe to run multiple times. ## Common event types - `account.verified` - `beneficiary.active` - `quote.expired` - `payment.created` - `payment.requires_action` - `payment.processing` - `payment.completed` - `payment.failed` - `payment.returned` - `balance.updated` - `statement.available` ## Testing Use sandbox to trigger test events and validate signature verification, retries, duplicate handling, and reconciliation workflows. --- # Best practices Source: https://docs.cashxchain.com/docs/integration/best-practices Description: Recommended integration practices for production reliability. # Best practices Production payment systems require careful engineering and operations. ## Use idempotency everywhere it matters Payment creation, beneficiary creation, and internal transfers should use stable idempotency keys where supported. ## Treat webhooks as notifications, not commands A webhook tells you something changed. Fetch the latest resource if you need authoritative state. ## Store CashXChain IDs Store IDs for accounts, beneficiaries, quotes, payments, ledger entries, and events. ## Build for exceptions Handle: - Quote expiry. - Required action. - Payment failure. - Payment return. - Account restriction. - Webhook duplicate. - Partner downtime. - Rate limits. ## Separate duties Use approvals for large or sensitive payments. Do not let the same user create and approve high-value transfers without controls. ## Secure credentials Use a secret manager, rotate keys, and never expose production keys in frontend code. ## Reconcile daily High-volume accounts should reconcile at least daily using ledger entries and statements. ## Test before production Use sandbox to simulate success and failure paths. Do not go live with only the happy path implemented. --- # FX guide Source: https://docs.cashxchain.com/docs/integration/fx-guide Description: Implement quote-driven FX safely. # FX guide FX should be explicit, transparent, and auditable. ## Source-fixed payments Use source-fixed quotes when the sender knows how much they want to debit. Example: pay EUR 10,000 and receive the best available USD amount. ## Target-fixed payments Use target-fixed quotes when the beneficiary must receive an exact amount. Example: supplier invoice requires exactly USD 25,000. Target-fixed flows may require additional fee handling because the source amount can change. ## Displaying quotes Show users: - Source amount. - Target amount. - Currency pair. - Rate. - Fees. - Expiry time. - Estimated settlement time. - Whether quote is guaranteed or indicative. ## Quote expiry If the quote expires, request a new quote. Do not silently execute at a different rate without user or policy approval. ## Reconciliation Store quote IDs with payment records. Quote IDs help explain FX rate and fee differences during reconciliation. --- # Payments guide Source: https://docs.cashxchain.com/docs/integration/payments-guide Description: Build a robust payment integration. # Payments guide A robust payment integration must handle success, failure, review, retries, duplicate events, quote expiry, and reconciliation. ## Recommended flow 1. Create or retrieve beneficiary. 2. Request FX quote if required. 3. Create payment with idempotency key. 4. Store payment ID and quote ID. 5. Listen for webhooks. 6. Handle `requires_action`. 7. Reconcile on completion. ## Idempotency strategy Use a stable business identifier as part of your idempotency key, such as invoice ID plus attempt number. ```text invoice-INV-2026-1042-payment-attempt-1 ``` If you retry the exact same request with the same key, CashXChain returns the original result. If you reuse the same key with a different body, the API returns `idempotency_conflict`. ## Payment references Use references that finance teams recognize: - Invoice number. - Purchase order. - Supplier ID. - Customer order ID. - Internal treasury transfer ID. ## Handling `requires_action` A payment may require action because of missing data, expired quote, beneficiary review, account restriction, approval requirement, or partner request. Your integration should surface the action to the correct user or operations team. ## Handling returns Returns can happen after apparent completion on some rails. Always listen for `payment.returned` and reconcile the returned amount as a separate event. ## Polling fallback Use webhooks as the primary source of updates. Poll payment status only as a fallback or during reconciliation. --- # QA checklist Source: https://docs.cashxchain.com/docs/integration/qa-checklist Description: Pre-production checklist for CashXChain integrations. # QA checklist Use this checklist before requesting production access. ## Authentication - [ ] API keys are stored in a secret manager. - [ ] Sandbox and production keys are separated. - [ ] Keys use least-privilege scopes. - [ ] Key rotation process is documented. ## Payments - [ ] Payment creation uses idempotency keys. - [ ] Quote expiry is handled. - [ ] `requires_action` is handled. - [ ] Failed payments are handled. - [ ] Returned payments are handled. - [ ] Payment references match internal systems. ## Webhooks - [ ] Endpoint uses HTTPS. - [ ] Signatures are verified. - [ ] Duplicate events are ignored safely. - [ ] Events are processed asynchronously. - [ ] Out-of-order events are handled. - [ ] Delivery failures are monitored. ## Reconciliation - [ ] Payment IDs are stored. - [ ] Quote IDs are stored. - [ ] Ledger entries are imported. - [ ] Statements are downloaded and matched. - [ ] Fees and FX are reconciled separately. ## Security - [ ] No keys in frontend code. - [ ] No secrets in logs. - [ ] User roles are configured. - [ ] Admin MFA is enabled where available. - [ ] Incident contacts are defined. ## Compliance - [ ] KYB data collection is complete. - [ ] Beneficiary data is accurate. - [ ] Purpose of payment is captured. - [ ] Customer terms and disclosures are shown where required. - [ ] Internal escalation path is defined for reviews. --- # Quickstart Source: https://docs.cashxchain.com/docs/integration/quickstart Description: Integrate CashXChain in a few steps. # Integration quickstart This guide walks through a basic CashXChain integration. ## 1. Get sandbox access Create a sandbox account and generate a sandbox API key in the dashboard. ```bash export CXC_API_KEY=cx_sandbox_... ``` ## 2. Configure webhooks Create a webhook endpoint in your backend and register it in the dashboard. Your endpoint should: - Use HTTPS. - Verify signatures. - Store event IDs. - Process events asynchronously. ## 3. Create a beneficiary ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/beneficiaries \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "business", "name": "Example Supplier Ltd", "country": "US", "currency": "USD", "bank_account": { "account_number": "000123456789", "routing_number": "021000021" } }' ``` ## 4. Request a quote ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/fx/quotes \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source_currency": "EUR", "target_currency": "USD", "source_amount": "1000.00", "beneficiary_country": "US" }' ``` ## 5. Create a payment ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/payments \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "X-Idempotency-Key: quickstart-001" \ -H "Content-Type: application/json" \ -d '{ "source_account_id": "acct_sandbox_123", "beneficiary_id": "bnf_sandbox_123", "quote_id": "fxq_sandbox_123", "amount": "1000.00", "currency": "EUR", "purpose": "supplier_payment", "reference": "QS-001" }' ``` ## 6. Reconcile Listen for `payment.completed` and download statements to match payments against your internal records. ## Production Production access requires business verification, use-case review, partner enablement, and security validation. --- # Wallets guide Source: https://docs.cashxchain.com/docs/integration/wallets-guide Description: Integrate balances, wallets, and ledger entries. # Wallets guide Wallets and ledger entries give your finance team visibility into funds and balance movements. ## Displaying balances Show balances by currency and status: - Available. - Pending. - Reserved. - Restricted. Avoid showing pending funds as spendable. ## Ledger integration Use ledger entries for accounting and reconciliation. Recommended local model: - `cashxchain_ledger_entry_id` - `cashxchain_payment_id` - `account_id` - `wallet_id` - `direction` - `amount` - `currency` - `reference` - `created_at` ## Balance updates Subscribe to `balance.updated` and `ledger_entry.created` events. Re-fetch the wallet balance after important updates. ## Internal transfers If enabled, internal transfers can move funds between wallets or entities. Treat these transfers like payments: use references, approvals, and reconciliation. ## Operational controls Restrict who can view, move, or reserve funds. Treasury wallets should have tighter access than standard operating wallets. --- # Webhooks guide Source: https://docs.cashxchain.com/docs/integration/webhooks-guide Description: Build a production-ready webhook receiver. # Webhooks guide Webhooks are the backbone of a reliable CashXChain integration. ## Handler design Your handler should: 1. Read the raw request body. 2. Verify signature. 3. Check timestamp tolerance. 4. Store event ID. 5. Deduplicate if already processed. 6. Acknowledge with 2xx quickly. 7. Process event asynchronously. 8. Fetch the latest resource state if needed. ## Pseudocode ```ts app.post('/cashxchain/webhooks', async (req, res) => { const rawBody = req.rawBody; const signature = req.header('X-CXC-Signature'); const timestamp = req.header('X-CXC-Timestamp'); verifyCashXChainSignature(rawBody, signature, timestamp, webhookSecret); const event = JSON.parse(rawBody.toString('utf8')); if (await alreadyProcessed(event.id)) { return res.sendStatus(200); } await storeEvent(event); await enqueueEventProcessing(event.id); return res.sendStatus(200); }); ``` ## Ordering Events may arrive out of order. Fetch the current payment or account state before making irreversible decisions. ## Retries CashXChain retries failed deliveries. Make your handler idempotent. ## Monitoring Monitor: - 2xx response rate. - Signature verification failures. - Queue latency. - Duplicate events. - Unhandled event types. - Delivery failure alerts. --- # Access control Source: https://docs.cashxchain.com/docs/security/access-control Description: Roles, permissions, API key scopes, and approval controls. # Access control Access control ensures that only authorized users and systems can perform sensitive actions. ## User roles Common roles include: - Owner: full account administration. - Admin: user, key, and configuration management. - Developer: API keys, webhooks, and sandbox tools. - Finance operator: create beneficiaries and payments. - Approver: approve payments or changes. - Compliance reviewer: review onboarding, documents, and risk events. - Viewer: read-only access. ## API scopes API keys should be scoped to the minimum required permissions. Do not use an admin-level key for routine payment creation. ## Approval workflows Enterprise accounts can require approvals for: - New beneficiaries. - Payments above thresholds. - High-risk corridors. - New payout methods. - API key creation. - User role changes. ## Separation of duties For high-volume accounts, separate the ability to create a payment from the ability to approve it. This reduces fraud and operational risk. ## Session security CashXChain may require multi-factor authentication for dashboard users, especially admins and approvers. ## Deprovisioning Remove users and rotate credentials immediately when employees, contractors, or vendors no longer require access. --- # Data isolation Source: https://docs.cashxchain.com/docs/security/data-isolation Description: How CashXChain separates customer data and environments. # Data isolation CashXChain separates customer data, environments, credentials, and operational records to protect confidentiality and reduce cross-account risk. ## Account boundaries Resources belong to an account. Users and API keys can only access resources permitted by their account roles and scopes. ## Platform accounts Platforms with connected accounts must enforce tenant boundaries in their own systems. CashXChain resource IDs should be mapped carefully to the correct tenant, seller, customer, or entity. ## Environment boundaries Sandbox and production are separate environments. Sandbox data must not be treated as real financial data. Production credentials must never be used in sandbox tools. ## Metadata isolation Metadata is scoped to the resource and account. Do not use metadata to store secrets, passwords, private keys, or raw payment credentials. ## Partner data Some data must be shared with regulated partners for onboarding, screening, payment execution, settlement, and legal compliance. CashXChain shares only what is required for the relevant workflow. ## Data minimization Customers should send only necessary data and use structured fields rather than free-form notes where possible. --- # Vulnerability disclosure Source: https://docs.cashxchain.com/docs/security/disclosure Description: Responsible disclosure process for security researchers. # Vulnerability disclosure CashXChain values responsible security research. ## Report a vulnerability Send security reports to: ```text security@cashxchain.com ``` Include: - A clear description of the issue. - Steps to reproduce. - Impact assessment. - Affected endpoint or page. - Screenshots or logs if helpful. - Your contact information. ## Rules of engagement Do not: - Access, modify, or delete data that is not yours. - Test against real customer payment flows without authorization. - Perform denial-of-service testing. - Use social engineering. - Exfiltrate secrets or customer data. - Publicly disclose before CashXChain has reviewed the report. ## Safe testing Use sandbox whenever possible. If you believe a production issue exists, report it without exploiting it beyond what is necessary to demonstrate impact. ## Response CashXChain will acknowledge valid reports, investigate, prioritize remediation, and coordinate disclosure where appropriate. --- # Encryption Source: https://docs.cashxchain.com/docs/security/encryption Description: Encryption in transit, at rest, and key management expectations. # Encryption CashXChain protects sensitive data through encryption in transit, encryption at rest, access controls, and operational safeguards. ## In transit API requests and webhooks use HTTPS. Customers must use TLS-enabled endpoints for webhook delivery. ## At rest Sensitive platform data is encrypted at rest using cloud-native encryption and managed key controls where applicable. ## Secrets API keys, webhook signing secrets, partner credentials, and operational secrets must be stored in approved secret management systems. They must not be stored in source code, public logs, analytics tools, or client-side applications. ## Webhook signing Webhook payloads are signed so customers can verify authenticity and integrity. Always verify signatures before processing an event. ## Customer data Customers should minimize sensitive data sent in metadata fields. Required compliance or payment data should be provided through the correct structured fields. ## Key rotation CashXChain supports rotation of API keys and webhook secrets. Customers should rotate credentials regularly and after any suspected exposure. --- # Fraud prevention Source: https://docs.cashxchain.com/docs/security/fraud-prevention Description: Controls for payment fraud, account takeover, and suspicious activity. # Fraud prevention CashXChain combines account controls, partner checks, risk signals, and operational workflows to reduce fraud risk. ## Fraud risks Common risks in B2B payments include: - Account takeover. - Fake supplier or invoice fraud. - Beneficiary manipulation. - Social engineering. - Payment redirection. - Smurfing or transaction splitting. - High-risk corridors or counterparties. - Compromised API credentials. ## Platform controls CashXChain can support: - Beneficiary verification workflows. - Role-based access control. - Approval thresholds. - Payment review queues. - Velocity limits. - Corridor restrictions. - Audit logs. - Webhook alerts. ## Customer controls Customers should implement: - Multi-factor authentication. - Out-of-band beneficiary verification. - Dual approval for large payments. - API key secret management. - Monitoring for abnormal payment patterns. - Clear internal escalation paths. ## Risk scoring CashXChain may apply risk scoring based on account profile, beneficiary details, route, amount, frequency, geography, and partner screening outcomes. ## Suspicious activity Payments may move to `requires_action`, `screening`, `restricted`, or `failed` if risk signals require review or partner intervention. --- # Security overview Source: https://docs.cashxchain.com/docs/security/overview Description: CashXChain security principles and controls. # Security overview CashXChain is built for business-critical financial workflows. Security is designed across identity, API access, data handling, infrastructure, partner routing, and operational processes. ## Security principles - Least privilege access. - Strong environment separation. - Server-side secret handling. - Defense in depth. - Auditability by default. - Secure-by-design API workflows. - Zero-custody architecture target. - Partner governance for regulated execution. ## Customer responsibilities Customers are responsible for securing their own systems, API keys, webhook endpoints, user permissions, approval workflows, and downstream reconciliation processes. ## CashXChain responsibilities CashXChain is responsible for protecting the platform, API, dashboard, orchestration logic, audit records, and customer data under its control. ## Partner responsibilities Regulated partners are responsible for the services they provide, including custody, payment execution, settlement, screening, and local rail access where applicable. ## Security reviews Before production access, CashXChain may review your integration for: - API key storage. - Webhook signature verification. - Retry and idempotency handling. - Access controls. - Incident contacts. - Expected payment volume. - Compliance process alignment. ## Reporting security issues Report suspected vulnerabilities to the security contact listed in [Disclosure](./disclosure). Do not test against production accounts or real customer data without authorization. --- # AML Source: https://docs.cashxchain.com/docs/compliance/aml Description: Anti-money-laundering concepts and payment monitoring. # AML Anti-money-laundering controls help prevent misuse of payment infrastructure for illegal activity. ## CashXChain model CashXChain is designed as an orchestration layer that prepares payment instructions and compliance metadata. Regulated partners perform required AML/CFT checks, transaction monitoring, reporting, and execution obligations where applicable. ## AML data points Payment workflows may require: - Originator information. - Beneficiary information. - Purpose of payment. - Source of funds. - Invoice or contract references. - Counterparty country. - Payment amount and frequency. - Business activity. - Beneficial ownership information. ## Monitoring outcomes A payment may be: - Approved automatically. - Delayed for review. - Sent to `requires_action`. - Rejected before execution. - Returned or restricted after downstream review. ## Customer obligations Customers must not use CashXChain for prohibited activities. Customers are responsible for providing accurate information and maintaining appropriate controls in their own business. ## Auditability CashXChain records payment metadata, status transitions, and review states to support audit and reconciliation. --- # KYC and KYB Source: https://docs.cashxchain.com/docs/compliance/kyc-kyb Description: Business verification and customer due diligence in CashXChain. # KYC and KYB CashXChain supports business verification workflows required for compliant payment operations. ## KYB purpose Know Your Business verification helps confirm that a business exists, is authorized to use the platform, and is appropriate for the requested products, corridors, volumes, and risk profile. ## KYC purpose Know Your Customer checks may apply to directors, authorized representatives, beneficial owners, sole proprietors, contractors, or other individuals connected to an account. ## Data commonly required Requirements vary by jurisdiction and partner, but may include: - Legal name. - Registration number. - Registered address. - Business activity. - Website. - Expected transaction volume. - Ownership structure. - Beneficial owners. - Directors or controlling persons. - Government ID or proof of address for individuals. - Business registration documents. - Source of funds or source of wealth information. ## Partner role Regulated partners may collect, verify, review, and retain KYC/KYB data where required. CashXChain structures and routes the information needed for the workflow. ## Verification status | Status | Meaning | | --- | --- | | `not_started` | No verification workflow started. | | `pending` | Information submitted and under review. | | `requires_action` | More information or documents are required. | | `verified` | Account passed required verification. | | `rejected` | Account did not pass verification. | | `restricted` | Account has limited access. | ## Best practices - Collect complete data before attempting live payments. - Keep business descriptions specific and accurate. - Update ownership or control changes promptly. - Respond quickly to document requests. --- # Licensing model Source: https://docs.cashxchain.com/docs/compliance/licensing Description: CashXChain regulatory positioning and partner allocation. # Licensing model CashXChain is designed as a technology and orchestration layer. Regulated activities are performed by licensed partners where required. ## Functional separation CashXChain prepares instructions, validates technical requests, structures metadata, evaluates routes, maintains audit trails, and provides the API and dashboard experience. Partners provide regulated services such as: - Fiat account services. - Payment execution. - Payout processing. - Crypto-asset custody where applicable. - Stablecoin issuance or redemption. - AML/CFT and sanctions obligations. - Travel Rule obligations. ## Zero-custody principle CashXChain's target model avoids holding customer private keys, customer fiat, or customer crypto-assets. Customer funds remain in partner-controlled infrastructure where regulated execution occurs. ## Availability by jurisdiction Products, currencies, and payment methods may vary by jurisdiction. Some services may require additional agreements, verification, or partner approval. ## Important note This documentation is informational and does not constitute legal advice. Customers should consult their own counsel about regulatory obligations related to their use case. --- # Risk rating Source: https://docs.cashxchain.com/docs/compliance/risk-rating Description: How CashXChain uses risk tiers to guide payment controls. # Risk rating Risk rating helps determine whether an account, beneficiary, route, or payment can proceed automatically or requires additional review. ## Factors Risk may be influenced by: - Business type. - Industry. - Jurisdiction. - Expected and actual transaction volume. - Beneficial ownership structure. - Payment purpose. - Corridor. - Beneficiary type. - Historical activity. - Screening results. - Partner risk assessment. ## Risk tiers | Tier | Typical handling | | --- | --- | | Low | Standard limits and automated processing. | | Medium | Additional monitoring or lower limits. | | High | Enhanced due diligence, approvals, or restrictions. | | Prohibited | Not supported. | ## Dynamic changes Risk rating may change over time based on new documents, volume changes, ownership changes, new corridors, alerts, or partner feedback. ## Developer implications Your integration should handle: - `account.restricted` - `beneficiary.requires_action` - `payment.requires_action` - `payment.failed` - `document.required` Do not assume that a previously successful route will always remain available. --- # Screening Source: https://docs.cashxchain.com/docs/compliance/screening Description: Sanctions, PEP, adverse media, and counterparty screening concepts. # Screening Screening helps determine whether a customer, beneficial owner, beneficiary, wallet, bank account, or transaction requires review. ## Types of screening Depending on product and partner, screening can include: - Sanctions list screening. - PEP screening. - Adverse media checks. - Business registry checks. - Bank account validation. - Wallet or address risk checks where relevant. - Country and corridor restrictions. ## Screening timing Screening can occur during: - Account onboarding. - Beneficiary creation. - Payment creation. - Payment processing. - Periodic account review. - Changes to ownership or business activity. ## Outcomes | Outcome | Meaning | | --- | --- | | `clear` | No blocking issue found. | | `review` | Human or partner review required. | | `requires_action` | More information is needed. | | `blocked` | Workflow cannot continue. | ## Customer experience When screening requires action, CashXChain may request more information, documents, or clarification. Do not create duplicate payments to bypass review. --- # Travel Rule Source: https://docs.cashxchain.com/docs/compliance/travel-rule Description: Travel Rule metadata and partner obligations. # Travel Rule The Travel Rule requires certain information about originators and beneficiaries to accompany qualifying transfers, including some crypto-asset transfers. ## CashXChain role CashXChain structures and attaches required data fields to payment instructions where relevant. Regulated partners are responsible for collecting, verifying, transmitting, and enforcing Travel Rule obligations where they provide the regulated service. ## Typical data fields Depending on corridor and product, required data may include: - Originator name. - Originator account or customer identifier. - Originator address or country. - Beneficiary name. - Beneficiary account or wallet identifier. - Beneficiary address or country. - Transaction amount and asset. - Purpose or reference. ## When additional information is required A payment may move to `requires_action` if required originator or beneficiary information is missing, inconsistent, or rejected by a partner. ## Developer guidance - Use structured fields instead of free-form metadata. - Keep beneficiary records current. - Provide purpose of payment where required. - Handle `requires_action` events in your integration. - Do not submit placeholder information in production. --- # B2B cross-border payments Source: https://docs.cashxchain.com/docs/use-cases/b2b-cross-border Description: Use CashXChain for supplier, vendor, and international business payments. # B2B cross-border payments CashXChain helps businesses pay suppliers, vendors, contractors, and partners across borders with clearer pricing and faster operational workflows. ## Problem Traditional cross-border B2B payments often involve high FX spreads, correspondent bank fees, long settlement windows, manual reconciliation, and unpredictable compliance holds. ## CashXChain approach CashXChain provides a single workflow: 1. Create beneficiary. 2. Request quote. 3. Submit payment. 4. Track lifecycle. 5. Receive webhook updates. 6. Reconcile with statements. Behind the scenes, CashXChain selects appropriate rails and partners based on corridor, currency, amount, compliance requirements, and route availability. ## Example use cases - German importer paying suppliers in Asia. - European company paying a US software vendor. - Infrastructure company paying contractors in Africa. - SME paying multiple international invoices from one treasury workflow. ## Benefits - Transparent quote before execution. - Faster settlement where supported. - Unified audit trail. - API and dashboard workflows. - Reduced operational complexity. - Better visibility into status and exceptions. ## Integration pattern Use the Payments API with quote-driven FX and webhooks. Store the CashXChain payment ID in your ERP or accounting system. --- # Marketplace payouts Source: https://docs.cashxchain.com/docs/use-cases/marketplace-payouts Description: Use CashXChain to pay sellers, contractors, creators, or merchants. # Marketplace payouts Platforms can use CashXChain to orchestrate payouts to sellers, contractors, creators, suppliers, or merchants across currencies and countries. ## Platform account model A platform can operate a master account and connected accounts for participants. Each connected account may have its own onboarding, risk, beneficiary, and payout configuration. ## Payout workflow 1. Onboard the connected account or beneficiary. 2. Calculate payout amount in your platform. 3. Request FX quote if needed. 4. Submit payout batch or individual payment. 5. Listen for webhook updates. 6. Display status to the participant. 7. Reconcile fees and payout records. ## Batch payouts Batch payout workflows are useful for marketplaces that pay many participants at once. A batch can contain multiple payment instructions, each with its own status and exception handling. ## Compliance considerations Platforms must collect accurate participant data and show required terms or disclosures where applicable. Regulated partners may require additional KYC/KYB information based on geography, volume, and payout method. ## Best practices - Use connected account IDs consistently. - Do not combine unrelated participant funds without an approved structure. - Handle payout failures per recipient. - Provide clear status messages to participants. - Reconcile batch totals against individual payments. --- # Supply chain payments Source: https://docs.cashxchain.com/docs/use-cases/supply-chain Description: Use CashXChain to improve supplier settlement and working-capital operations. # Supply chain payments Supply chains depend on timely, reliable payment. Delays in cross-border settlement can delay production, shipping, subcontractor work, or inventory release. ## Challenges - Suppliers wait for funds before shipping goods. - Correspondent banking can take days. - FX cost is unclear until after execution. - Payment status is hard to track. - Manual reconciliation slows operations. ## CashXChain approach CashXChain gives supply-chain teams: - Quote visibility before payment. - Faster settlement options where supported. - Real-time payment status events. - References that match purchase orders and invoices. - Audit trails for finance and operations. - Partner-based local payout capabilities. ## Example workflow A manufacturer in Germany pays a hardware supplier in Hong Kong: 1. Supplier is created as beneficiary. 2. Treasury requests EUR -> HKD or EUR -> USD quote. 3. Payment is submitted with purchase order reference. 4. CashXChain routes through available rails and partners. 5. Supplier payment status is updated through webhooks. 6. Finance reconciles payment and fees from statements. ## Operational best practices - Verify suppliers before first payment. - Use purchase order references. - Require approvals for new beneficiaries. - Monitor payment status before shipment cut-offs. - Reconcile daily during high-volume import periods. --- # Treasury automation Source: https://docs.cashxchain.com/docs/use-cases/treasury-automation Description: Automate treasury transfers, FX, and liquidity operations with CashXChain. # Treasury automation CashXChain can support treasury teams that need faster movement of funds, better visibility, and programmable controls across entities, currencies, and payment rails. ## Common workflows - Move funds between operating balances. - Convert currencies through quote-based FX. - Pay suppliers from treasury wallets. - Reserve funds for payout batches. - Reconcile transactions across entities. - Monitor liquidity and settlement states. ## Controls Treasury workflows should use: - Role-based access. - Approval thresholds. - Account and wallet limits. - Audit trails. - Statement exports. - Webhook alerts for large balance changes. ## Liquidity visibility CashXChain exposes available, pending, reserved, and restricted balances so treasury teams can understand which funds are usable. ## Future capabilities CashXChain is designed to support more advanced automation over time, including liquidity forecasting, policy-based routing, and automated rebalancing through approved partners and rails. --- # Contact Source: https://docs.cashxchain.com/docs/legal/contact Description: Contact CashXChain for support, sales, legal, and security. # Contact For general information, visit: ```text https://www.cashxchain.com ``` ## Sales and partnerships ```text sales@cashxchain.com partnerships@cashxchain.com ``` ## Support ```text support@cashxchain.com ``` Include your account ID, environment, request ID, payment ID, and webhook event ID where relevant. ## Security ```text security@cashxchain.com ``` Use this address for vulnerability disclosure and security concerns. ## Legal and privacy ```text legal@cashxchain.com privacy@cashxchain.com ``` ## Company CashXChain operates through its relevant corporate entities and partner arrangements. Customer agreements specify the contracting entity and applicable terms. --- # Cookies Source: https://docs.cashxchain.com/docs/legal/cookies Description: Cookie and similar technology overview. # Cookies CashXChain websites and dashboards may use cookies or similar technologies for security, authentication, preferences, analytics, and product improvement. ## Cookie categories - Strictly necessary cookies: required for login, session security, routing, and core functionality. - Preference cookies: remember language, environment, or interface settings. - Analytics cookies: help understand documentation and product usage. - Security cookies: help detect abuse, fraud, or unauthorized access. ## Documentation site The public documentation site may use minimal cookies or analytics to understand content usage and improve developer experience. ## Managing cookies Browser settings can block or delete cookies. Some features may not work without necessary cookies. ## Production policy Final cookie notices and consent flows should be reviewed for compliance with applicable privacy and ePrivacy laws before production launch. --- # Partners Source: https://docs.cashxchain.com/docs/legal/partners Description: How CashXChain works with regulated and infrastructure partners. # Partners CashXChain works with regulated and infrastructure partners to provide payment, FX, settlement, onboarding, screening, and local rail capabilities. ## Partner categories - Banking and payout partners. - Stablecoin issuers and settlement providers. - On/off-ramp providers. - KYB/KYC and screening providers. - Cloud and infrastructure providers. - Security and audit providers. ## Why partners matter Cross-border payments require regulated capabilities across many jurisdictions. Partners help provide local accounts, payout access, compliance checks, custody where applicable, settlement execution, and scheme connectivity. ## Availability Partner availability can vary by country, currency, payment method, customer type, volume, and risk profile. CashXChain documentation may describe capabilities that require partner approval or production enablement. ## Responsibility allocation CashXChain orchestrates the technology workflow. Regulated partners perform regulated activities where required. Customer agreements and partner terms define the final legal responsibilities. ## Public partner references CashXChain may reference partners publicly only where approved. Some partner relationships, pilots, or evaluations may remain non-public until launch. --- # Privacy Source: https://docs.cashxchain.com/docs/legal/privacy Description: Privacy overview for CashXChain documentation. # Privacy CashXChain processes data required to provide payment orchestration, account management, compliance workflows, support, security, and reporting. ## Data categories Depending on your use case, data may include: - Business profile data. - User contact details. - Beneficial ownership data. - Identity verification data. - Beneficiary data. - Payment instructions. - Transaction metadata. - Device, log, and security data. - Support communications. ## Why data is processed Data is processed to: - Provide the platform and API. - Verify accounts and users. - Prepare payment instructions. - Route information to regulated partners. - Support compliance obligations. - Detect fraud and abuse. - Provide statements and audit trails. - Improve reliability and security. ## Partner sharing CashXChain may share required data with regulated partners, service providers, compliance vendors, infrastructure providers, and authorities where required by law or agreement. ## Data minimization Customers should provide accurate and necessary information through structured fields. Do not place sensitive secrets in metadata or free-form references. ## Rights and requests Privacy rights depend on applicable law and role. Contact CashXChain for privacy requests using the details in [Contact](./contact). ## Legal review This page is a documentation draft and must be aligned with the final privacy policy before production launch. --- # Risk notice Source: https://docs.cashxchain.com/docs/legal/risk-notice Description: Important risks related to cross-border payments, FX, partners, and settlement. # Risk notice Business payments involve operational, financial, regulatory, and technical risks. This page summarizes important considerations. ## Payment risk Payments may be delayed, rejected, returned, or restricted because of incorrect beneficiary information, partner review, banking cut-offs, sanctions screening, compliance checks, rail downtime, or local banking rules. ## FX risk FX rates can change. Quotes expire. Indicative quotes may differ from final execution pricing unless explicitly guaranteed. ## Partner risk Some services depend on regulated partners, banking providers, payout providers, on/off-ramp providers, screening providers, or settlement networks. Availability may change by jurisdiction, route, customer type, or partner status. ## Stablecoin and blockchain risk Where stablecoin or blockchain settlement is used in the background, risks can include network congestion, smart contract risk, issuer risk, redemption risk, regulatory changes, and settlement finality differences. ## Compliance risk Customers must provide accurate information and use CashXChain only for lawful purposes. Missing, false, or incomplete information can cause delays, restrictions, account closure, or reporting obligations. ## No investment advice CashXChain is payment infrastructure. Documentation does not provide investment, legal, tax, accounting, or financial advice. --- # Terms Source: https://docs.cashxchain.com/docs/legal/terms Description: Public terms overview for CashXChain documentation. # Terms This page provides a public-facing summary of terms concepts for CashXChain. Final customer terms are governed by the signed agreement between CashXChain, the customer, and any applicable regulated partners. ## Use of documentation The documentation is provided for informational purposes. It may describe planned, beta, sandbox, or production capabilities. Feature availability can vary by account, jurisdiction, partner, currency, route, and product approval. ## Use of services Customers must use CashXChain only for lawful business purposes and in compliance with applicable laws, agreements, partner terms, sanctions rules, AML requirements, and acceptable use policies. ## No prohibited activity CashXChain must not be used for fraud, money laundering, sanctions evasion, terrorist financing, illegal goods or services, unauthorized financial activity, or any activity prohibited by applicable law or partner policies. ## Partner services Some services are provided by regulated partners. Partner terms, onboarding requirements, and restrictions may apply. ## API use Customers are responsible for securing API keys, implementing idempotency, verifying webhooks, maintaining accurate data, and preventing unauthorized use of their integration. ## Changes CashXChain may update documentation, APIs, products, and availability over time. Breaking API changes will be communicated through changelog entries and customer notices where applicable. ## Legal review This page is not a substitute for legal terms. Production legal documents should be reviewed by counsel before publication. --- # Changelog Source: https://docs.cashxchain.com/docs/changelog Description: Product and documentation changelog. # Changelog This changelog tracks public documentation and API-facing product updates. ## 2026-05-08 ### Documentation - Rewrote the public documentation structure for CashXChain. - Added full introduction, product, platform, API, security, compliance, integration, use case, and legal pages. - Established CashXChain as a payment orchestration and technology layer with regulated partner execution. - Added future-state API examples for accounts, wallets, FX quotes, payments, webhooks, statements, and errors. - Added security, webhook, idempotency, reconciliation, and QA guidance. ### Notes - API examples are intended as product documentation targets and may evolve before production launch. - Legal pages are documentation drafts and require counsel review before publication. ## Future entries Future changelog entries should include: - API changes. - New supported corridors. - New webhook events. - New SDK releases. - Breaking changes. - Deprecation notices. - Security-related documentation updates. ---