Create on-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 on-ramp funds move from local currency to digital dollars.

Simulating your on-ramp (View API reference)

The first step is to create a simulation, which returns the indicative amount of USDC 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 on_ramp , and an amount denominated in the home currency, to create a simulation of your on-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 on-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": "BRL",
        "value": 100
    },
    "beneficiaryId": "64c96cddf8aaac3956c07848",
    "type": "ON_RAMP"
}'

{
  "id": "833099d6-1a85-40ee-ae2d-50fdac641844",
  "integratorId": "64bea4abf8aaac3956c07844",
  "beneficiaryId": "64c96cddf8aaac3956c07848",
  "from": {
    "currencyCode": "BRL",
    "value": "100.00"
  },
  "to": {
    "currencyCode": "USDC",
    "value": "19.41"
  },
  "transactionDetails": {
    "taxes": {
      "currencyCode": "BRL",
      "value": "0.37"
    },
    "conversionDetails": {
      "effectiveTransactionValue": "5.14",
      "exchangeRate": "5.01"
    },
    "feeDetails": {
      "totalFees": {
        "currencyCode": "BRL",
        "value": "2.71"
      },
      "integratorFee": {
        "currencyCode": "BRL",
        "value": "1.00"
      }
    }
  },
  "type": "ON_RAMP",
  "executed": false
}

Creating your on-ramp (View API reference)

After simulating your on-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, 833099d6-1a85-40ee-ae2d-50fdac641844, 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 on-ramp based on your previous simulation, which will be executed at the latest exchange rate

Example request to create an on-ramp transfer:

curl --request POST \
     --url https://sandbox.api.caliza.co/core-api/v1/transfers \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     -data-raw '{
     "simulationId": "833099d6-1a85-40ee-ae2d-50fdac641844",
     "beneficiaryIp": "127.0.0.1"
}'

{
    "id": "5d097212-9902-4d86-beec-c578640105f4",
    "simulationId": "833099d6-1a85-40ee-ae2d-50fdac641844",
    "integratorId": "64bea4abf8aaac3956c07844",
    "beneficiaryId": "64c96cddf8aaac3956c07848",
    "from": {
        "currencyCode": "BRL",
        "value": "100.00"
    },
    "to": {
        "currencyCode": "USDC",
        "value": "19.41"
    },
    "transactionDetails": {
        "taxes": {
            "currencyCode": "BRL",
            "value": "0.37"
        },
        "conversionDetails": {
            "effectiveTransactionValue": "5.14",
            "exchangeRate": "5.01"
        },
        "feeDetails": {
            "totalFees": {
                "currencyCode": "BRL",
                "value": "2.71"
            },
            "integratorFee": {
                "currencyCode": "BRL",
                "value": "1.00"
            }
        }
    },
    "type": "ON_RAMP",
    "status": "PENDING",
    "createdBy": "4b37bebd-6453-4078-8511-f41daf92fba0",
    "createdDate": "2023-08-02T02:35:45.454487Z",
    "lastModifiedBy": "4b37bebd-6453-4078-8511-f41daf92fba0",
    "lastModifiedDate": "2023-08-02T02:35:45.454487Z"
}

Direct On Ramp

In the direct collection mode, there will be an additional field that includes information that you will need to pass on to the beneficiary for them to make a transfer to Caliza in order to initiate the on-ramp. We will execute the FX transaction and begin the on-ramp as soon as we receive the transfer.

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

Pix (Brazil)

The additional field is pixCopyAndPaste. This string should be provided directly to the beneficiary with instructions for them to use it to initiate a Pix transfer from their bank. You should ensure that the beneficiary knows that the receiving entity for the transfer will be Caliza.

Create Fake Pix In [Sandbox Only]

Pix deposits can only be received in production, so in sandbox, you can fake a Pix Deposit In using the POST /transfers/sandbox/pix endpoint, shown below. You'll need to pass the CPF or CNPJ of the beneficiary in document field as part of the request.

This endpoint is enabled only on sandbox

curl --request POST \
     --url 'https://sandbox.api.caliza.co/core-api/v1/transfers/sandbox/pix' \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     --data '{
    "document": "129543596",
    "simulationId": "833099d6-1a85-40ee-ae2d-50fdac641844"
}'

Checking on the progress of on-ramp (View API reference)

Call GET /transfer/{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.

curl --request GET \
     --url 'https://sandbox.api.caliza.co/core-api/v1/transfers/{id}' \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \

Callback notification

As soon as a new onramp is completed, a callback is sent to the integrator URL:

{
	"operation": "TRANSFER_ONRAMP",
  "resourceId": "6306548828912548710e667c",
  "createdAt": "2022-08-02T15:51:49.119+00:00",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "success": false,
  "message": "Something went wrong"
}

{
	"operation": "ON_RAMP",
	"resourceId": "632a208b806bd70097197367",
	"createdAt": "2022-09-20T17:20:28.93589",
	"integratorId": "6306548828912548710e667c",
	"beneficiaryId": "6306556b28912548710e667e",
	"message": null,
	"success": true,
	"data": {
		"id": "632a208b806bd70097197367",
		"simulationId": "632a2088806bd70097197366",
		"integratorId": "6306548828912548710e667c",
		"beneficiaryId": "6306556b28912548710e667e",
		"from": {
			"currencyId": "630e2cdea794547d4b80e3f9",
			"currencyCode": "COP",
			"value": 3000
		},
		"to": {
			"currencyId": "6227f5d27f58553906108dab",
			"currencyCode": "USDC",
			"value": 0.68
		},
		"type": "ON_RAMP",
		"status": "SUCCEEDED"
	}
}

Overview

Simulating your on-ramp (View API reference)

Creating your on-ramp (View API reference)

Direct On Ramp

Pix (Brazil)

Create Fake Pix In [Sandbox Only]

Checking on the progress of on-ramp (View API reference)

❗️FYI

Callback notification

❗️
FYI