Create off-ramp transfer

Overview

Transfer is a movement of funds from the local currency in a beneficiary's home country bank account to digital dollars in the same beneficiary's Caliza wallet, or vice versa. In off-ramp funds move from digital dollars to local currency.

Simulating your off-ramp (View API reference)

The first step is to create a simulation, which returns the indicative amount of funds to be received at the end of the transfer and generates a simulationId required to launch the transaction.

• Call POST /transfers/simulations with type of off_ramp , and an amount denominated in digital dollars (USDC), to create a simulation of your off-ramp transfer
• Based on the latest exchange rate, we calculate and return the likely amount to be received by the beneficiary, complete with fees and effective exchange rate

Example request to create a simulation of an off-ramp transfer:

curl --location 'https://sandbox.api.caliza.co/core-api/v1/transfers/simulations' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data '{
    "amount": {
        "currencyCode": "USDC",
        "value": 100
    },
    "beneficiaryId": "64c96cddf8aaac3956c07848",
    "type": "OFF_RAMP"
}'

{
    "id": "34c9dfe7-12da-4119-8beb-4db895c01a47",
    "integratorId": "64bea4abf8aaac3956c07844",
    "beneficiaryId": "64c96cddf8aaac3956c07848",
    "from": {
        "currencyCode": "USDC",
        "value": "100.00"
    },
    "to": {
        "currencyCode": "BRL",
        "value": "487.62"
    },
    "transactionDetails": {
        "taxes": {
            "currencyCode": "BRL",
            "value": "1.87"
        },
        "conversionDetails": {
            "effectiveTransactionValue": "4.87",
            "exchangeRate": "5.01"
        },
        "feeDetails": {
            "totalFees": {
                "currencyCode": "USD",
                "value": "2.66"
            },
            "integratorFee": {
                "currencyCode": "BRL",
                "value": "4.94"
            }
        }
    },
    "type": "OFF_RAMP",
    "executed": false
}

Creating your off-ramp (View API reference)

After simulating your off-ramp, it's time to create it for real. The only things you'll need to send are: the id of the simulation from the previous step, so in the example above, 34c9dfe7-12da-4119-8beb-4db895c01a47, and the IP from which you received the request from the beneficiary. You can leave the rest to us! This request will generate an id associated with the transfer, which you can use to check its status. We will send callbacks (detailed below) as the status changes.

• Call POST /transfers with the simulationId
• Now we create your off-ramp based on your previous simulation, which will be executed at the latest exchange rate

Example request to create an off-ramp transfer:

curl --request POST \
     --url https://sandbox.api.caliza.co/core-api/v1/transfers \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     -data-raw '{
     "simulationId": "{SIMULATION_ID}",
     "beneficiaryIp": "127.0.0.1"
}'

{
    "id": "bae5b70a-22dd-494e-9e67-55f3e2e5e938",
    "simulationId": "630bd8bfe5f4450249fffb25",
    "integratorId": "64a77197e459bc78b6585fa7",
    "beneficiaryId": "64af1510267758301e2c6c7f",
    "from": {
        "currencyCode": "USDC",
        "value": "50.00"
    },
    "to": {
        "currencyCode": "BRL",
        "value": "243.78"
    },
    "transactionDetails": {
        "taxes": {
            "currencyCode": "BRL",
            "value": "0.93"
        },
        "conversionDetails": {
            "effectiveTransactionValue": "4.87",
            "exchangeRate": "5.01"
        },
        "feeDetails": {
            "totalFees": {
                "currencyCode": "USD",
                "value": "1.33"
            },
            "integratorFee": {
                "currencyCode": "BRL",
                "value": "2.47"
            }
        }
    },
    "type": "OFF_RAMP",
    "status": "PENDING",
    "createdBy": "521353a8-90b2-4abd-abde-fcabc3b66e06",
    "createdDate": "2023-07-18T16:12:06.916270Z",
    "lastModifiedBy": "521353a8-90b2-4abd-abde-fcabc3b66e06",
    "lastModifiedDate": "2023-07-18T16:12:06.916270Z"
}

Direct Off-Ramp

In the direct collection mode, there will be an additional field in both the simulation and transfer responses that includes information that reflects the account that the off-ramp proceeds will be deposited into. We will execute the transaction, and deposit the proceeds into this account.

Further details are below based on the country/transfer method.

Pix (Brazil)

The additional field is targetPixKey. This string represents the Pix Key that has been stored and will be used as the target of the off-ramp. Please inform your beneficiaries that this payment will come from Caliza.

External Wallet Off-Ramp

Depositing Crypto

In integrations in which we don't custody the funds, after executing the transfer, we will not begin the transaction until the USDC to off-ramp arrives in our wallet. You'll need to make an on-chain transfer to the wallet address included in the returned transfer object at fundingWallet for the exact amount listed as the from value in the transfer object.

Simulate Crypto Deposit [Sandbox]

In order to simulate a crypto deposit, you'll make a request to POST /transfers/sandbox/crypto-deposit with the simulationId you used to create the transfer and the transaction hash for the simulated crypto deposit. This is the same transaction hash you will (or have) provided at PUT /transfers/{id}/transactionHash.

curl --request PUT \
     --url https://sandbox.api.caliza.co/core-api/v1/transfers\sandbox\crypto-deposit \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     -data-raw '{
     "txHash": "17267593-c4da-4ccd-8e33-70c2724cc1e5",
     "simulationId": "630bd8bfe5f4450249fffb25"
}'

Attaching the Transaction Hash of the Deposit

In order for us to link the USDC you deposit with the appropriate transfer, you will need to update the transfer with the transaction hash of your deposit by calling PUT /transfers/{id}/transactionHash. We will largely trust this relationship, but will validate the amounts.

Example transactionHash request:

curl --request PUT \
     --url https://sandbox.api.caliza.co/core-api/v1/transfers\{id}\transactionHash \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     -data-raw '{
     "transactionHash": "17267593-c4da-4ccd-8e33-70c2724cc1e5"
}'

You will receive the transfer object as the response.

Immediately upon the completion of the linked transaction and upon confirming the appropriate values, we will execute the transaction and continue with the rest of the off-ramp.

Checking the progress of your off-ramp (View API reference)

Call GET /transfers/{id} to check the status of your transfer.

Possible status responses are: pending, succeeded, failed, and cancelled.

You'll receive the same response as above, with changing statuses and actual transaction value details rather than estimates, as the transfer progresses.

❗️

FYI

We take several internal steps before marking a transfer as succeeded, and the complete payload will only be available once the status is succeeded. Before then, it's possible to receive a response without the transactionDetails and to fields.

Callback notification

As soon as a new off-ramp is completed, a callback is sent to the integrator URL:

{
	"operation": "OFF_RAMP",
  "resource": "transfers",
  "resourceId": "6306548828912548710e667c",
  "createdAt": "2022-08-02T15:51:49.119+00:00",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "succeeded": false,
  "error": "Something went wrong"
}

{
	"operation": "OFF_RAMP",
  "resourceId": "6306548828912548710e667c",
  "createdAt": "2022-08-02T15:51:49.119+00:00",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "success": false,
  "message": "Beneficiary doesn't have funds"

{
	"operation": "OFF_RAMP",
  "resourceId": "6306548828912548710e667c",
  "createdAt": "2022-08-02T15:51:49.119+00:00",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "success": true