Saltar al contenido principal
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",
  "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"
    }
  ]
}
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
​
customer
string
requerido

The customer's ID.

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

"customer_1234567890"

​
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
​
destination
object
requerido
​
externalId
string

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

Ejemplo:

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

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"

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

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

Respuesta

​
id
string
requerido

A unique identifier for transfer.

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

"payout_a1b2c3d4e5f6a7b8c9d0e1f2"

​
type
enum<string>
requerido

The transfer type.

Opciones disponibles:
on_ramp,
off_ramp,
unmatched_deposit,
microdeposit
Ejemplo:

"on_ramp"

​
status
enum<string>
requerido

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

Opciones disponibles:
pendingFunding,
pendingReview,
fundsReceived,
processing,
succeeded,
undeliverable,
returned,
pendingRefundInformation,
failed,
canceled,
refunded,
unexpectedError,
failedPrecondition,
expired
Ejemplo:

"pendingFunding"

​
customer
string
requerido

The customer ID.

Ejemplo:

"customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7"

​
source
Source Bank Account · object
requerido

The source of an on ramp transfer.

Ejemplo:
{
  "id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "type": "bank_account"
}
​
destination
Destination Wallet · object
requerido

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

​
depositAccount
Deposit Bank Account · object
requerido

The deposit bank account for an on ramp transfer.

​
updated
string<date-time>
requerido

The last datetime the transfer was updated.

Ejemplo:

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

​
created
string<date-time>
requerido

The datetime the transfer was created.

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.

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

​
paymentReason
string

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

Ejemplo:

"professional_services"

​
paymentDescription
string

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

Ejemplo:

"INV-2026-004 — Q1 software services"

Última modificación el 22 de junio de 2026