Send Your First Payment

This guide provides a step-by-step walkthrough of the complete transaction lifecycle. Follow the instructions below to set up a recipient, and perform a successful currency conversion and transfer using the Caliza API.

Prerequisites

To perform a payment transaction, you'll need:

• Authentication token: An access token to authenticate your requests. To learn how to generate one, refer to the Authenticate with the Caliza API documentation.
• Beneficiary: A beneficiary, business or individual, must be created and have completed the Caliza KYX process before you can create recipients or send payments. The beneficiary represents the entity that will execute the transactions. To learn how to create a beneficiary, refer to the Create Beneficiaries documentation.

Create a Recipient

A recipient defines the external bank account where funds will be sent. Recipients are required for payment transactions and must be created before executing a payment. To create a recipient, send a POST request to /v1/recipients. For detailed information about recipient types, required fields, and examples, refer to the Create Recipients documentation.

curl --location 'https://api.sandbox.caliza.com/core-api/v1/recipients' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "individualName": "{{INDIVIDUAL_NAME}}",
  "currency": "{{CURRENCY}}",
  "type": "WIRE",
  "details": {
    "bankName": "{{BANK_NAME}}",
    "routingNumber": "{{ROUTING_NUMBER}}",
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "recipientAddress": { "city": "{{CITY}}", "state": "{{STATE}}", "country": "{{COUNTRY}}" },
    "bankAddress": { "city": "{{BANK_CITY}}", "state": "{{BANK_STATE}}", "country": "{{BANK_COUNTRY}}" }
  }
}'

Simulate & Execute a Payment

Now that your recipient is defined, simulate a conversion of USDC (USD Coin, a stablecoin) from crypto to a wire payout in USD (United States Dollar. For more information about this process, access the Manage Payments page

Simulate the Transaction

First, create a simulation for the payment. This calculates the exchange rate and fees. To create a Simulation, you'll need to make a request to the simulations endpoint.

curl --location 'https://api.sandbox.caliza.com/core-api/v1/simulations' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
    "from": { "currencyCode": "USDC", "value": 100 },
    "to": { "currencyCode": "USD" },
    "beneficiaryId": "{{BENEFICIARY_ID}}",
    "type": "FIAT",
    "destination": "{{RECIPIENT_ID}}",
    "paymentRail": "WIRE"
}'

{
  "id": "{{SIMULATION_ID}}",
  "beneficiaryId": "{{BENEFICIARY_ID}}",
  "from": {
    "currencyCode": "{{FROM_CURRENCY}}",
    "value": {{FROM_VALUE}}
  },
  "to": {
    "currencyCode": "{{TO_CURRENCY}}",
    "value": {{TO_VALUE}}
  },
  "transactionDetails": {
    "conversionDetails": {
      "effectiveTransactionValue": {{EFFECTIVE_VALUE}},
      "marketExchangeRate": {{EXCHANGE_RATE}}
    },
    "feeDetails": {
      "totalFees": {
        "currencyCode": "{{FEE_CURRENCY}}",
        "value": {{FEE_VALUE}}
      }
    }
  },
  "expiresAt": "{{EXPIRES_AT}}"
}

📘

ID from response

Copy the id from the response, such as 34c9dfe7....

Execute the Transaction

Confirm the payment using the simulation ID. To confirm the Payment, you'll need to make a request to the /payments/ endpoint using the simulationID.

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

{
  "id": "{{TRANSACTION_ID}}",
  "simulationId": "{{SIMULATION_ID}}",
  "status": "{{STATUS}}",
  "from": {
    "currencyCode": "{{FROM_CURRENCY}}",
    "value": {{FROM_VALUE}}
  },
  "to": {
    "currencyCode": "{{TO_CURRENCY}}",
    "value": {{TO_VALUE}}
  },
  "flowOfFundsId": "{{FLOW_OF_FUNDS_ID}}",
  "createdDate": "{{CREATED_DATE}}"
}

📘

Transaction successful created

You receive a transaction object with status CREATED or PROCESSING. The system will now execute the funds movement.

Track Payment Status

After executing a payment, you can track its status using one of the following methods:

Method 1: Polling via API

Retrieve the current status of a payment by calling the GET /v1/payments/{id} endpoint with the transaction ID from the response.

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

The response includes the current status field, which can be one of the following values:

Method 2: Webhook Notifications

Caliza can send webhook notifications when payment status changes. The TRANSACTION_COMPLETED webhook is sent when a payment transaction completes successfully. Configure your webhook endpoint to receive real-time status updates. For more information about webhook configuration and available events, refer to (placeholder for webhook documentation page)

Related Articles