Fiat Deposits

To receive a USD deposit from a third party into a beneficiary's account, you first need to retrieve the banking credentials. There are two ways to do this:

Option 1: Deposit Instructions

Use the deposit instructions endpoint to retrieve account details for a specific payment rail:

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).

Option 2: Virtual Accounts

Alternatively, you can retrieve the banking credentials from the beneficiary's virtual accounts:

curl --location --request GET 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{beneficiaryId}/virtualAccounts' \
--header 'Authorization: Bearer YOUR_TOKEN'

Example response:

[
  {
    "id": "a1b2c3d4-5678-9012-abcd-ef1234567890",
    "accountNumber": "083a1637-219b-487b-a6dd-5e27252ddafd",
    "routingNumber": "021214891",
    "receiverName": "John Doe",
    "receiverAddress": "1600 Pennsylvania Avenue NW, 20500 Washington, DC, US",
    "receiverBankName": "CROSS RIVER BANK",
    "swiftCode": "BKCHUSXXXX",
    "receiverBankAddress": "2115 Linwood Ave, Fort Lee, NJ 07024, United States"
  }
]

This returns all virtual accounts associated with the beneficiary. For more details on creating and managing virtual accounts, see Create USD Virtual Accounts.

Response

Both options return 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