Payments

Payments in Caliza refer to the process of transferring funds from a beneficiary to a recipient. To manage payments, follow a two-step process:

1. Simulate the payment to get a quote.
2. Execute the payment based on the simulation.

See the sections below for more details on each step.

Simulate the payment

To simulate a payment using the Caliza API, you can use the following cURL command. Make sure to replace the following:

• YOUR_TOKEN with your actual API token
• beneficiaryId with the ID of the beneficiary you want to simulate the payment for.

See an example request and response below:

curl -s --location --request POST 'https://api.sandbox.caliza.com/core-api/v2/simulations' \
--header "Authorization: Bearer Your_Token" \
--header 'Content-Type: application/json' \
--data '{
    "from": {
        "currencyCode": "USDC",
        "value": 500
    },
    "to": {
        "currencyCode": "USD"
    },
    "beneficiaryId": "69261109adcc7b2db705a123",
    "recipientId": "12ace467-8189-42ec-8b21-0a5bf7cd7f5e",
    "funding": "ETH",
    "payout": "WIRE"
}'

Execute the payment

After simulating and agreeing on the from and to values, you'll need to start the payment.

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

Attach supporting documents

For high-value transactions, cross-border payments, or any transaction that requires supporting documentation for compliance — invoices, contracts, purchase orders, proof of goods or services, import/export licenses, and similar — Caliza accepts file attachments at the time the payment is created and lets you retrieve them later for audit or reconciliation.

There are two endpoints involved:

📘

File size limit

Each file must be non-empty and no larger than 10 MB. Requests containing an empty file or a file that exceeds the limit are rejected with 400 Bad Request (File is empty or File size exceeds maximum allowed size of 10MB).

Create a payment with documents

The endpoint accepts a multipart/form-data body with two parts:

• request — the same JSON payload you would send to POST /v1/payments, serialized as a string.
• files — one or more file parts (repeat the field name to attach multiple files).

curl --location 'https://api.sandbox.caliza.com/core-api/v1/payments/:withDocuments' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--form 'request="{\"simulationId\":\"{{SIMULATION_ID}}\",\"beneficiaryIp\":\"127.0.0.1\"}";type=application/json' \
--form 'files=@"./invoice.pdf"' \
--form 'files=@"./contract.pdf"'

⚠️

Document upload is best-effort

The transaction is created first, then files are uploaded. A successful 2xx response confirms that the transaction was created. If the file upload step fails afterwards, the transaction itself is not rolled back. Use GET /v1/transactions/{id}/:withDocuments to confirm which files were stored.

Retrieve a transaction with its documents

Once a payment has been created with attachments, you can fetch the transaction together with metadata for each stored document, including a presigned URL for direct download.

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

Get the payment status

To check the status of a payment using the Caliza API, you can use the following cURL command.

curl --location --globoff 'https://api.sandbox.caliza.com/core-api/v1/payments/{{payment_id}}' \
--header 'Authorization: Bearer YOUR_TOKEN'

Webhook events for payments

When a payment is completed, Caliza will send a webhook event to notify you about the successful payment. The relevant webhook event for payments completed is as follows:

{
"operation": "TRANSACTION_COMPLETED",
"resourceId": "{{payment_id}}",
"createdAt": "2025-04-17T22:10:23.476151179",
"integratorId": "{{integrator_id}}",
"beneficiaryId": "{{beneficiary_id}}",
"message": null,
"success": true,
"data": {
  "callbackType": "transactionCallback",
  "id": "{{payment_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": "PAYMENT_COMPLETED", // CREATED, PROCESSING, PAYMENT_SENT, PAYMENT_COMPLETED
  "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 payment status and take appropriate actions based on each transaction.

Related Articles