Create an On-Ramp or Off-Ramp Transfer

Create a Transfer

curl --request POST \
  --url https://api.spherepay.co/v2/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "customer_1234567890",
  "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "source": {
    "type": "wallet",
    "id": "wallet_1234567890abcdef1234567890abcdef12345678"
  },
  "destination": {
    "type": "wallet",
    "id": "wallet_1234567890abcdef1234567890abcdef12345678"
  },
  "externalId": "merchant_ref_123",
  "paymentReason": "professional_services",
  "paymentDescription": "INV-2026-004 - Q1 software services",
  "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}
'

import requests

url = "https://api.spherepay.co/v2/transfer"

payload = {
    "customer": "customer_1234567890",
    "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "source": {
        "type": "wallet",
        "id": "wallet_1234567890abcdef1234567890abcdef12345678"
    },
    "destination": {
        "type": "wallet",
        "id": "wallet_1234567890abcdef1234567890abcdef12345678"
    },
    "externalId": "merchant_ref_123",
    "paymentReason": "professional_services",
    "paymentDescription": "INV-2026-004 - Q1 software services",
    "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer: 'customer_1234567890',
    quoteId: 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    source: {type: 'wallet', id: 'wallet_1234567890abcdef1234567890abcdef12345678'},
    destination: {type: 'wallet', id: 'wallet_1234567890abcdef1234567890abcdef12345678'},
    externalId: 'merchant_ref_123',
    paymentReason: 'professional_services',
    paymentDescription: 'INV-2026-004 - Q1 software services',
    documentId: 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'
  })
};

fetch('https://api.spherepay.co/v2/transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => 'customer_1234567890',
    'quoteId' => 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'source' => [
        'type' => 'wallet',
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678'
    ],
    'destination' => [
        'type' => 'wallet',
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678'
    ],
    'externalId' => 'merchant_ref_123',
    'paymentReason' => 'professional_services',
    'paymentDescription' => 'INV-2026-004 - Q1 software services',
    'documentId' => 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/transfer"

	payload := strings.NewReader("{\n  \"customer\": \"customer_1234567890\",\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"destination\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentReason\": \"professional_services\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/transfer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer\": \"customer_1234567890\",\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"destination\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentReason\": \"professional_services\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/transfer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer\": \"customer_1234567890\",\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"destination\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentReason\": \"professional_services\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "payout_a1b2c3d4e5f6a7b8c9d0e1f2",
  "type": "on_ramp",
  "status": "pendingFunding",
  "statusHistory": [
    {
      "status": "pendingFunding",
      "transitionedAt": "2026-06-20T14:03:21.000Z"
    },
    {
      "status": "processing",
      "transitionedAt": "2026-06-20T14:05:10.000Z"
    }
  ],
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "<string>",
    "exchangeRate": "5.455"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "John Doe",
      "accountType": "savings",
      "accountNumber": "1234567890",
      "routingNumber": "1234567890",
      "bic": "1234567890",
      "iban": "1234567890",
      "pixKey": "+5511999999999",
      "brCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "bankAddress": "123 Main St, Anytown, USA",
      "beneficiaryAddress": "123 Main St, Anytown, USA",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "updated": "2021-01-01T00:00:00.000Z",
  "created": "2021-01-01T00:00:00.000Z",
  "externalId": "merchant_ref_123",
  "fees": {
    "integratorFee": {
      "fixedAmount": "1.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "1.10",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "2.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "2.10",
      "currency": "usd"
    }
  },
  "quote": {
    "id": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "expiresAt": "2021-01-01T00:00:00.000Z"
  },
  "paymentReason": "professional_services",
  "paymentDescription": "INV-2026-004 - Q1 software services"
}

{
  "status": 400,
  "detail": "Invalid request parameters",
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 404,
  "detail": "Resource not found",
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 422,
  "detail": "Validation failed",
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}

Create a Transfer

curl --request POST \
  --url https://api.spherepay.co/v2/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "customer_1234567890",
  "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "source": {
    "type": "wallet",
    "id": "wallet_1234567890abcdef1234567890abcdef12345678"
  },
  "destination": {
    "type": "wallet",
    "id": "wallet_1234567890abcdef1234567890abcdef12345678"
  },
  "externalId": "merchant_ref_123",
  "paymentReason": "professional_services",
  "paymentDescription": "INV-2026-004 - Q1 software services",
  "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}
'

import requests

url = "https://api.spherepay.co/v2/transfer"

payload = {
    "customer": "customer_1234567890",
    "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "source": {
        "type": "wallet",
        "id": "wallet_1234567890abcdef1234567890abcdef12345678"
    },
    "destination": {
        "type": "wallet",
        "id": "wallet_1234567890abcdef1234567890abcdef12345678"
    },
    "externalId": "merchant_ref_123",
    "paymentReason": "professional_services",
    "paymentDescription": "INV-2026-004 - Q1 software services",
    "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer: 'customer_1234567890',
    quoteId: 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    source: {type: 'wallet', id: 'wallet_1234567890abcdef1234567890abcdef12345678'},
    destination: {type: 'wallet', id: 'wallet_1234567890abcdef1234567890abcdef12345678'},
    externalId: 'merchant_ref_123',
    paymentReason: 'professional_services',
    paymentDescription: 'INV-2026-004 - Q1 software services',
    documentId: 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'
  })
};

fetch('https://api.spherepay.co/v2/transfer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => 'customer_1234567890',
    'quoteId' => 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'source' => [
        'type' => 'wallet',
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678'
    ],
    'destination' => [
        'type' => 'wallet',
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678'
    ],
    'externalId' => 'merchant_ref_123',
    'paymentReason' => 'professional_services',
    'paymentDescription' => 'INV-2026-004 - Q1 software services',
    'documentId' => 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/transfer"

	payload := strings.NewReader("{\n  \"customer\": \"customer_1234567890\",\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"destination\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentReason\": \"professional_services\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/transfer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer\": \"customer_1234567890\",\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"destination\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentReason\": \"professional_services\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/transfer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer\": \"customer_1234567890\",\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"destination\": {\n    \"type\": \"wallet\",\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\"\n  },\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentReason\": \"professional_services\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "payout_a1b2c3d4e5f6a7b8c9d0e1f2",
  "type": "on_ramp",
  "status": "pendingFunding",
  "statusHistory": [
    {
      "status": "pendingFunding",
      "transitionedAt": "2026-06-20T14:03:21.000Z"
    },
    {
      "status": "processing",
      "transitionedAt": "2026-06-20T14:05:10.000Z"
    }
  ],
  "customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "source": {
    "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "type": "bank_account"
  },
  "destination": {
    "id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "type": "wallet",
    "currency": "usdc",
    "network": "sol",
    "amount": "<string>",
    "exchangeRate": "5.455"
  },
  "depositAccount": {
    "type": "bank_account",
    "bankDetails": {
      "bankName": "Bank of America",
      "accountHolderName": "John Doe",
      "accountType": "savings",
      "accountNumber": "1234567890",
      "routingNumber": "1234567890",
      "bic": "1234567890",
      "iban": "1234567890",
      "pixKey": "+5511999999999",
      "brCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "bankAddress": "123 Main St, Anytown, USA",
      "beneficiaryAddress": "123 Main St, Anytown, USA",
      "memo": "BBE6C7EB4A3F"
    }
  },
  "updated": "2021-01-01T00:00:00.000Z",
  "created": "2021-01-01T00:00:00.000Z",
  "externalId": "merchant_ref_123",
  "fees": {
    "integratorFee": {
      "fixedAmount": "1.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "1.10",
      "currency": "usd"
    },
    "platformFee": {
      "fixedAmount": "2.00",
      "bpsRate": "10",
      "bpsAmount": "0.10",
      "totalAmount": "2.10",
      "currency": "usd"
    }
  },
  "quote": {
    "id": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "expiresAt": "2021-01-01T00:00:00.000Z"
  },
  "paymentReason": "professional_services",
  "paymentDescription": "INV-2026-004 - Q1 software services"
}

{
  "status": 400,
  "detail": "Invalid request parameters",
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 404,
  "detail": "Resource not found",
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 422,
  "detail": "Validation failed",
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}

Use this endpoint to initiate a money movement for a verified customer. SpherePay supports two transfer directions: on-ramp (fiat → crypto) and off-ramp (crypto → fiat). You define the direction by the types you supply for source and destination — a bank_account source with a wallet destination creates an on-ramp, and the reverse creates an off-ramp. The response includes deposit instructions your customer needs to fund the transfer.

The customer must have an approved verification profile before you can create a transfer on their behalf.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Transfer with Quote
Transfer

customer

string

required

The customer's ID.

Pattern: ^customer_[a-z0-9]+$

Example:

"customer_1234567890"

quoteId

string

required

The quote ID from a previously created quote. The transfer uses the locked exchange rate, currency, and network from the quote.

Example:

"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

source

object

required

Show child attributes

destination

object

required

Show child attributes

externalId

string

Integrator-defined external reference. The value is not stored as unique.

Example:

"merchant_ref_123"

paymentReason

enum<string>

The reason for the payment. Required for SWIFT transfers, BRL transfers, and for third-party off-ramp transfers (where the destination bank account owner relationship is not self).

Available options:

personal,

investment,

real_estate,

tax,

loan,

bills,

reimbursement,

professional_services,

family_support,

education,

rent,

donation,

gift,

insurance,

medical,

savings,

travel,

mortgage,

fine,

dividend,

agriculture,

import_export,

art,

other

Example:

"professional_services"

paymentDescription

string

A free-text description of the payment purpose. Required for third-party off-ramp transfers (where the destination bank account owner relationship is not self). Max 500 characters.

Required string length: 1 - 500

Example:

"INV-2026-004 - Q1 software services"

documentId

string

ID of a pre-uploaded supporting document (from POST /v2/document with target transfer). Required for third-party transfers on certain routes. A transfer is considered third-party when the destination bank account owner is not the customer themselves (i.e. the bank account relationship is not self). The document should evidence the purpose of the transfer - for example, an invoice, contract, payment agreement, or proof of services rendered.

Minimum string length: 1

Pattern: ^document_[a-z0-9]+$

Example:

"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Response

string

required

A unique identifier for transfer.

Pattern: ^payout_[a-z0-9]{24}$

Example:

"payout_a1b2c3d4e5f6a7b8c9d0e1f2"

type

enum<string>

required

The transfer type.

Available options:

on_ramp,

off_ramp,

unmatched_deposit,

microdeposit

Example:

"on_ramp"

status

enum<string>

required

The transfer status. See Transfer Lifecycle for status definitions and transitions.

Available options:

pendingFunding,

pendingReview,

fundsReceived,

processing,

succeeded,

undeliverable,

returned,

pendingRefundInformation,

failed,

canceled,

refunded,

unexpectedError,

failedPrecondition,

expired

Example:

"pendingFunding"

statusHistory

Transfer Status History Entry · object[]

required

Timeline of status transitions for this transfer, ascending by transitionedAt.

Show child attributes

Example:

[
  {
    "status": "pendingFunding",
    "transitionedAt": "2026-06-20T14:03:21.000Z"
  },
  {
    "status": "processing",
    "transitionedAt": "2026-06-20T14:05:10.000Z"
  }
]

customer

string

required

The customer ID.

Example:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

source

Source Bank Account · object

required

The source of an on ramp transfer.

Source Bank Account
Source Wallet

Show child attributes

Example:

{
  "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "type": "bank_account"
}

destination

Destination Wallet · object

required

The destination of an On-ramp transfer. See Wallets for registration.

Destination Wallet
Destination Bank Account

Show child attributes

depositAccount

Deposit Bank Account · object

required

The deposit bank account for an on ramp transfer.

Deposit Bank Account
Deposit Wallet

Show child attributes

updated

string<date-time>

required

The last datetime the transfer was updated.

Example:

"2021-01-01T00:00:00.000Z"

created

string<date-time>

required

The datetime the transfer was created.

Example:

"2021-01-01T00:00:00.000Z"

externalId

string

The external reference (not stored as unique).

Example:

"merchant_ref_123"

fees

object

Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete.

Show child attributes

quote

object

The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate.

Show child attributes

paymentReason

string

The reason for the payment. Present on BRL transfers and third-party off-ramp transfers.

Example:

"professional_services"

paymentDescription

string

A free-text description of the payment purpose. Present on third-party off-ramp transfers.

Example:

"INV-2026-004 - Q1 software services"

Last modified on June 18, 2026

Delete Wallet List Transfers

⌘I

Onboarding

Accounts

Money movement

Create an On-Ramp or Off-Ramp Transfer

Authorizations

Body

Response