Deposits

Caliza allows beneficiaries to deposit funds using stablecoins, local currencies and payment rails including USD (ACH, Wire, SWIFT), BRL (Pix), and MXN (SPEI). Here you'll find an example of a stablecoin deposit.

Before initiating a transaction, you can simulate a USDC/USDT deposit. To do this, set the fundingMethod that you would like to use to make the deposit, along with the from or to value that you'd like to either send or end up with. The simulation response will provide the full transaction details.

To simulate a USDC/USDT deposit using the Caliza API, you can use the following cURL command. Make sure to replace YOUR_TOKEN with your actual API token and beneficiaryId with the ID of the beneficiary you want to simulate the transaction for:

curl 'https://api.sandbox.caliza.com/core-api/v1/simulations' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{beneficiaryId}}",
  "from": {
    "value": 10,
    "currencyCode": "USDC"
  },
  "to": {
    "currencyCode": "USDC"
  },
  "fundingMethod": "ETH"
}'

Note: You can also use "USDT" instead of "USDC" for the currency code.

This command creates a simulation for a USDC/USDT deposit. The response includes details about the simulated transaction, including fees and estimated time of arrival. The response should look like this:

{
  "id": "34c9dfe7-12da-4119-8beb-4db895c01a47",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "beneficiaryId": "69261109adcc7b2db705a123",
  "from": {
    "currencyCode": "USDC",
    "value": 10.00
  },
  "to": {
    "currencyCode": "USDC",
    "value": 10.00
  },
  "transactionDetails": {
    "conversionDetails": {
      "effectiveTransactionValue": 10.00,
      "marketExchangeRate": 1.0
    },
    "feeDetails": {
      "totalFees": {
        "currencyCode": "USDC",
        "value": 0.00
      }
    }
  },
  "createdDate": "2025-11-27T14:30:00Z"
}

Where:

• id: The unique identifier for the simulation.
• integratorId: The ID of the integrator associated with the simulation.
• beneficiaryId: The ID of the beneficiary associated with the simulation.
• from: An object containing details about the source of funds, including currency code and value.
• to: An object containing details about the destination of funds, including currency code and value.
• transactionDetails: An object containing details about the transaction, including conversion details and fee details.
• createdDate: The date and time when the system created the simulation.

Execute the simulated deposit

To execute the simulated transaction, you can use the following cURL command. Make sure to replace YOUR_TOKEN with your actual API token and simulationId with the ID of the simulation you want to execute:

curl 'https://api.sandbox.caliza.com/core-api/v1/transactions' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "simulationId": "{{simulationId}}",
  "beneficiaryIp": "{{beneficiaryIp}}"
}'

This command executes the transaction based on the provided simulation ID. The response includes details about the executed transaction, including its status and timestamps. The response should look like this:

{
    "id": "5d097212-9902-4d86-beec-c578640105f4",
    "simulationId": "34c9dfe7-12da-4119-8beb-4db895c01a47",
    "integratorId": "6920925fdbadfe09b1bf9e5e",
    "beneficiaryId": "69261109adcc7b2db705a123",
    "from": {
        "currencyCode": "USDC",
        "value": 10.00
    },
    "to": {
        "currencyCode": "USDC",
        "value": 10.00
    },
    "status": "PENDING",
    "blockchainInfo": {
        "fundingWallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "depositTransactionHash": null,
        "withdrawalTransactionHash": null
    },
    "localInfo": null,
    "beneficiaryIp": "127.0.0.1",
    "flowOfFundsId": "55b778b2-1d8e-48fb-8229-0386d0f33fe0",
    "transactionDetails": {
        "conversionDetails": {
            "effectiveTransactionValue": 10.00,
            "marketExchangeRate": 1.0
        },
        "feeDetails": {
            "totalFees": {
                "currencyCode": "USDC",
                "value": 0.00
            }
        }
    },
    "createdDate": "2025-11-27T14:35:00Z",
    "lastModifiedDate": "2025-11-27T14:35:00Z"
}

Where:

• id: The unique identifier for the transaction.
• simulationId: The ID of the simulation associated with the transaction.
• integratorId: The ID of the integrator associated with the transaction.
• beneficiaryId: The ID of the beneficiary associated with the transaction.
• from: An object containing details about the source of funds, including currency code and value.
• to: An object containing details about the destination of funds, including currency code and value.
• status: The current status of the transaction (for example, PENDING, COMPLETED).
• blockchainInfo: An object containing blockchain-related information, including funding wallet and transaction hashes.
• localInfo: Local payment information, if applicable (null for USDC/USDT deposits).
• beneficiaryIp: The IP address of the beneficiary initiating the transaction.
• flowOfFundsId: The unique identifier for the flow of funds associated with the transaction.
• transactionDetails: An object containing details about the transaction, including conversion details and fee details.
• createdDate: The date and time when the system created the transaction.

You can check the status of the deposit by querying the transaction endpoint using the transaction ID with the following command:

curl 'https://api.sandbox.caliza.com/core-api/v1/transactions/{{transaction_id}}' \
--header 'Authorization: Bearer YOUR_TOKEN'

Where transaction_id is the ID of the transaction you want to check.

📘

Relevant information on transactions

For crypto deposits, the blockchainInfo section includes the depositTransactionHash once the deposit is confirmed on the blockchain. For fiat deposits, the localInfo section contains relevant payment information, such as a Pix QR code or copy-and-paste code for Brazilian Real deposits.

Transaction hash for crypto transactions

For crypto transactions, you need to send the depositTransactionHash to Caliza to identify the transaction. For this, use this command:

curl --request PUT \
  --url 'https://api.sandbox.caliza.com/core-api/v1/transactions/{TRANSACTION_ID}/depositTransactionHash' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
      "transactionHash": "0x_hash_on_blockchain"
  }'

Replace TRANSACTION_ID with the actual transaction ID and YOUR_TOKEN with your API token.

Where:

• transactionHash: The hash of the deposit transaction on the blockchain.

This command updates the transaction with the provided deposit transaction hash. The response confirms that the hash has been successfully associated with the transaction.

USD third-party deposits

To receive a USD deposit from a third party into a beneficiary's account, you can use the following cURL command to retrieve account details:

curl --location --globoff 'https://api.sandbox.caliza.com/core-api/v1/transactions/deposit-instructions?beneficiaryId={beneficiaryId}&paymentRail={WIRE}' \
--header 'Authorization: Bearer YOUR_TOKEN'\

Where beneficiaryId must be replaced with the actual ID of the beneficiary and paymentRail with the desired payment rail (for example, WIRE, ACH, SWIFT).

As a response, you will get bank account details:

{
  "accountNumber": "123456789",
  "routingNumber": "021000021",
  "receiverName": "John Doe",
  "receiverBankName": "Global Bank",
  "receiverBankAddress": "123 Main Street, New York, NY, USA",
  "swiftCode": "DEUTDEFF",
  "reference": ""
}

Where:

• accountNumber: The bank account number for deposits.
• routingNumber: The routing number associated with the bank account.
• receiverName: The name of the account holder.
• receiverBankName: The name of the bank where the account is held.
• receiverBankAddress: The address of the bank where the account is held.
• swiftCode: The SWIFT code for international transactions.
• reference: Any specific reference information needed for the deposit.

This information can be shared with third parties to facilitate deposits into the beneficiary's account. As soon as the payor pays and we receive your funds, we will notify you via webhooks, and you can check the deposit status via the transactions endpoint. Depending on your configuration, these funds may be held as USD, or converted automatically into USDC.

Webhook events for deposits

The Caliza API uses webhook events to notify you of various transaction-related events, including deposits. When a deposit is made, Caliza will send webhook events to inform you of the transaction status. The relevant webhook events for deposits include:

{
  "operation": "PAYMENT_IN_COMPLETED",
  "resourceId": "{{transaction_id}}",
  "createdAt": "2025-04-17T22:10:23.476151179",
  "integratorId": "{{integrator_id}}",
  "beneficiaryId": "{{beneficiary_id}}",
  "message": null,
  "success": true,
  "data": {
    "callbackType": "transactionCallback",
    "id": "{{transaction_id}}",
    "integratorId": "{{integrator_id}}",
    "beneficiaryId": "{{beneficiary_id}}",
    "simulationId": null,
    "foFTransactionType": "REGULAR_TRANSACTION",
    "amountToBeConverted": {
      "currencyCode": "USDC",
      "value": 100.00
    },
    "from": {
      "currencyCode": "USD",
      "value": 100.00
    },
    "to": {
      "currencyCode": "USD",
      "value": 100.00
    },
    "totalFees": {
      "currencyCode": "USD",
      "value": 0.0000
    },
    "totalTaxes": {
      "currencyCode": "USD",
      "value": 0.0000
    },
    "status": "SUCCEEDED",
    "fiatAccountId": null,
    "recipientId": null,
    "fundingWallet": {{funding_wallet_address}},
    "targetWallet": null,
    "depositTransactionHash": null,
    "withdrawalTransactionHash": null,
    "flowOfFundsId": {{flow_of_funds_id}},
    "localTargetAccount": null,
    "exchangeRate": null,
    "settlement": false
  }
}

Where:

• operation: The type of operation that triggered the webhook (for example, TRANSACTION_COMPLETED).
• resourceId: The ID of the transaction associated with the webhook event.
• createdAt: The timestamp when the webhook event was created.
• integratorId: The ID of the integrator associated with the transaction.
• beneficiaryId: The ID of the beneficiary associated with the transaction.
• data: An object containing detailed information about the transaction, including its status and amounts.

You can use these webhook events to track deposit status and take appropriate actions based on each transaction.

Related Articles