Crear una Transferencia On-Ramp u Off-Ramp

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
}

Usa este endpoint para iniciar un movimiento de dinero para un cliente verificado. SpherePay soporta dos direcciones de transferencia: on-ramp (fiat → cripto) y off-ramp (cripto → fiat). Defines la dirección por los tipos que suministras para source y destination — una fuente bank_account con un destino wallet crea un on-ramp, y el inverso crea un off-ramp. La respuesta incluye instrucciones de depósito que tu cliente necesita para financiar la transferencia.

El cliente debe tener un perfil de verificación approved antes de que puedas crear una transferencia en su nombre.

Autorizaciones

Authorization

string

header

requerido

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

Cuerpo

application/json

Transfer with Quote
Transfer

customer

string

requerido

The customer's ID.

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

Ejemplo:

"customer_1234567890"

destination

object

requerido

Show child attributes

quoteId

string

requerido

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

Ejemplo:

"quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

source

object

requerido

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]+$

Ejemplo:

"document_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

externalId

string

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

Ejemplo:

"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

Ejemplo:

"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).

Opciones disponibles:

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

Ejemplo:

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

Ejemplo:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

Respuesta

created

string<date-time>

requerido

The datetime the transfer was created.

Ejemplo:

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

customer

string

requerido

The customer ID.

Ejemplo:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

depositAccount

Deposit Bank Account · object

requerido

The deposit bank account for an on ramp transfer.

Deposit Bank Account
Deposit Wallet

Show child attributes

destination

Destination Wallet · object

requerido

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

Destination Wallet
Destination Bank Account

Show child attributes

string

requerido

A unique identifier for transfer.

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

Ejemplo:

"payout_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

source

Source Bank Account · object

requerido

The source of an on ramp transfer.

Source Bank Account
Source Wallet

Show child attributes

Ejemplo:

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

status

enum<string>

requerido

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

Opciones disponibles:

pendingFunding,

pendingReview,

fundsReceived,

processing,

succeeded,

undeliverable,

returned,

processingRefund,

refundFailed,

pendingRefundInformation,

failed,

canceled,

refunded,

unexpectedError,

failedPrecondition,

expired,

unfunded

Ejemplo:

"pendingFunding"

statusHistory

Transfer Status History Entry · object[]

requerido

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

Show child attributes

Ejemplo:

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

type

enum<string>

requerido

The transfer type.

Opciones disponibles:

on_ramp,

off_ramp,

fiat_to_fiat,

unmatched_deposit,

microdeposit

Ejemplo:

"on_ramp"

updated

string<date-time>

requerido

The last datetime the transfer was updated.

Ejemplo:

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

externalId

string

The external reference (not stored as unique).

Ejemplo:

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

Ejemplo:

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

paymentDescription

string

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

Ejemplo:

"INV-2026-004 - Q1 software services"

paymentReason

string

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

Ejemplo:

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

Ejemplo:

"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"

Última modificación el 22 de junio de 2026

Incorporación

Cuentas

Movimiento de dinero

Webhooks

Crear una Transferencia On-Ramp u Off-Ramp

Autorizaciones

Cuerpo

Respuesta