# 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-06-08T15:33:21.051Z 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": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "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 FX runs against the sandbox pricing engine today; production availability is environment-gated. See the [FX API](../api/fx) for the full request/response and the persisted-quote execution flow. ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/fx/quotes \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from_currency": "EUR", "to_currency": "USD", "from_amount": "100000.00" }' ``` ## 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 Transfers are idempotent: each result carries an `idempotency_key`, so a retried request returns the original result instead of creating a duplicate. Create a transfer with `POST /v1/transfers`: ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/transfers \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": "25000.00", "currency": "EUR", "recipient": { "name": "Example Supplier Ltd", "email": "ap@supplier.example", "bank": { "bank_name": "Example Bank", "account_number": "DE89370400440532013000", "routing_number": "COBADEFFXXX", "country": "DE", "currency": "EUR" } }, "note": "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 { "quote_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "from_amount": "100000.00", "from_currency": "EUR", "to_amount": "108420.00", "to_currency": "USD", "rate": "1.0842", "fee": "1000.00", "fee_currency": "EUR", "expires_at": "2026-06-01T09:00:30Z" } ``` The single `fee` consolidates the components above (CashXChain fee, FX spread, and any partner cost) for the quoted route. ## 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, and sub-entities in CashXChain. API reference for account creation and management. # Accounts An account is the main container for identity, permissions, balances, payment history, and compliance status. The `accounts` resource is the canonical entity returned by the API; it maps to the underlying `customers` table with enriched fields. --- ## Account object ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "tenant_id": null, "contact_email": "ops@acme.com", "display_name": "Acme Corp", "country_code": "US", "kyb_status": "active", "api_tier": "direct", "metadata": {}, "parent_platform_account_id": null, "created_at": "2026-06-08T00:00:00Z", "updated_at": "2026-06-08T00:00:00Z" } ``` | Field | Type | Description | |---|---|---| | `id` | uuid | Account UUID. | | `tenant_id` | uuid \| null | Tenant the account belongs to. | | `contact_email` | string | Primary contact email. | | `display_name` | string | Human-readable account name. | | `country_code` | string | ISO 3166-1 alpha-2 country code. | | `kyb_status` | string | `pending`, `active`, or `rejected`. | | `api_tier` | string | `direct` or `platform_ready`. | | `metadata` | object | Caller-defined key-value pairs. | | `parent_platform_account_id` | uuid \| null | Set when this is a managed sub-account. | --- ## POST /v1/accounts — Create account Creates a new account. No authentication required for basic creation. For platform flows, pass `?acting_as=` to create a managed sub-account. Requires a JWT with `api_tier=platform_ready`. ```http POST /v1/accounts Content-Type: application/json Idempotency-Key: account-acme-001 ``` ```json { "contact_email": "ops@acme.com", "display_name": "Acme Corp", "country_code": "US", "metadata": { "erp_id": "ACC-1042" } } ``` #### Platform sub-account creation ```http POST /v1/accounts?acting_as= Authorization: Bearer Content-Type: application/json Idempotency-Key: subaccount-merchant-001 ``` This creates a managed account linked to the platform. The link is stored as a `platform_permissions` row. #### Response (201 Created) ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "contact_email": "ops@acme.com", "display_name": "Acme Corp", "country_code": "US", "kyb_status": "pending", "api_tier": "direct", "metadata": { "erp_id": "ACC-1042" }, "created_at": "2026-06-08T00:00:00Z", "updated_at": "2026-06-08T00:00:00Z" } ``` --- ## GET /v1/accounts/me — Caller's account Returns the account associated with the calling credential. **Auth:** Elevated — JWT (`aud=internal` or `aud=admin`) or master key only. ```http GET /v1/accounts/me Authorization: Bearer ``` --- ## GET /v1/accounts/me/balance — Balance Returns the caller's balance breakdown by currency. **Auth:** Elevated — JWT or master key only. ```http GET /v1/accounts/me/balance Authorization: Bearer ``` #### Response (200 OK) ```json { "totals": [ { "currency": "USD", "amount": "1000.00", "available": "1000.00", "pending": "0.00" }, { "currency": "USDC", "amount": "50.00", "available": "50.00", "pending": "0.00" } ] } ``` --- ## GET /v1/accounts/me/vibans — Virtual IBANs Returns the caller's virtual IBANs with bank routing details. **Auth:** Elevated — JWT or master key only. ```http GET /v1/accounts/me/vibans Authorization: Bearer ``` --- ## GET /v1/accounts — List accounts Lists accounts visible to the caller. Supports filtering by `tenant_id` or `managed_by` (platform accounts only). **Auth:** Elevated — JWT or master key only. ```http GET /v1/accounts?limit=50&offset=0 Authorization: Bearer ``` Query parameters: | Param | Type | Description | |---|---|---| | `tenant_id` | uuid | Filter by tenant. | | `managed_by` | uuid | List managed sub-accounts for a platform account. | | `limit` | integer | Max rows (default 50). | | `offset` | integer | Pagination offset. | --- ## GET /v1/accounts/\{id\} — Get account Retrieve a single account by UUID. **Auth:** Elevated — JWT or master key only. ```http GET /v1/accounts/3fa85f64-5717-4562-b3fc-2c963f66afa6 Authorization: Bearer ``` --- ## Account KYB status | Status | Meaning | |---|---| | `pending` | Account created but KYB verification not yet complete. | | `active` | KYB verified — account can transact. | | `rejected` | KYB rejected — account cannot transact. | Accounts with `kyb_status != active` cannot initiate payments. The `api_tier` claim on the JWT controls whether an account can create managed sub-accounts. --- ## API tier | Value | Meaning | |---|---| | `direct` | Single-account flows only. | | `platform_ready` | Can create and manage sub-accounts via `?acting_as=`. | Platform tier is granted by CashXChain after your platform integration is approved. --- ## Account types | Type | Description | |---|---| | Business account | A company using CashXChain directly. | | Platform account | A platform embedding CashXChain for its customers. Requires `api_tier=platform_ready`. | | Managed sub-account | A customer account created by a platform via `?acting_as=`. Has a `parent_platform_account_id`. | --- # API keys Source: https://docs.cashxchain.com/docs/platform/api-keys Description: Create, scope, rotate, and protect CashXChain API keys. Includes master key (platform key) reference. # API keys API keys authenticate server-side requests to the CashXChain API. Keys are environment-scoped and type-gated — the type determines what operations the key may perform. --- ## Key types ### Secret key (`sk_`) The default all-purpose server-side key. Suitable for backend integrations where you fully control the runtime environment. - Full read + write access to all `/v1/*` routes. - Scope array is accepted at creation but ignored at runtime — a `sk_` key always passes scope checks. - Cannot access dashboard (`/internal/*`) routes. ### Publishable key (`pk_`) A read-only key safe to embed in front-end or mobile applications. - `GET`, `HEAD`, and `OPTIONS` requests only — any write method (`POST`, `PUT`, `DELETE`, `PATCH`) returns `403 Forbidden`. - Write scopes are stripped silently at creation even if submitted. - Cannot access dashboard routes. ### Restricted key (`rk_`) A scoped key for least-privilege integrations. Only routes matching the declared scopes are accessible. - Read and/or write access, limited to scopes declared at creation. - A handler requiring `payments:write` returns `403` if that scope is absent from the key. - Cannot access dashboard routes. ### Master key (`mk_`) — Platform / operations The highest-privilege credential. Not a developer key — a platform operations credential. - Full access to all `/v1/*` and `/internal/*` (dashboard) routes. - Bypasses all scope checks. - **Cannot be created via the API.** Provisioned only by running the admin seed script with direct database access. - **Cannot be revoked via the API.** Revocation requires direct database intervention. - Stored in a separate `master_keys` table; the `api_keys` table is never touched. > Use master keys only for internal dashboards, ops tooling, and platform-level automation. Never distribute them to third-party integrations — issue a `sk_` or `rk_` key instead. --- ## Environments Keys are environment-scoped and will be rejected if used against the wrong environment. | Environment | Prefix | |---|---| | Sandbox | `sk_sandbox_` / `pk_sandbox_` / `rk_sandbox_` / `mk_sandbox_` | | Production | `sk_live_` / `pk_live_` / `rk_live_` / `mk_live_` | Never use production keys in local development. Never commit keys to source control. --- ## Key format ``` {prefix}{64 hex characters} ``` Total length: 75 characters. The 64-character random suffix provides 256 bits of entropy. Only the SHA-256 hash of the full key is stored — the plain-text token is shown **once** at creation and is never recoverable. --- ## Creating a key Requires a valid bearer credential (JWT or existing API key). ```http POST /v1/api-keys Authorization: Bearer Content-Type: application/json Idempotency-Key: ``` ### Secret key ```json { "name": "Backend production", "type": "secret" } ``` ### Publishable key ```json { "name": "Dashboard read-only", "type": "publishable" } ``` ### Restricted key ```json { "name": "Payments service", "type": "restricted", "scopes": ["payments:read", "payments:write"] } ``` ### Response (201 Created) ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "object": "api_key", "name": "Backend production", "token": "sk_sandbox_ab12cd34ef56gh78...", "prefix": "sk_sandbox_ab12cd34", "last4": "a1b2", "type": "secret", "scopes": [], "created_at": "2026-06-08T00:00:00Z" } ``` > **Copy the `token` field immediately.** It is not stored and cannot be retrieved after this response. --- ## Available scopes Request only the scopes your integration needs. | Scope | Grants | |---|---| | `transfers:read` | List and retrieve transfers | | `transfers:write` | Create transfers | | `transactions:read` | List and retrieve transactions | | `contacts:read` | List contacts / payment beneficiaries | | `payments:read` | List and retrieve payments | | `payments:write` | Create payments (add-funds, send, FX execute) | | `fx:read` | Create persisted FX quotes | | `api_keys:read` | List API keys | | `api_keys:write` | Create and revoke API keys | | `request_logs:read` | Access request logs | | `usage:read` | Access usage analytics | `sk_` and `mk_` keys bypass all scope checks. Scopes only gate `pk_` and `rk_` keys. --- ## Listing keys ```http GET /v1/api-keys Authorization: Bearer ``` Returns an array of key objects. The `token` field is never included in list responses — only `prefix` and `last4` are returned for masked display. --- ## Revoking a key ```http DELETE /v1/api-keys/{id} Authorization: Bearer ``` Returns `204 No Content`. Revocation is immediate and permanent — the key hash is retained in the database for audit purposes but cannot be used for authentication. --- ## Key rotation Rotate keys regularly and immediately after any suspected exposure. Recommended rotation process: 1. Create a new key with the same type and scopes. 2. Deploy the new key to your secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, etc.). 3. Confirm successful API calls using the new key. 4. Revoke the old key via `DELETE /v1/api-keys/{id}`. 5. Review `GET /v1/request-logs` for unexpected usage of the old key. --- ## Security requirements - Store keys only in server-side secret storage — never in environment variable files committed to git. - Do not log or print key values in application code or CI pipelines. - Do not expose `sk_` or `rk_` keys in browser JavaScript or mobile apps — use `pk_` for client-side reads. - Revoke unused or rotated keys promptly. - Monitor `GET /v1/request-logs` for unexpected authentication failures. --- ## Compromised keys If you suspect a key has been exposed: 1. Revoke it immediately via `DELETE /v1/api-keys/{id}`. 2. Rotate all dependent services to a new key. 3. If a production payment-capable key (`sk_live_` or `rk_live_` with `payments:write`) was exposed, contact [support@cashxchain.com](mailto:support@cashxchain.com). --- # 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. ## Two quote styles **Stateless quote** (`POST /v1/fx/quotes`) is indicative — useful for display: ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "from_currency": "EUR", "from_amount": "100000.00", "to_currency": "USD", "to_amount": "108420.00", "rate": "1.0842", "spread_bps": 25, "source": "sandbox-static", "issued_at": "2026-06-01T09:00:00Z", "expires_at": "2026-06-01T09:15:00Z" } ``` **Persisted quote** (`POST /v1/fx/quote`) returns a `quote_id` you lock and then execute with `POST /v1/fx/execute` before it expires (~30s): ```json { "quote_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "from_currency": "EUR", "from_amount": "100000.00", "to_currency": "USD", "to_amount": "108420.00", "rate": "1.0842", "fee": "120.00", "fee_currency": "EUR", "expires_at": "2026-06-01T09:00:30Z", "expires_in_seconds": 30 } ``` A persisted quote is short-lived: once `expires_in_seconds` elapses it can no longer be executed and you must request a new one. See the [FX API](../api/fx) for the full request/response and execution flow. ## Amount direction Quotes are requested by `from_amount` (the amount you sell). The engine returns the resulting `to_amount` for the target currency. ## 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. | | Contact | A saved beneficiary — a bank account, CashXChain user, or crypto wallet (`/v1/contacts`). | | FX quote | A priced conversion proposal (`/v1/fx/quote`). | | Transfer | An instruction to move value (`/v1/transfers`). | | Transaction | A ledger record of a transfer (`/v1/transactions`). | | Account & balances | Account profile and per-currency balances (`/v1/accounts/me`). | | Statement | A reconciliation export for a period. | | Wallet | A logical balance container — planned API; balances are exposed via accounts today. | | Webhook endpoint | A URL that receives event notifications — planned; today via the event stream. | ## Typical implementation path 1. Create or access a business account. 2. Complete KYB and risk review. 3. Generate sandbox API keys. 4. Create a contact (beneficiary). 5. Request an FX quote. 6. Create a transfer (optionally executing a locked FX quote). 7. Track transactions and (planned) receive webhook events. 8. Reconcile with statements and transaction 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. :::note API shapes This page describes the normalized, business-facing model. For the exact request/response shapes available today, see the [Payments API](../api/payments) — money movement is created with `POST /v1/transfers` and read back as transactions (`GET /v1/transactions`) and payments (`GET /v1/payments`). ::: ## Payment object (normalized model) A normalized payment record includes, depending on route: - `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 recipient/contact is usable. 3. Request and (if needed) lock an FX quote. 4. Create the transfer (`POST /v1/transfers`). 5. Track the resulting transaction status. 6. Handle `executing`, `failed`, `rolled_back`, and `completed` states. 7. Reconcile with transactions and 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 & vIBANs Source: https://docs.cashxchain.com/docs/platform/wallets Description: Balance containers, virtual IBANs, and crypto wallet management via the CashXChain API. # Wallets & vIBANs CashXChain uses a wallet abstraction to present balances without requiring end users to manage private keys or understand blockchain infrastructure. A wallet in the API is a logical balance container scoped to a customer and currency. --- ## Balance model | Balance type | Meaning | |---|---| | `available` | Funds immediately usable for payments. | | `pending` | Funds expected but not yet final (incoming transfers in transit). | | `reserved` | Funds held for pending outbound payments, fee reserves, or FX quote locks. | | `restricted` | Funds that cannot move — compliance hold, account restriction, or partner limitation. | --- ## GET /v1/accounts/me/balance Returns the caller's balance breakdown across all currencies. **Auth:** Elevated — JWT or master key only. ```http GET /v1/accounts/me/balance Authorization: Bearer ``` ```json { "totals": [ { "currency": "USD", "amount": "1000.00", "available": "1000.00", "pending": "0.00" }, { "currency": "USDC", "amount": "50.00", "available": "50.00", "pending": "0.00" } ] } ``` --- ## Virtual IBANs (vIBANs) A vIBAN is a dedicated bank account number issued to a customer by a payment partner (e.g. Veem). Customers can receive fiat wire transfers to their vIBAN, which credits their CashXChain balance. vIBANs carry full bank routing metadata: IBAN number, BIC/SWIFT, sort codes, or ACH routing numbers depending on the currency and jurisdiction. --- ## POST /v1/customers/\{id\}/vibans — Create vIBAN Provisions a vIBAN for a customer via a specified partner. The backend submits the application and polls the partner until the vIBAN is approved (up to 10 attempts with 500ms backoff). **Auth:** Elevated — JWT or master key only. **Header:** `Idempotency-Key: ` — required. ```http POST /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/vibans Authorization: Bearer Content-Type: application/json Idempotency-Key: viban-usd-2026-001 ``` ```json { "partner": "veem", "currency": "USD", "display_name": "USD Receiving Account" } ``` If the partner has not finished provisioning within the polling window, the API returns `202 Accepted` with an `application_id`. Poll `GET /v1/customers/:id/vibans` to check status. --- ## GET /v1/customers/\{id\}/vibans — List vIBANs Lists all vIBANs provisioned for a customer. **Auth:** Elevated — JWT or master key only. ```http GET /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/vibans Authorization: Bearer ``` --- ## GET /v1/customers/\{id\}/vibans/\{viban_id\} — Get vIBAN Returns full detail for a single vIBAN including bank routing numbers. **Auth:** Elevated — JWT or master key only. ```http GET /v1/customers/:id/vibans/:viban_id Authorization: Bearer ``` --- ## GET /v1/customers/\{id\}/vibans/\{viban_id\}/balance — vIBAN balance Returns the balance held at the partner for this specific vIBAN. **Auth:** Elevated — JWT or master key only. --- ## GET /v1/customers/\{id\}/vibans/\{viban_id\}/transactions — vIBAN transactions Returns the transaction history for a vIBAN. **Auth:** Elevated — JWT or master key only. --- ## GET /v1/customers/\{id\}/wallet — Crypto wallet Returns the customer's crypto wallet information (Solana address, Coinbase CDP link). **Auth:** Elevated — JWT or master key only. ```http GET /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/wallet Authorization: Bearer ``` --- ## GET /v1/accounts/me/vibans — Caller's vIBANs Shortcut to list all vIBANs for the account associated with the calling credential. **Auth:** Elevated — JWT or master key only. --- ## Sandbox faucet In sandbox, use the faucet to credit test balances: ```http POST /v1/sandbox/faucet Authorization: Bearer Content-Type: application/json ``` ```json { "currency": "USD", "amount": "10000.00" } ``` The faucet is only available when `APP_ENV=sandbox` and requires a valid JWT. --- ## Crypto rails USDC and EURC transfers route via Coinbase CDP on Solana. Before sending USDC/EURC: 1. Ensure the sender has a Solana wallet provisioned (`GET /v1/customers/:id/wallet`). 2. Validate the recipient address: `GET /v1/utility/validate-address?address=&chain=solana&asset=USDC`. 3. If `ata_exists=false`, the first transfer will create the recipient's token account — the ~0.002 SOL rent is deducted from the transaction. --- # 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. :::caution Planned Customer-managed webhook endpoints are on the roadmap and **not yet available**. Today, events are exposed as a server-sent event (SSE) stream from the dashboard session (`GET /v1/notifications`). The signed-POST model below is the planned contract — see the [Webhooks API](../api/webhooks). ::: ## 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": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "transfer.completed", "created_at": "2026-06-01T09:00:42Z", "environment": "sandbox", "resource_type": "transfer", "resource_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "completed" } } ``` ## Signature headers Signed delivery will include a timestamp and an HMAC signature over the raw request body, which you must verify before trusting the payload. The exact header names are being finalized and will be published with the endpoint. ## 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. ## Planned event types Aligned to the transfer/payment lifecycle: - `transfer.pending` - `transfer.executing` - `transfer.completed` - `transfer.failed` - `transfer.rolled_back` - `payment.sent` - `payment.completed` - `payment.failed` - `balance.updated` ## 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: How to authenticate requests to the CashXChain API. # Authentication All API requests must include an `Authorization` header with a bearer token. ```http Authorization: Bearer sk_sandbox_... ``` --- ## API key types CashXChain issues three types of API keys. Each has a distinct prefix and a different permission level. ### Secret key — `sk_` The standard server-side key. Use it for all backend integrations. - Full read and write access to all `/v1/*` routes. - Never expose in client-side code, mobile apps, or public repositories. ### Publishable key — `pk_` A read-only key safe for use in front-end or mobile environments. - Read access only (`GET` requests). Any write request returns `403 Forbidden`. - Suitable for displaying balances, transaction history, or FX rates in a UI. ### Restricted key — `rk_` A scoped key for least-privilege integrations. - Access limited to the specific scopes declared when the key was created. - Use when issuing keys to services that only need a subset of your API access. ### Master key / Platform key — `mk_` A master key provides unrestricted access to all API routes, including platform-level and dashboard endpoints not reachable by standard API keys. It is intended for platforms and operators building on top of CashXChain infrastructure. Master keys are not self-serve. To request one, contact [support@cashxchain.com](mailto:support@cashxchain.com) with your use case. CashXChain provisions the key directly to your account. --- ## Environments | Environment | Key prefix | |---|---| | Sandbox | `sk_sandbox_`, `pk_sandbox_`, `rk_sandbox_`, `mk_sandbox_` | | Production | `sk_live_`, `pk_live_`, `rk_live_`, `mk_live_` | Never use production keys in local development or non-production environments. --- ## Scopes Scopes apply to restricted keys only. Secret keys have full access regardless of the scope list. | Scope | Access granted | |---|---| | `transfers:read` | List and retrieve transfers | | `transfers:write` | Create transfers | | `transactions:read` | List and retrieve transactions | | `contacts:read` | List contacts | | `payments:read` | List and retrieve payments | | `payments:write` | Create payments and execute FX conversions | | `fx:read` | Create persisted FX quotes | | `api_keys:read` | List API keys | | `api_keys:write` | Create and revoke API keys | | `request_logs:read` | Access request logs | | `usage:read` | Access usage analytics | Request only the scopes your integration needs. Scopes are declared at key creation and cannot be changed afterwards — create a new key if you need different scopes. --- ## Creating a key ```http POST /v1/api-keys Authorization: Bearer Content-Type: application/json Idempotency-Key: ``` **Secret key:** ```json { "name": "Backend service", "type": "secret" } ``` **Restricted key:** ```json { "name": "Payments service", "type": "restricted", "scopes": ["payments:read", "payments:write"] } ``` **Publishable key:** ```json { "name": "Dashboard read-only", "type": "publishable" } ``` The response includes a `token` field with the full key value. This is shown **once only** — copy it immediately and store it in a secret manager. It cannot be retrieved again. --- ## Key rotation 1. Create a new key with the same type and scopes. 2. Deploy the new key to your environment. 3. Confirm API calls succeed with the new key. 4. Revoke the old key: `DELETE /v1/api-keys/{id}`. 5. Check `GET /v1/request-logs` for any unexpected usage of the old key. --- ## Authentication errors | Status | Code | Meaning | |---|---|---| | 401 | `authentication_required` | No `Authorization` header provided. | | 401 | `invalid_api_key` | Key not found or revoked. | | 403 | `insufficient_scope` | Restricted key is missing the required scope. | | 403 | `publishable_key_write_denied` | Publishable key attempted a write request. | | 403 | `environment_mismatch` | Key environment does not match the API base URL. | --- ## Security checklist - Store keys in a secret manager — not in environment files committed to source control. - Do not log or print key values in application code or CI pipelines. - Use the most restrictive key type that satisfies your use case. - Rotate keys regularly and immediately after any suspected exposure. - Revoke keys that are no longer in use. --- # Errors Source: https://docs.cashxchain.com/docs/api/errors Description: CashXChain API error structure, HTTP status codes, and all error codes. # Errors CashXChain uses standard HTTP status codes and a consistent structured JSON error response across all endpoints. --- ## Error format All errors return the same top-level shape: ```json { "success": false, "error": "insufficient_scope", "message": "api key missing required scope: payments:write", "details": "scope: payments:write" } ``` | Field | Type | Description | |---|---|---| | `success` | `false` | Always `false` on error responses. | | `error` | `string` | Stable machine-readable code. Safe to match programmatically. | | `message` | `string` | Human-readable description. Do not parse — may change. | | `details` | `string` \| `null` | Optional extra context (e.g. field name, resource ID). | --- ## HTTP status codes | Status | Meaning | |---|---| | `400 Bad Request` | Request body or parameters are invalid. | | `401 Unauthorized` | Authentication failed — missing, invalid, or expired credential. | | `403 Forbidden` | Credential valid but insufficient permissions for this operation. | | `404 Not Found` | Resource does not exist or is not accessible to the caller. | | `409 Conflict` | Duplicate resource or invalid state transition. | | `422 Unprocessable Entity` | Request is valid JSON but semantically cannot be processed. | | `429 Too Many Requests` | Rate limit exceeded. | | `500 Internal Server Error` | Unexpected server error. | | `503 Service Unavailable` | Backend or downstream partner temporarily unavailable. | --- ## Authentication and authorization errors | Code | HTTP | Meaning | |---|---|---| | `authentication_required` | 401 | No `Authorization` header and route requires authentication. | | `invalid_api_key` | 401 | Key not found, revoked, or hash does not match. Identical response for non-existent and revoked keys to prevent enumeration. | | `token_expired` | 401 | JWT `exp` claim has passed. | | `invalid_token` | 401 | JWT signature invalid, malformed, or algorithm mismatch. | | `insufficient_scope` | 403 | Restricted key does not have the required scope for this operation. | | `publishable_key_write_denied` | 403 | Publishable key (`pk_`) attempted a write method. | | `dashboard_access_denied` | 403 | Regular API key (`sk_`/`pk_`/`rk_`) attempted a dashboard route that requires JWT or master key. | | `environment_mismatch` | 403 | Key prefix environment (`sandbox`/`live`) does not match the API base URL. | --- ## Resource errors | Code | HTTP | Meaning | |---|---|---| | `resource_not_found` | 404 | Resource does not exist or is not accessible to the calling account. | | `payment_not_found` | 404 | Payment UUID not found. | | `transfer_not_found` | 404 | Transfer UUID not found. | | `quote_not_found` | 404 | FX quote UUID not found or expired. | --- ## Payment and transfer errors | Code | HTTP | Meaning | |---|---|---| | `insufficient_funds` | 422 | Sender balance is below the requested transfer amount. | | `sender_no_coinbase_wallet` | 422 | Sender attempted a USDC/EURC transfer but has no Solana wallet provisioned. | | `recipient_not_found` | 422 | Recipient email is not registered on CashXChain. | | `phantom_recipient` | 422 | Recipient account exists but has no partner links (no wallet or bank provisioned). | | `external_send_blocked` | 400 | External bank send rejected in sandbox — bank details do not match a registered sandbox user. | | `invalid_currency` | 400 | Currency code is not supported by the selected partner. | | `invalid_partner` | 400 | Partner slug is not recognised or not enabled for this environment. | | `customer_not_linked` | 400 | Customer is not enrolled with the specified partner. | --- ## FX errors | Code | HTTP | Meaning | |---|---|---| | `quote_expired` | 422 | FX quote TTL has passed (30-second window). | | `quote_already_consumed` | 409 | FX quote has already been executed. | | `unsupported_pair` | 400 | No rate available for the requested currency pair. Sandbox supports: USD/EUR, USD/GBP, EUR/GBP and inverses. | | `corridor_unavailable` | 503 | Currency or country corridor is not currently enabled. | --- ## Idempotency errors | Code | HTTP | Meaning | |---|---|---| | `idempotency_key_missing` | 400 | Write route requires an `Idempotency-Key` header but none was provided. | | `idempotency_conflict` | 409 | The same `Idempotency-Key` was used with a different request body. | --- ## Account and compliance errors | Code | HTTP | Meaning | |---|---|---| | `account_not_active` | 403 | Account KYB status is not `active` — cannot transact. | | `requires_action` | 403 | Additional information or approval is required before this operation can proceed. | | `cross_account_access_denied` | 403 | Non-admin caller attempted to access a resource belonging to another account. | --- ## Partner errors | Code | HTTP | Meaning | |---|---|---| | `partner_unavailable` | 503 | Downstream payment partner is temporarily unavailable. Retry with exponential backoff. | | `partner_error` | 502 | Partner returned an unexpected error. The operation may or may not have been processed — check `GET /v1/payments/{id}` or `GET /v1/transfers/{id}`. | --- ## Validation errors | Code | HTTP | Meaning | |---|---|---| | `invalid_request` | 400 | Request body or query parameters are missing required fields, wrong types, or failed validation rules. | | `invalid_country_code` | 400 | `country_code` is not a valid ISO 3166-1 alpha-2 code. | | `invalid_currency` | 400 | `currency` is not a valid ISO 4217 code or is not supported on this route. | | `invalid_key_type` | 400 | `type` must be `secret`, `publishable`, or `restricted`. | --- ## Rate limit errors | Code | HTTP | Meaning | |---|---|---| | `rate_limit_exceeded` | 429 | Too many requests. Retry after the duration indicated in the `Retry-After` response header. | --- ## Debugging All requests are automatically logged. Reference a request by its log ID when contacting support: ```http GET /v1/request-logs/{id} ``` This returns the full request and response body for that request. List recent logs with: ```http GET /v1/request-logs?limit=100 ``` --- ## Safe retries All write routes are idempotent when an `Idempotency-Key` header is supplied. Repeating the same key with the same body returns the cached response without re-executing the operation — safe on network errors, timeouts, and 5xx responses. Do not retry on `400`, `401`, `403`, or `409` — these indicate a client-side error that will not resolve on retry. --- # FX Source: https://docs.cashxchain.com/docs/api/fx Description: Foreign exchange quotes and execution via the CashXChain API. # FX CashXChain provides two FX surfaces: - **Public stateless quote** (`POST /v1/fx/quotes`) — no auth, no persistence, suitable for price discovery. - **Persisted quote + execute** (`POST /v1/fx/quote` → `POST /v1/fx/execute`) — locked rate with a 30-second TTL. Sandbox only for now. --- ## POST /v1/fx/quotes — Public stateless quote No authentication required. Returns an indicative rate for display purposes. The quote is not persisted and cannot be executed. ```http POST /v1/fx/quotes Content-Type: application/json ``` ```json { "from_currency": "EUR", "to_currency": "USD", "from_amount": "1000.00" } ``` ### Response (200 OK) ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "from_currency": "EUR", "to_currency": "USD", "from_amount": "1000.00", "to_amount": "1082.50", "rate": "1.0825", "spread_bps": 50, "source": "ecb", "issued_at": "2026-06-08T12:00:00Z", "expires_at": "2026-06-08T12:05:00Z" } ``` Supported pairs (sandbox): USD/EUR, USD/GBP, EUR/GBP, and their inverses. --- ## POST /v1/fx/quote — Persisted quote Creates a rate-locked quote valid for 30 seconds. Returns a `quote_id` that must be passed to `/v1/fx/execute` to settle the conversion. **Auth:** Any valid credential. Scope required for `rk_` keys: `fx:read`. **Availability:** Sandbox only. Returns 404 in production until a live FX provider is integrated. ```http POST /v1/fx/quote Authorization: Bearer Content-Type: application/json ``` ```json { "from_currency": "USD", "to_currency": "EUR", "from_amount": "500.00" } ``` ### Response (201 Created) ```json { "quote_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "from_currency": "USD", "from_amount": "500.00", "to_currency": "EUR", "to_amount": "462.15", "rate": "0.9243", "fee": "2.50", "fee_currency": "USD", "expires_at": "2026-06-08T12:00:30Z", "expires_in_seconds": 30 } ``` > The quote TTL is 30 seconds. After expiry, executing the quote returns `422 quote_expired`. --- ## POST /v1/fx/execute — Execute a quote Atomically settles the FX conversion: debits the source-side balance, credits the destination-side balance, persists a `transfers` row with `transfer_type = 'fx_conversion'`, and marks the quote consumed. All steps run in a single database transaction. **Auth:** Any valid credential. Scope required for `rk_` keys: `payments:write`. **Availability:** Sandbox only. ```http POST /v1/fx/execute Authorization: Bearer Content-Type: application/json ``` ```json { "quote_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` ### Response (200 OK) ```json { "transfer_id": "...", "status": "completed", "from_currency": "USD", "from_amount": "500.00", "to_currency": "EUR", "to_amount": "462.15", "rate": "0.9243", "fee": "2.50" } ``` --- ## Quote + execute flow ``` POST /v1/fx/quote → receive quote_id, rate, expires_in_seconds | | (must execute within 30 seconds) | POST /v1/fx/execute → atomic balance swap + transfers row ``` A quote can only be executed once. Executing an already-consumed quote returns `409 quote_already_consumed`. Executing an expired quote returns `422 quote_expired`. --- ## Sandbox rates Rates in the sandbox are hardcoded for deterministic testing. They do not reflect live market rates. | Pair | Rate (approximate) | |---|---| | USD to EUR | 0.924 | | EUR to USD | 1.082 | | USD to GBP | 0.792 | | GBP to USD | 1.263 | | EUR to GBP | 0.858 | | GBP to EUR | 1.166 | Spread: 50 bps. Fee: 0.5% of the `from_amount`. --- ## Error codes | Code | HTTP | Meaning | |---|---|---| | `unsupported_pair` | 400 | No rate available for the requested currency pair. | | `quote_expired` | 422 | Quote TTL has passed. | | `quote_already_consumed` | 409 | Quote has already been executed. | | `quote_not_found` | 404 | Quote UUID not found. | --- # Getting started Source: https://docs.cashxchain.com/docs/api/getting-started Description: Make your first CashXChain API request in five minutes. # Getting started The CashXChain API is a REST API. All requests use JSON bodies and `Authorization: Bearer ` headers. This guide walks from zero to a working end-to-end payment. --- ## Base URLs ``` Sandbox: https://api.sandbox.cashxchain.com Production: https://api.cashxchain.com ``` All route paths are prefixed with `/v1`. Use sandbox for all development — it mirrors production behaviour with deterministic mock partners and a faucet for adding test funds. --- ## Step 1 — Get an API key Contact [support@cashxchain.com](mailto:support@cashxchain.com) or sign up at [cashxchain.com](https://cashxchain.com) to get sandbox access. Once your account is provisioned, create an API key from the developer dashboard. Your sandbox API key starts with `sk_sandbox_`. Store it securely — it is shown only once at creation. ```bash export CXC_API_KEY=sk_sandbox_... ``` See [API keys](../platform/api-keys) for key types and scopes. --- ## Step 2 — Verify the key works A quick read against transaction history confirms the key is valid: ```bash curl https://api.sandbox.cashxchain.com/v1/transactions \ -H "Authorization: Bearer $CXC_API_KEY" ``` A `200` with an empty array means the key works and the account is reachable. A `401` means the key is invalid or revoked. --- ## Step 3 — Create a customer Customers represent your end-users or businesses. Idempotent on email: ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/customers \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: customer-acme-001" \ -d '{ "email": "ap@acme.com", "business_name": "Acme Corp", "country_code": "US" }' ``` Note the `id` from the response — you will use it as `customer_id` in payment calls. --- ## Step 4 — Get an FX quote (optional) The public FX endpoint requires no authentication: ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/fx/quotes \ -H "Content-Type: application/json" \ -d '{ "from_currency": "EUR", "to_currency": "USD", "from_amount": "1000.00" }' ``` The response includes `rate`, `to_amount`, and `expires_at`. To lock a rate for execution, use the persisted quote flow (`POST /v1/fx/quote` → `POST /v1/fx/execute`). --- ## Step 5 — Send a transfer ### Internal (CashXChain user to CashXChain user) ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/transfers \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: invoice-2026-001" \ -d '{ "recipient_email": "recipient@cashxchain.com", "amount": "50.00", "currency": "USD", "note": "INV-2026-001" }' ``` ### External (bank account) ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/transfers \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: invoice-2026-002" \ -d '{ "recipient": { "email": "vendor@external.com", "name": "Vendor GmbH", "bank": { "country": "DE", "bank_name": "Deutsche Bank", "account_number": "DE89370400440532013000", "routing_number": "37040044", "currency": "EUR" } }, "amount": "1000.00", "currency": "EUR", "note": "Invoice payment" }' ``` The response includes `transfer_id`, `status`, and `estimated_arrival`. **Transfer status lifecycle:** ``` pending → quoting → executing → completed ↘ failed ↘ rolled_back ``` --- ## Step 6 — Track the transfer ```bash curl https://api.sandbox.cashxchain.com/v1/transfers/$TRANSFER_ID \ -H "Authorization: Bearer $CXC_API_KEY" ``` --- ## API conventions - **JSON** request and response bodies. Always set `Content-Type: application/json` on write requests. - **ISO 8601** timestamps in UTC (`2026-06-08T12:00:00Z`). - **Decimal strings** for amounts (`"1000.00"` not `1000`). - **ISO 4217** currency codes (`USD`, `EUR`, `USDC`). - **ISO 3166-1 alpha-2** country codes (`US`, `DE`). - **UUIDs** for all resource IDs. - **Idempotency-Key** header required on all write routes. Use a unique string per distinct operation (invoice number, UUID, etc.). Replaying the same key returns the cached response safely. - **Pagination**: `limit` + `offset` or cursor (`before`) on list endpoints. Returns `has_more` and `next_cursor` where applicable. --- ## Sandbox routing rules In sandbox, payment routing is deterministic: | Currency | Partner | |---|---| | USD, EUR, GBP | MockPartner — instant, always succeeds | | USDC, EURC | Coinbase CDP on Solana | Internal (email-to-email) transfers always work in sandbox. External (bank) transfers return 400 unless the bank details match a registered sandbox user. --- ## Next steps - [Authentication](./authentication) — key types, scopes, and the auth decision tree - [API route reference](./routes) — complete endpoint list with scopes - [Errors](./errors) — error format and all error codes - [Webhooks](./webhooks) — receive real-time payment events - [Integration quickstart](../integration/quickstart) — full end-to-end integration guide --- # Master key (platform API key) Source: https://docs.cashxchain.com/docs/api/master-key Description: The master key is CashXChain's highest-privilege credential for platform operations and internal dashboards. # Master key — Platform API key The master key (`mk_`) is the highest-privilege credential in the CashXChain system. It is a platform-operations credential, distinct from the developer API keys (`sk_`, `pk_`, `rk_`) used by external integrations. --- ## What it can do | Capability | Master key | |---|---| | Access all `/v1/*` routes | ✅ | | Access `/internal/*` dashboard routes | ✅ | | Write operations (POST, PUT, DELETE, PATCH) | ✅ | | Scope enforcement | Bypassed — all scopes always pass | | Create via API | ❌ — admin script only | | Revoke via API | ❌ — database only | The master key is the **only** API credential that can reach dashboard routes. Regular API keys (`sk_`, `pk_`, `rk_`) are rejected at the middleware layer before any database lookup — they cannot access dashboard endpoints regardless of their scopes or type. --- ## Key format ``` mk_sandbox_<64 hex characters> ``` Total length: 75 characters. Identical format to other key types — only the prefix differs. Production: `mk_live_<64 hex characters>` --- ## How to obtain one Master keys cannot be created through any HTTP endpoint. They are provisioned exclusively by running the admin seed script with direct database access: ```bash node scripts/create-master-key.mjs \ --account-id \ --label "Ops dashboard key" ``` **Prerequisites:** - `DATABASE_URL` environment variable pointing at the target database. - Direct network access to the database (not via the API). **What the script does:** 1. Generates 32 random bytes → 64 hex characters. 2. Prepends `mk_sandbox_` (or `mk_live_`) to form the full key. 3. SHA-256 hashes the full key. 4. Extracts `key_prefix` (first 20 characters) and `key_suffix` (last 4 characters) for masked display. 5. Inserts into the `master_keys` table with `created_by = 'admin-seed-script'`. 6. Prints the full key to stdout **once** with a warning. ``` ✓ Master key created Label: Ops dashboard key Prefix: mk_sandbox_ab12cd34ef56 Last 4: a1b2 Token: mk_sandbox_ab12cd34ef56...a1b2 ← COPY THIS NOW ⚠ This key is not stored. Copy it before closing this terminal. ``` --- ## Using the key Pass the master key in the `Authorization` header exactly like any other bearer token: ```http Authorization: Bearer mk_sandbox_ab12cd34ef56...a1b2 ``` The API detects the `mk_` prefix and routes the lookup to the `master_keys` table (not `api_keys`). All scope checks are bypassed. All dashboard routes are accessible. --- ## Request flow ``` Authorization: Bearer mk_sandbox_<64hex> ↓ api_key_auth middleware detects mk_ prefix ↓ SHA-256 hash the token ↓ SELECT FROM master_keys WHERE key_hash = $1 AND revoked_at IS NULL ↓ Found → AuthContext { key_type: "master", scopes: [] } ↓ Background task: UPDATE master_keys SET last_used_at = NOW() ↓ Handler runs — scope checks unconditionally pass ``` --- ## Revoking a master key There is no API endpoint for revoking a master key. Revocation requires direct database access: ```sql UPDATE master_keys SET revoked_at = NOW() WHERE id = ''; ``` In an incident, revocation takes effect immediately on the next request to the key — the partial index `WHERE revoked_at IS NULL` ensures revoked keys are never found in authentication lookups. --- ## Storage and security | Property | Detail | |---|---| | Table | `master_keys` (separate from `api_keys`) | | Stored value | SHA-256 hex digest only — plain-text never stored | | Domain struct | `MasterKey` deliberately excludes the `key_hash` field — hash never leaves the database layer | | Collision prevention | `UNIQUE (key_hash)` constraint | | Lookup index | Partial index on `(key_hash) WHERE revoked_at IS NULL` — O(1) and never touches revoked rows | --- ## When to use a master key Use master keys for: - **Internal dashboards** — the CashXChain ops dashboard and monitoring tools. - **Platform automation** — scripts that manage accounts, run reconciliation, or access multi-account data. - **Internal tooling** — anything that needs `/internal/*` routes. Do **not** use master keys for: - Third-party integrations — issue a `sk_` key with the minimum required scopes. - Customer-facing applications — issue a `pk_` key for read-only access. - Any context where the key could be exposed outside your infrastructure. --- ## Differences from secret key (`sk_`) | | `mk_` | `sk_` | |---|---|---| | Dashboard routes (`/internal/*`) | ✅ | ❌ | | Created via API | ❌ | ✅ | | Revoked via API | ❌ | ✅ | | Stored in `master_keys` table | ✅ | ❌ | | Scope bypass | ✅ | ✅ | | Write access | ✅ | ✅ | --- # Payments & Transfers Source: https://docs.cashxchain.com/docs/api/payments Description: Full request/response reference for transfers, payments, and the low-level partner payment API. # Payments & Transfers CashXChain has two payment surfaces: - **Transfers** (`/v1/transfers`) — the primary, high-level API for sending money. Use this for most integrations. - **Payments** (`/v1/payments`) — the low-level partner passthrough API for add-funds and claimless sends via a specific partner. Money movement is created with a write call and tracked as **transactions** (`/v1/transactions`). --- ## Transfers ### POST /v1/transfers Creates a transfer. The API auto-detects the transfer type from the body shape: - Send `recipient_email` for an **internal** transfer (CashXChain user to CashXChain user). - Send `recipient` (object with `bank`) for an **external** transfer (to a bank account). **Auth:** Any valid credential. Scope required for `rk_` keys: `transfers:write`. **Header:** `Idempotency-Key: ` — required. #### Internal transfer (email-to-email) ```http POST /v1/transfers Authorization: Bearer Content-Type: application/json Idempotency-Key: invoice-2026-001 ``` ```json { "recipient_email": "recipient@cashxchain.com", "amount": "50.00", "currency": "USD", "note": "INV-2026-001" } ``` Supported currencies in sandbox: - `USD`, `EUR`, `GBP` → routed via MockPartner (instant, deterministic) - `USDC`, `EURC` → routed via Coinbase CDP on Solana #### External transfer (bank account) ```json { "recipient": { "email": "vendor@external.com", "name": "Vendor GmbH", "bank": { "country": "DE", "bank_name": "Deutsche Bank", "account_number": "DE89370400440532013000", "routing_number": "37040044", "currency": "EUR" } }, "amount": "1000.00", "currency": "EUR", "note": "Invoice payment" } ``` > **Sandbox note:** External transfers return `400 external_send_blocked` unless the bank details match a registered sandbox user. #### Response (201 Created) ```json { "transfer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "executing", "amount": "50.00", "currency": "USD", "estimated_arrival": "within minutes", "veem_payment_id": "mock-pay-abc123" } ``` #### Transfer status lifecycle ``` pending → quoting → executing → completed ↘ failed ↘ rolled_back ``` | Status | Meaning | |---|---| | `pending` | Received and queued. | | `quoting` | Fetching FX rate or routing information. | | `executing` | Submitted to the downstream partner rail. | | `completed` | Settled successfully. | | `failed` | Terminal failure. The transaction will not proceed. | | `rolled_back` | Execution started but was reversed. | --- ### GET /v1/transfers List transfers for the caller's account. **Auth:** Any valid credential. Scope required for `rk_` keys: `transfers:read`. ```http GET /v1/transfers Authorization: Bearer ``` --- ### GET /v1/transfers/\{id\} Retrieve a single transfer by UUID. **Auth:** Any valid credential. Scope required for `rk_` keys: `transfers:read`. ```http GET /v1/transfers/3fa85f64-5717-4562-b3fc-2c963f66afa6 Authorization: Bearer ``` --- ## Transactions Transactions are the ledger records produced by transfers. Read transactions to track the status of money movement. ### GET /v1/transactions ```http GET /v1/transactions?limit=50 Authorization: Bearer ``` Query parameters: | Param | Type | Description | |---|---|---| | `limit` | integer | Max rows (default 50, max 200). | | `before` | uuid | Cursor for pagination — returns rows before this transaction ID. | **Auth:** Scope required for `rk_` keys: `transactions:read`. ### GET /v1/transactions/\{id\} ```http GET /v1/transactions/3fa85f64-5717-4562-b3fc-2c963f66afa6 Authorization: Bearer ``` --- ## Payments (low-level partner API) The payments API provides direct access to partner-level funding operations. Use it when you need fine-grained control over which partner handles a transaction or when building treasury/wallet top-up flows. ### POST /v1/payments/add-funds Add funds to a customer's wallet via a specific partner. **Auth:** Any valid credential. Scope required for `rk_` keys: `payments:write`. **Header:** `Idempotency-Key: ` — required. ```http POST /v1/payments/add-funds Authorization: Bearer Content-Type: application/json Idempotency-Key: add-funds-2026-001 ``` ```json { "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "partner": "veem", "amount": "500.00", "currency": "USD" } ``` Optional: include `source_funding_method_external_id` to specify the partner-side funding method. If omitted, it is auto-discovered. #### Response (201 Created) ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "partner": "veem", "direction": "outbound", "kind": "add_funds", "amount": "500.00", "currency": "USD", "status": "authorized", "external_id": "mock-pay-xyz", "claim_link": null, "idempotency_key": "add-funds-2026-001", "retry_count": 0, "created_at": "2026-06-08T00:00:00Z", "completed_at": null } ``` --- ### POST /v1/payments/send Send a claimless payment to an external payee via a specific partner. **Auth:** Any valid credential. Scope required for `rk_` keys: `payments:write`. **Header:** `Idempotency-Key: ` — required. ```json { "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "partner": "veem", "amount": "250.00", "currency": "USD", "purpose": "Goods and Services", "source_funding_method_external_id": "", "source_funding_method_kind": "wallet", "payee": { "email": "payee@vendor.com", "first_name": "John", "last_name": "Smith", "country_code": "US", "phone_country_code": "+1", "phone_number": "5551234567", "kind": "business", "business": { "business_name": "Smith Corp", "industry": "Technology", "sub_industry": "Software", "entity": "LLC", "tax_id_number": "12-3456789", "address": { "country_code": "US", "street": "123 Main St", "city": "New York", "province": "NY", "postal_code": "10001" } }, "bank": { "iso_country_code": "US", "bank_name": "JPMorgan Chase", "currency_code": "USD", "bank_account_number": "123456789", "routing_number": "021000021" } } } ``` `source_funding_method_kind` values: `wallet` | `bank` | `viban` `payee.kind` values: `personal` | `business` --- ### GET /v1/payments List payments for the caller's account. **Auth:** Any valid credential. Scope required for `rk_` keys: `payments:read`. ```http GET /v1/payments?limit=50&status=pending&customer_id= Authorization: Bearer ``` Query parameters: | Param | Type | Description | |---|---|---| | `customer_id` | uuid | Filter by customer. Non-admin callers are pinned to their own account. | | `status` | string | Filter by payment status. | | `limit` | integer | Max rows (default 50, max 200). | --- ### GET /v1/payments/\{id\} Retrieve a single payment by UUID. **Auth:** Any valid credential. Scope required for `rk_` keys: `payments:read`. --- ## Payment object fields | Field | Type | Description | |---|---|---| | `id` | uuid | Payment UUID. | | `partner` | string | Partner that executed the payment (`veem`, `coinbase`, `circle`, `stablegate`). | | `direction` | string | `outbound` or `inbound`. | | `kind` | string | `add_funds`, `claimless`, or `send`. | | `amount` | decimal string | Payment amount. | | `currency` | string | ISO 4217 currency code. | | `status` | string | See lifecycle below. | | `external_id` | string \| null | Partner-assigned payment ID. | | `claim_link` | string \| null | Claim URL for claimless payments, if applicable. | | `idempotency_key` | string | The `Idempotency-Key` submitted with the request. | | `retry_count` | integer | Number of times this payment has been retried. | | `created_at` | ISO 8601 | Creation timestamp. | | `completed_at` | ISO 8601 \| null | Settlement timestamp. | ### Payment status lifecycle ``` pending → sent → authorized → completed ↘ failed ↘ cancelled ``` | Status | Meaning | |---|---| | `pending` | Persisted, not yet submitted to partner. | | `sent` | Submitted to partner — awaiting confirmation. | | `authorized` | Partner has authorized the transaction. | | `completed` | Fully settled. | | `failed` | Terminal failure. | | `cancelled` | Cancelled before execution. | --- ## Idempotency All write endpoints (`POST /v1/transfers`, `POST /v1/payments/add-funds`, `POST /v1/payments/send`) require an `Idempotency-Key` header. ```http Idempotency-Key: invoice-2026-001 ``` - Use a unique string per distinct operation — an invoice number, UUID, or timestamp. - Repeating the same key returns the cached response (`200 OK`) without re-executing. - Prevents double-charges on network retries, timeouts, or 5xx errors. - The `idempotency_key` is included in the response for correlation. --- # 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. --- # Request logs & usage Source: https://docs.cashxchain.com/docs/api/request-logs Description: Access request history, usage analytics, and the utility address validation endpoint. # Request logs & usage The CashXChain API automatically logs every authenticated request. These logs are queryable via the API and include full request/response bodies for debugging. --- ## Request logs ### GET /v1/request-logs Returns paginated request history for the caller's account. **Auth:** Any valid credential. Scope required for `rk_` keys: `request_logs:read`. ```http GET /v1/request-logs?limit=100 Authorization: Bearer ``` Query parameters: | Param | Type | Description | |---|---|---| | `limit` | integer | Max rows (default 100). | | `before` | uuid | Cursor — returns entries before this log ID. | #### Response (200 OK) ```json { "logs": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "method": "POST", "path": "/v1/transfers", "status_code": 201, "duration_ms": 142, "key_type": "api_key", "api_key_id": "uuid-or-null", "ip_address": "1.2.3.4", "idempotency_key": "invoice-2026-001", "created_at": "2026-06-08T12:00:00Z" } ], "has_more": false, "next_cursor": null } ``` --- ### GET /v1/request-logs/\{id\} Retrieve a single log entry with the full request and response bodies. **Auth:** Any valid credential. Scope required for `rk_` keys: `request_logs:read`. ```http GET /v1/request-logs/3fa85f64-5717-4562-b3fc-2c963f66afa6 Authorization: Bearer ``` #### Response (200 OK) ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "method": "POST", "path": "/v1/transfers", "status_code": 201, "duration_ms": 142, "key_type": "api_key", "api_key_id": "uuid-or-null", "ip_address": "1.2.3.4", "idempotency_key": "invoice-2026-001", "request_body": { "recipient_email": "...", "amount": "50.00", "currency": "USD" }, "response_body": { "transfer_id": "...", "status": "executing" }, "created_at": "2026-06-08T12:00:00Z" } ``` Use the log `id` when contacting support to reference a specific request. --- ## Usage analytics ### GET /v1/usage/summary Returns account-level usage statistics. **Auth:** Any valid credential. Scope required for `rk_` keys: `usage:read`. ```http GET /v1/usage/summary Authorization: Bearer ``` #### Response (200 OK) ```json { "requests_7d": 142, "requests_7d_delta_pct": 12.5, "error_rate_pct": 2.1, "total_volume": "48500.00", "avg_settlement_secs": 1.8 } ``` ### GET /v1/usage/timeseries Returns per-day request counts for the specified window. **Auth:** Any valid credential. Scope required for `rk_` keys: `usage:read`. ```http GET /v1/usage/timeseries?window=7d Authorization: Bearer ``` Query parameters: | Param | Values | Description | |---|---|---| | `window` | `7d`, `30d`, `90d` | Time window (default `7d`). | #### Response (200 OK) ```json { "window": "7d", "data": [ { "date": "2026-06-01", "count": 18 }, { "date": "2026-06-02", "count": 24 }, { "date": "2026-06-03", "count": 31 } ] } ``` --- ## Utility ### GET /v1/utility/validate-address Validates a blockchain address and, for Solana, checks whether the recipient's associated token account (ATA) exists. **Auth:** Any valid credential. No scope required. ```http GET /v1/utility/validate-address?address=Ax1b...&chain=solana&asset=USDC Authorization: Bearer ``` Query parameters: | Param | Type | Description | |---|---|---| | `address` | string | The blockchain address to validate. | | `chain` | string | `solana` (others: `ethereum`, `polygon`). | | `asset` | string | Optional. SPL asset to check ATA for (e.g. `USDC`, `EURC`). Defaults to `USDC` on Solana. | #### Response (200 OK) ```json { "valid": true, "reason": null, "ata_exists": true, "asset": "USDC", "estimated_rent": 0.00203928 } ``` | Field | Description | |---|---| | `valid` | Whether the address is syntactically and cryptographically valid. | | `reason` | Null if valid, or a human-readable reason for invalidity. | | `ata_exists` | Solana only. Whether the recipient's USDC/EURC ATA already exists. `false` means the first transfer to this address will create the ATA at ~0.002 SOL cost. | | `asset` | The asset whose ATA was checked. Echoes the input. | | `estimated_rent` | SOL needed to create the ATA if missing (rent-exempt minimum for a 165-byte token account). `0` if the ATA already exists. | --- ## Identity ### GET /v1/me Returns the caller's identity extracted from their auth token. Useful for verifying the credential and understanding which account it belongs to. **Auth:** Any valid credential. No scope required. ```http GET /v1/me Authorization: Bearer ``` --- # API route reference Source: https://docs.cashxchain.com/docs/api/routes Description: Complete list of all CashXChain API endpoints, authentication requirements, and required scopes. # API route reference This page lists every endpoint in the CashXChain API. Routes are grouped by the authentication tier they belong to. **Base URL:** `https://api.sandbox.cashxchain.com` (sandbox) / `https://api.cashxchain.com` (production) --- ## Auth tiers | Tier | Accepts | Rejects | |---|---|---| | **Public** | No credential required | — | | **Unified** | JWT (any `aud`), `sk_`, `pk_` (read-only), `rk_` (scoped), `mk_` | — | | **Elevated** | JWT (`aud=internal` or `aud=admin`), `mk_` | `sk_`, `pk_`, `rk_` → 401 | | **HMAC** | HMAC-SHA-256 (`AUTH_PORTAL_WEBHOOK_SECRET`) | Everything else | | **Bearer secret** | `AUTH_PORTAL_REPLAY_SECRET` or JWT | — | --- ## Public routes (no authentication) | Method | Path | Description | |---|---|---| | `GET` | `/` | Service info and version | | `GET` | `/health` | Liveness probe | | `GET` | `/ready` | Readiness probe (database connectivity) | | `POST` | `/webhooks/{partner}/{env}` | Receive partner webhook events (HMAC-verified internally) | | `POST` | `/v1/fx/quotes` | Stateless FX quote — no auth, no persistence | --- ## Unified auth — Developer API These routes accept any valid credential (JWT, `sk_`, `pk_`, `rk_`, or `mk_`). Publishable keys are limited to read-only methods. Restricted keys are gated by the scope column. ### Accounts | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `POST` | `/v1/accounts` | ✅ | — | Create account. Requires `api_tier=platform_ready` JWT when `?acting_as=` is set. | | `POST` | `/v1/customers` | ✅ | — | Create customer (legacy alias). Idempotent on email. | ### Transfers | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `POST` | `/v1/transfers` | ✅ | `transfers:write` | Create internal (email-to-email) or external (bank) transfer. Requires `Idempotency-Key` header. | | `GET` | `/v1/transfers` | — | `transfers:read` | List transfers for the caller's account. | | `GET` | `/v1/transfers/{id}` | — | `transfers:read` | Retrieve a single transfer by UUID. | ### Payments (low-level) | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `POST` | `/v1/payments/add-funds` | ✅ | `payments:write` | Add funds to a customer wallet via a partner. Requires `Idempotency-Key` header. | | `POST` | `/v1/payments/send` | ✅ | `payments:write` | Send a claimless payment to an external payee via a partner. Requires `Idempotency-Key` header. | | `GET` | `/v1/payments` | — | `payments:read` | List payments. Filter by `customer_id`, `status`, `limit`. | | `GET` | `/v1/payments/{id}` | — | `payments:read` | Retrieve a single payment by UUID. | ### FX | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `POST` | `/v1/fx/quotes` | — | — | **Public.** Stateless, non-persisted FX quote. | | `POST` | `/v1/fx/quote` | ✅ | `fx:read` | Persisted FX quote with 30-second TTL. Returns `quote_id` for execute step. Sandbox only. | | `POST` | `/v1/fx/execute` | ✅ | `payments:write` | Execute a persisted FX quote. Atomic DB transaction — debit/credit + transfers row. Sandbox only. | ### Transactions | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `GET` | `/v1/transactions` | — | `transactions:read` | List transactions for the caller's account. | | `GET` | `/v1/transactions/{id}` | — | `transactions:read` | Retrieve a single transaction by UUID. | ### Contacts | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `GET` | `/v1/contacts` | — | `contacts:read` | List payment beneficiaries / contacts. | ### API keys | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `POST` | `/v1/api-keys` | ✅ | `api_keys:write` | Create a new API key. Full token returned once only. | | `GET` | `/v1/api-keys` | — | `api_keys:read` | List all API keys for the account. No tokens returned. | | `DELETE` | `/v1/api-keys/{id}` | ✅ | `api_keys:write` | Revoke an API key. Returns 204. | ### Request logs | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `GET` | `/v1/request-logs` | — | `request_logs:read` | List request logs. Supports `limit`, `before` (cursor). | | `GET` | `/v1/request-logs/{id}` | — | `request_logs:read` | Retrieve a single request log with full request/response bodies. | ### Usage analytics | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `GET` | `/v1/usage/summary` | — | `usage:read` | Summary stats: request count, error rate, volume, avg settlement. | | `GET` | `/v1/usage/timeseries` | — | `usage:read` | Time-series data. Query param `?window=7d|30d|90d`. | ### Utility | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `GET` | `/v1/utility/validate-address` | — | — | Validate a blockchain address. Params: `address`, `chain`, `asset` (optional). Solana: checks ATA existence. | ### Identity | Method | Path | Write | Scope (RK) | Description | |---|---|:---:|---|---| | `GET` | `/v1/me` | — | — | Returns the caller's identity and account info from the auth token. | --- ## Elevated auth — Dashboard / Platform These routes require JWT with `aud=internal` or `aud=admin`, or a master key (`mk_`). Regular API keys (`sk_`, `pk_`, `rk_`) are **rejected with 401** before any database lookup — they cannot access these routes under any circumstance. ### Accounts (dashboard) | Method | Path | Description | |---|---|---| | `GET` | `/v1/accounts` | List accounts. Filter by `tenant_id`, `managed_by`, `limit`, `offset`. | | `GET` | `/v1/accounts/{id}` | Retrieve a single account by UUID. | | `GET` | `/v1/accounts/me` | Caller's own account. Elevated context. | | `GET` | `/v1/accounts/me/balance` | Caller's balance breakdown by currency. | | `GET` | `/v1/accounts/me/vibans` | Caller's virtual IBANs. | | `GET` | `/v1/accounts/{id}/statements` | Account statement. | ### Customers (dashboard) | Method | Path | Description | |---|---|---| | `GET` | `/v1/customers` | List customers for the caller's account. | | `GET` | `/v1/customers/{id}` | Retrieve a single customer. | | `POST` | `/v1/customers/{id}/partner-link` | Enroll a customer with a payment partner. | | `GET` | `/v1/customers/{id}/partner-link` | List all partner links for a customer. | | `GET` | `/v1/customers/{id}/partner-link/{partner}` | Retrieve a specific partner link. | ### vIBANs (dashboard) | Method | Path | Description | |---|---|---| | `POST` | `/v1/customers/{id}/vibans` | Create a vIBAN for a customer. Requires `Idempotency-Key`. | | `GET` | `/v1/customers/{id}/vibans` | List vIBANs for a customer. | | `GET` | `/v1/customers/{id}/vibans/{viban_id}` | Retrieve a vIBAN. | | `GET` | `/v1/customers/{id}/vibans/{viban_id}/balance` | vIBAN balance. | | `GET` | `/v1/customers/{id}/vibans/{viban_id}/transactions` | vIBAN transaction history. | | `GET` | `/v1/customers/{id}/wallet` | Customer's crypto wallet info. | ### Platform permissions (dashboard) | Method | Path | Description | |---|---|---| | `DELETE` | `/v1/platform-permissions/{id}` | Revoke a platform permission (managed account link). | ### Notifications (dashboard) | Method | Path | Description | |---|---|---| | `GET` | `/v1/notifications` | Server-sent events stream. JWT via `?access_token=` for `EventSource` clients. | ### Crypto addresses (dashboard) | Method | Path | Description | |---|---|---| | `GET` | `/v1/crypto-addresses/me` | Caller's on-chain addresses. | --- ## Internal — HMAC service-to-service Not accessible from developer or platform API keys. Authenticated via HMAC-SHA-256 (`AUTH_PORTAL_WEBHOOK_SECRET`). | Method | Path | Events | |---|---|---| | `POST` | `/internal/webhooks/auth` | `user.created`, `user.kyc.approved`, `user.kyc_status_changed`, `user.updated` | --- ## Sandbox-only routes These routes are only available when `APP_ENV=sandbox`. They do not exist in production. ### Faucet | Method | Path | Auth | Description | |---|---|---|---| | `POST` | `/v1/sandbox/faucet` | JWT | Credit sandbox balances for testing. | ### Admin | Method | Path | Auth | Description | |---|---|---|---| | `POST` | `/v1/sandbox/admin/wipe` | Bearer secret (`AUTH_PORTAL_REPLAY_SECRET`) | Reset all sandbox data. | | `POST` | `/v1/sandbox/admin/replay` | Bearer secret | Replay a set of seed events. | | `POST` | `/v1/sandbox/admin/reprovision/{account_id}` | JWT | Re-run provisioning for an account. | | `GET` | `/v1/sandbox/admin/whoami` | JWT | Debug identity endpoint. | --- ## API documentation (sandbox only) | Method | Path | Description | |---|---|---| | `GET` | `/v1/openapi.json` | OpenAPI 3.0 spec (sandbox only — not exposed in production) | | `GET` | `/v1/docs` | Swagger UI (sandbox only) | --- ## Common request headers | Header | Required | Description | |---|---|---| | `Authorization` | Yes (protected routes) | `Bearer ` | | `Content-Type` | Yes (POST/PUT/PATCH) | `application/json` | | `Idempotency-Key` | Yes (all write routes) | Unique key per distinct request. Repeating the same key returns the cached response. | | `X-Request-ID` | Optional | Client-supplied request correlation ID. Echoed back in `X-CXC-Request-ID`. | --- # 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. `sk_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 :::note Rolling out The production API is environment-gated and rolling out. Build and validate on sandbox today; if production sign-up or API access is not yet enabled for your account, [contact us](../legal/contact) to be onboarded. ::: 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 | `sk_sandbox_...` | `sk_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({ from_currency: 'EUR', to_currency: 'USD', from_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={ 'from_currency': 'EUR', 'to_currency': 'USD', 'from_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: How balances are exposed today, and the planned wallets resource. # Wallets API :::caution Planned A standalone wallets resource (`/v1/wallets`, per-wallet balances, ledger-entry listing, and wallet-to-wallet transfers) is on the roadmap and **not yet available** in the sandbox API. The endpoints below describe the planned model. Use the supported endpoints in [Balances today](#balances-today) for now. ::: ## Balances today Account balances are aggregated per settlement currency, summed across the underlying rails (vIBANs and USDC rails roll into the USD/EUR tiles): ```http GET /v1/accounts/me/balance ``` ```json { "totals": [ { "currency": "USD", "amount": "98000.00", "available": "97000.00", "pending": "1000.00" }, { "currency": "EUR", "amount": "25000.00", "available": "25000.00", "pending": "0.00" } ] } ``` The caller is derived from the authenticated session, so there is no account id in the path. To list the underlying vIBANs, use `GET /v1/accounts/me/vibans`. > These `/v1/accounts/me/*` endpoints are dashboard (session) endpoints and are > not callable with a developer API key. To move funds to a recipient, create a [transfer](./payments) — `POST /v1/transfers` — rather than a wallet-to-wallet transfer. ## Planned: wallet objects ```http GET /v1/wallets GET /v1/wallets/{wallet_id}/balances GET /v1/wallets/{wallet_id}/ledger-entries POST /v1/wallet-transfers ``` These are part of the roadmap toward multiple logical balance containers (operating, treasury, payout, fee, escrow). See [Wallets](../platform/wallets) for the business-facing balance model. --- # Webhooks API Source: https://docs.cashxchain.com/docs/api/webhooks Description: Event delivery today (stream) and planned customer-managed webhooks. # Webhooks API Webhooks notify your system when important events happen in CashXChain. :::caution Planned Customer-managed webhook endpoints (registering your own URL via `/v1/webhooks` and receiving signed POSTs) are on the roadmap and **not yet available** in the sandbox API. Today, events are available as a server-sent event (SSE) stream from the dashboard session — see [Event stream](#event-stream-available-today). The signed-POST contract below is the planned model. ::: ## Event stream (available today) ```http GET /v1/notifications ``` A long-lived SSE stream of account, transfer/payment, and balance events for the authenticated session. This is a dashboard (session) endpoint and is not consumed with a developer API key. ## Planned: signed webhook delivery ### 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": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "transfer.completed", "created_at": "2026-06-01T09:00:42Z", "environment": "sandbox", "resource_type": "transfer", "resource_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "completed" } } ``` ### Signature headers The signing scheme is being finalized. Plan to verify a signature header (timestamp + HMAC) over the raw request body before trusting the payload; the exact header names will be published with the endpoint. ### Delivery behavior If your endpoint does not return a 2xx response, delivery is retried with backoff. Events may be delivered more than once and may arrive out of order. ### Idempotency Use the event ID to deduplicate processing. Your handler should be safe to run multiple times. ### Planned event types Aligned to the transfer/payment lifecycle: - `transfer.pending` - `transfer.executing` - `transfer.completed` - `transfer.failed` - `transfer.rolled_back` - `payment.sent` - `payment.completed` - `payment.failed` ## Testing Use sandbox to validate event handling — deduplication, retries, and reconciliation — against the event stream. --- # 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=sk_sandbox_... ``` ## 2. Create a contact (beneficiary) A contact is a saved recipient. For a bank account, use `kind: "bank_account"`: ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/contacts \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "bank_account", "name": "Example Supplier Ltd", "country": "US", "currency": "USD", "bank_name": "Example Bank", "account_number": "000123456789", "routing_number": "021000021" }' ``` Listing contacts (`GET /v1/contacts`) returns rails masked to the last 4 (`account_number_last4`, `iban_last4`, `routing_number_last4`). ## 3. 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 '{ "from_currency": "EUR", "to_currency": "USD", "from_amount": "1000.00" }' ``` ## 4. Create a transfer ```bash curl -X POST https://api.sandbox.cashxchain.com/v1/transfers \ -H "Authorization: Bearer $CXC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "amount": "1000.00", "currency": "USD", "recipient": { "name": "Example Supplier Ltd", "email": "ap@supplier.example", "bank": { "bank_name": "Example Bank", "account_number": "000123456789", "routing_number": "021000021", "country": "US", "currency": "USD" } }, "note": "QS-001" }' ``` The response returns a `transfer_id` and `status`. ## 5. Reconcile Poll `GET /v1/transactions` (or `GET /v1/transactions/{id}`) for the `completed` status, and download statements to match transfers against your internal records. Customer-managed webhook subscriptions are planned — see [Webhooks](../api/webhooks). ## 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-06-06 ### Documentation - Reconciled the API reference and platform pages with the sandbox OpenAPI (`/v1/openapi.json`). - Corrected endpoints: money movement is `POST /v1/transfers` with history via `GET /v1/transactions`; beneficiaries are `/v1/contacts`; FX adds a persisted `POST /v1/fx/quote` → `POST /v1/fx/execute` flow. - Corrected conventions: API keys are `sk_sandbox_` / `sk_live_` sent as `Authorization: Bearer`; resource IDs are UUIDs; lists are cursor + `limit`. - Labelled not-yet-available capabilities (standalone wallets API, customer-managed webhooks, production API access) as planned rather than live. ## 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. ---