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:

Simulate the payment to get a quote.
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:

See an example request below:

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

Where:

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.
beneficiaryId: The ID of the beneficiary associated with the payment.
type: The type of payment, either "FIAT" or "CRYPTO".
destination: The ID of the recipient where the funds will be sent.
fundingMethod: The method used to fund the payment, such as "ETH".
paymentRail: The payment rail used for the transaction, such as "WIRE".

Execute the payment

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

To execute the payment using the Caliza API, 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/payments' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"simulationId": "{{simulationId}}",
"beneficiaryIp": "{{beneficiaryIp}}"
}'

Where:

simulationId: The ID of the simulation you want to execute.
beneficiaryIp: The IP address of the beneficiary initiating the payment.

Get the payment status

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

See the example request below:

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

Where payment_id is the ID of the payment you want to check.

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.