Caliza Core Concepts

This page explains the fundamental architecture and essential terms for interacting with the Caliza API, which focuses on global money transfers.

Key API Entities

The platform defines three main roles for fund movement:

• Integrator: The integrator is the software partner building the solution on the Caliza API.
• Beneficiary: The Beneficiary is the Integrator's customer. Every API call that moves funds requires a beneficiary ID. The Caliza KYX process will be performed when creating a beneficiary, triggering identity and compliance verification processes.
• Recipient: The entity that receives funds. The Recipient stores all information necessary for payment, such as bank account details (ex. SWIFT, ACH, PIX, or SPEI) or a blockchain wallet address.

The simulation-transaction model

All money movement on Caliza, including deposits, transfers, and withdrawals, is organized around a two-step framework from the API perspective: Simulation followed by Transaction.

• Simulation: The Simulation is the initial endpoint used to retrieve the details of an operation before executing the operation. A Simulation request returns an object containing comprehensive transaction details - including fees, exchange rates, and any other charges associated with the transaction. The generated simulation is typically valid for 30 minutes and guarantees the price, though this may vary depending on contract details. During this time, the customer can review the details and decide whether to proceed with the operation. If they do, the returned simulation ID is used to execute the transaction.
• Transaction/Payment: The Transaction is the execution endpoint that both confirms and initiates the money movement. To execute, the user submits the simulation ID received in the previous step, confirming the simulation. All fund movements are managed through Transactions, regardless of the parties involved. If the transaction involves a deposit (such as a Pix or stablecoin deposit), the Transaction response includes the information needed to complete the deposit.

Operational Currency and Conversion

Caliza uses stablecoins as the core of its operations.

• Stablecoin custody: Caliza allows integrators to hold stablecoins on behalf of their customers.
• Deposit conversions: The system immediately converts any deposit received in a local currency, such as BRL (Brazilian Real) or MXN (Mexican Peso), to USDC or USDT upon receipt.
• USDT/USDC conversion: The platform supports conversion between USDT and USDC, typically at a rate close to one-to-one, but a transaction fee applies.

Spread & revenue

Whenever an operation includes a currency conversion (for example USDC → BRL or USDC → MXN), the rate the beneficiary ultimately receives is built up in two markup tiers on top of the raw market rate. Each tier is a margin, and each margin is revenue for a different party.

• Market rate (marketExchangeRate): the raw mid-market FX rate between the source and destination currencies. No margin is applied at this level.
• Caliza rate (calizaRate): the market rate adjusted by Caliza's spread. The gap between the market rate and the Caliza rate is Caliza's revenue on the conversion. This spread always applies.
• Integrator rate (integratorRate): the Caliza rate adjusted by your own integrator spread. The gap between the Caliza rate and the integrator rate is your revenue on the conversion. You set this spread per simulation; when you do not, the integrator rate simply equals the Caliza rate (no integrator margin).

The two margins stack, so the integrator rate is the least favorable of the three. The beneficiary receives the amount converted at the integrator rate — that is the final disbursed amount.

You add your own spread by passing a customFees object with an INTEGRATOR_SPREAD value (in basis points, where 100 BPS = 1%) on the simulation request. The resulting margins are reported back on the simulation and transaction responses through the conversionDetails rate fields and the feeDetails.spreadFees[] items (one CALIZA item for Caliza's revenue and one INTEGRATOR_SPREAD item for yours). See the Exchanges and Payments guides for request and response examples.

Funding Methods and Payment Rails

Caliza supports a variety of methods for initiating and settling transactions, called Payment Rails. When creating a simulation or transaction, the funding_method field determines how the system sources initial funds.

• Using existing balance: If you omit funding_method, Caliza draws funds for the transaction from the USDC/USDT balance that the Integrator or Beneficiary already holds on the platform.
• Real-time deposit: If you specify funding_method, this signals that the transaction starts with a new real-time deposit of the specified type, which the system converts as needed for execution.

KYX Process

The KYX (Know Your Customer/Business) process verifies a Beneficiary's identity and compliance status. It begins automatically after a Beneficiary is created and adapts to the client’s risk profile and jurisdiction.

• Initiation: Creating a beneficiary triggers KYX. The system notifies integrators (typically via webhook) and may direct end users to a third-party verification provider (for example, AiPrise) to enter information or upload documents.
• Requirements: Requested documents depend on risk and region. For individuals, government ID is requested. For businesses, proof of address, business registration, and beneficial ownership information are requested.
• API endpoints: You can monitor the KYX status via the Beneficiary endpoints in the API.
• Flow and blocking: You must satisfy KYX requirements before certain transactions can proceed. Monitor status via webhooks and the API; handle rejections and resubmissions as needed.
• Best practices: Subscribe to KYX webhooks, surface clear upload instructions in your UI, validate files client-side, and implement retries and user notifications for incomplete or rejected submissions.

Sandbox environment

Caliza provides the sandbox environment to developers after the initial sales and compliance process. It allows testing and integration without using real money. Key aspects include:

• Deposit mocking: Caliza provides dedicated sandbox endpoints for integrators to simulate fiat deposits (Pix, SPEI) for testing, enabling flow validation without real money. It's highly recommended that integrators focus on their integration in sandbox before moving to production.

Next Steps