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",
  "destination": {
    "id": "wallet_1234567890abcdef1234567890abcdef12345678",
    "type": "wallet"
  },
  "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "source": {
    "id": "wallet_1234567890abcdef1234567890abcdef12345678",
    "type": "wallet"
  },
  "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "externalId": "merchant_ref_123",
  "paymentDescription": "INV-2026-004 - Q1 software services",
  "paymentReason": "professional_services",
  "referenceSide": "<unknown>",
  "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
'

import requests

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

payload = {
    "customer": "customer_1234567890",
    "destination": {
        "id": "wallet_1234567890abcdef1234567890abcdef12345678",
        "type": "wallet"
    },
    "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "source": {
        "id": "wallet_1234567890abcdef1234567890abcdef12345678",
        "type": "wallet"
    },
    "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "externalId": "merchant_ref_123",
    "paymentDescription": "INV-2026-004 - Q1 software services",
    "paymentReason": "professional_services",
    "referenceSide": "<unknown>",
    "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
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',
    destination: {id: 'wallet_1234567890abcdef1234567890abcdef12345678', type: 'wallet'},
    quoteId: 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    source: {id: 'wallet_1234567890abcdef1234567890abcdef12345678', type: 'wallet'},
    documentId: 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    externalId: 'merchant_ref_123',
    paymentDescription: 'INV-2026-004 - Q1 software services',
    paymentReason: 'professional_services',
    referenceSide: '<unknown>',
    returnAddress: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  })
};

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',
    'destination' => [
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678',
        'type' => 'wallet'
    ],
    'quoteId' => 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'source' => [
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678',
        'type' => 'wallet'
    ],
    'documentId' => 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'externalId' => 'merchant_ref_123',
    'paymentDescription' => 'INV-2026-004 - Q1 software services',
    'paymentReason' => 'professional_services',
    'referenceSide' => '<unknown>',
    'returnAddress' => '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  ]),
  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  \"destination\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"paymentReason\": \"professional_services\",\n  \"referenceSide\": \"<unknown>\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\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  \"destination\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"paymentReason\": \"professional_services\",\n  \"referenceSide\": \"<unknown>\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\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  \"destination\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"paymentReason\": \"professional_services\",\n  \"referenceSide\": \"<unknown>\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}"

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

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

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

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

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

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",
  "destination": {
    "id": "wallet_1234567890abcdef1234567890abcdef12345678",
    "type": "wallet"
  },
  "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "source": {
    "id": "wallet_1234567890abcdef1234567890abcdef12345678",
    "type": "wallet"
  },
  "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "externalId": "merchant_ref_123",
  "paymentDescription": "INV-2026-004 - Q1 software services",
  "paymentReason": "professional_services",
  "referenceSide": "<unknown>",
  "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
'

import requests

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

payload = {
    "customer": "customer_1234567890",
    "destination": {
        "id": "wallet_1234567890abcdef1234567890abcdef12345678",
        "type": "wallet"
    },
    "quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "source": {
        "id": "wallet_1234567890abcdef1234567890abcdef12345678",
        "type": "wallet"
    },
    "documentId": "document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "externalId": "merchant_ref_123",
    "paymentDescription": "INV-2026-004 - Q1 software services",
    "paymentReason": "professional_services",
    "referenceSide": "<unknown>",
    "returnAddress": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
}
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',
    destination: {id: 'wallet_1234567890abcdef1234567890abcdef12345678', type: 'wallet'},
    quoteId: 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    source: {id: 'wallet_1234567890abcdef1234567890abcdef12345678', type: 'wallet'},
    documentId: 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    externalId: 'merchant_ref_123',
    paymentDescription: 'INV-2026-004 - Q1 software services',
    paymentReason: 'professional_services',
    referenceSide: '<unknown>',
    returnAddress: '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  })
};

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',
    'destination' => [
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678',
        'type' => 'wallet'
    ],
    'quoteId' => 'quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'source' => [
        'id' => 'wallet_1234567890abcdef1234567890abcdef12345678',
        'type' => 'wallet'
    ],
    'documentId' => 'document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'externalId' => 'merchant_ref_123',
    'paymentDescription' => 'INV-2026-004 - Q1 software services',
    'paymentReason' => 'professional_services',
    'referenceSide' => '<unknown>',
    'returnAddress' => '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  ]),
  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  \"destination\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"paymentReason\": \"professional_services\",\n  \"referenceSide\": \"<unknown>\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\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  \"destination\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"paymentReason\": \"professional_services\",\n  \"referenceSide\": \"<unknown>\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\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  \"destination\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"quoteId\": \"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"source\": {\n    \"id\": \"wallet_1234567890abcdef1234567890abcdef12345678\",\n    \"type\": \"wallet\"\n  },\n  \"documentId\": \"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\",\n  \"externalId\": \"merchant_ref_123\",\n  \"paymentDescription\": \"INV-2026-004 - Q1 software services\",\n  \"paymentReason\": \"professional_services\",\n  \"referenceSide\": \"<unknown>\",\n  \"returnAddress\": \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n}"

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

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

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

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

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

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"

destination

object

required

Show child attributes

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

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"

externalId

string

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

Example:

"merchant_ref_123"

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"

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"

referenceSide

any

returnAddress

string

Crypto address where funds are returned on failed transactions. Must be 1-255 characters and valid for the source network.

Example:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

Response

created

string<date-time>

required

The datetime the transfer was created.

Example:

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

customer

string

required

The customer ID.

Example:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

depositAccount

Deposit Bank Account · object

required

The deposit bank account for an on ramp transfer.

Deposit Bank Account
Deposit Wallet

Show child attributes

destination

Destination Wallet · object

required

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

Destination Wallet
Destination Bank Account

Show child attributes

string

required

A unique identifier for transfer.

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

Example:

"payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

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"
}

status

enum<string>

required

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

Available options:

pendingFunding,

pendingReview,

fundsReceived,

processing,

succeeded,

undeliverable,

returned,

processingRefund,

refundFailed,

pendingRefundInformation,

failed,

canceled,

refunded,

unexpectedError,

failedPrecondition,

expired,

unfunded

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"
  }
]

type

enum<string>

required

The transfer type.

Available options:

on_ramp,

off_ramp,

fiat_to_fiat,

unmatched_deposit,

microdeposit

Example:

"on_ramp"

updated

string<date-time>

required

The last datetime the transfer was updated.

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

fundingDeadline

string<date-time>

The datetime by which the deposit must arrive into the deposit account. A later deposit is not applied to this transfer. Present only on bank-funded transfers that have a deadline. Distinct from quote.expiresAt, which is the expiry of the quoted rate.

Example:

"2026-11-03T12:00:00.000Z"

paymentDescription

string

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

Example:

"INV-2026-004 - Q1 software services"

paymentReason

string

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

Example:

"professional_services"

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

returnAddress

string

Crypto wallet address where funds are sent if the transfer fails or is refunded. Only present on off-ramp transfers created with a custom return address.

Example:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

Last modified on June 18, 2026

Onboarding

Accounts

Money movement

Webhooks

Create an On-Ramp or Off-Ramp Transfer

Authorizations

Body

Response