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"
}'

Adding your own spread

When a payment involves a cross-currency payout — the beneficiary holds stablecoins but the recipient is paid in a local currency (for example USDC → BRL over PIX, or USDC → MXN over SPEI) — the payment includes a currency-conversion (FX) leg. On that leg you can add your own spread on top of Caliza's spread, and that spread becomes your revenue. You set it by passing a customFees object with an INTEGRATOR_SPREAD value on the simulation request.

• The value is expressed in basis points (BPS), where 100 BPS = 1%. A value of 10 means a 0.10% markup.
• The value must be ≥ 0. Passing 0 (or omitting customFees) disables your spread; Caliza's spread always applies.
• It only affects the currency-conversion (FX) leg. Same-currency payouts (for example a USD → USD wire) have no FX leg and are unaffected.

How the rates relate

A converted amount is built up in two markup tiers on top of the raw market rate. Each margin is revenue for a different party:

The two margins stack, so the integrator rate is the least favorable of the three. The recipient is paid the amount converted at the integrator rate.

Request

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": "BRL"
    },
    "customFees": {
        "INTEGRATOR_SPREAD": 100
    },
    "beneficiaryId": "69261109adcc7b2db705a123",
    "recipientId": "12ace467-8189-42ec-8b21-0a5bf7cd7f5e",
    "funding": "ETH",
    "payout": "PIX"
}'

Where customFees.INTEGRATOR_SPREAD is your spread in basis points (here 100 BPS = 1%).

Response

The simulation (and later the transaction) reports the rate tiers under conversionDetails, and each margin as an item under feeDetails.spreadFees[] — a CALIZA item for Caliza's revenue and an INTEGRATOR_SPREAD item for yours:

"transactionDetails": {
    "conversionDetails": {
        "effectiveTransactionValue": 2633.76,
        "marketExchangeRate": 5.40000000,
        "clientRate": 5.32019704,
        "calizaRate": 5.32019704,
        "integratorRate": 5.26752183
    },
    "feeDetails": {
        "spreadFees": [
            {
                "type": "CALIZA",
                "spreadBasisPoint": 150,
                "marketRate": 5.40000000,
                "effectiveRate": 5.32019704,
                "calizaRate": 5.32019704,
                "calculatedFee": 39.90
            },
            {
                "type": "INTEGRATOR_SPREAD",
                "spreadBasisPoint": 100,
                "marketRate": 5.40000000,
                "effectiveRate": 5.26752183,
                "calizaRate": 5.26752183,
                "calculatedFee": 26.34
            }
        ]
    }
}

Worked example

Paying out 500 USDC → BRL at a market rate of 5.40, with a Caliza spread of 150 BPS and your spread of 100 BPS:

• At the market rate (5.40000000): 500 × 5.40 = 2700.00 BRL.
• At the Caliza rate (5.32019704): 500 × 5.32019704 ≈ 2660.10 BRL. The 39.90 BRL gap is Caliza's revenue (the CALIZA spread item).
• At the integrator rate (5.26752183): 500 × 5.26752183 ≈ 2633.76 BRL. The 26.34 BRL gap is your revenue (the INTEGRATOR_SPREAD spread item).

The recipient is paid 2633.76 BRL — the amount converted at the integrator rate.

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:

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

Where:

* `request`: A JSON-encoded payment payload, identical in shape to the body of `POST /v1/payments`. At minimum it must include `simulationId` and `beneficiaryIp`.
* `files`: One file part per attachment. Repeat the form field to send multiple files in a single request.

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'

Upload a document to an existing transaction

When you need to attach a supporting document after a transaction has already been created — for example, to provide a document a transaction is waiting on, or to replace one that was rejected — use POST /v1/transactions/{id}/documents. Uploading a document through this endpoint triggers document validation for the transaction.

The endpoint accepts a multipart/form-data body with a single file part:

   curl --location 'https://api.sandbox.caliza.com/core-api/v1/transactions/{{TRANSACTION_ID}}/documents' \
   --header 'Authorization: Bearer YOUR_TOKEN' \
   --form 'file=@"./invoice.pdf"'

To understand what happens after a document is uploaded — how validation runs and how it can release a transaction that is held for review — see Document validation and review.

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'

SWIFT payment status tracking

For payments sent over the SWIFT network, Caliza continuously tracks the payment and provides status updates as information becomes available from banks in the payment chain. The possible SWIFT-specific statuses are:

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