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.

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