Create a Transfer
Create a new transfer.
In: header
The customer's ID.
^customer_[a-z0-9]+$The quote ID from a previously created quote. The transfer uses the locked exchange rate, currency, and network from the quote.
Integrator-defined external reference. The value is not stored as unique.
Standard floating-rate transfer. For BRL (PIX) transfers: only polygon, ethereum, base, and tron wallet networks are supported (not sol); integratorFixedFee is not allowed — use integratorBpsFeeRate instead. See BRL/PIX transfer constraints for current transfer limits.
The transfer amount in source currency. Must have exactly 2 decimal places. Transfer limits are set dynamically based on due diligence and may change over time — see BRL/PIX transfer constraints for current BRL limits.
The customer's ID.
^customer_[a-z0-9]+$The integrator fixed fee amount in source currency. Must have exactly 2 decimal places. Not supported for BRL transfers — use integratorBpsFeeRate instead.
The integrator BPS fee rate as an integer string (1 bps = 0.01%). This is the only fee mechanism supported for BRL transfers.
^\d+$Integrator-defined external reference. The value is not stored as unique.
The source of an Off-ramp transfer. See Wallets for registration.
The source type: wallet.
"wallet"The source wallet ID.
^wallet_[a-z0-9]+$The source currency for an Off-ramp transfer. This should be the currency of the wallet. See Supported Rails & Currencies.
"usdc" | "usdt" | "eurc"The source network of the customer's wallet. See Supported Rails & Currencies.
"sol" | "ethereum" | "arbitrum" | "polygon" | "base" | "avalanche" | "tron"The source of an On-ramp transfer.
The source type: bank_account.
"bank_account"The source bank account ID.
^bankAccount_[a-z0-9]+$The source currency for an On-ramp transfer. This should be the currency of the bank account. See Supported Rails & Currencies.
"usd" | "eur" | "brl"The source network of the bank account. See Supported Rails & Currencies.
"ach" | "wire" | "sepa" | "pix"The destination of an On-ramp transfer. See Wallets for registration.
The destination type: wallet.
"wallet"The destination wallet ID.
^wallet_[a-z0-9]+$The destination currency for an On-ramp transfer. This should be the currency of the wallet. See Supported Rails & Currencies.
"usdc" | "usdt" | "eurc"The destination network of the customer's wallet. See Supported Rails & Currencies.
"sol" | "ethereum" | "arbitrum" | "polygon" | "base" | "avalanche" | "tron"The destination bank account for transfers.
The destination type: bank_account.
"bank_account"The destination bank account ID.
The destination currency: [usd, eur, brl]. See Supported Rails & Currencies.
"usd" | "eur" | "brl"Reference sent to the receiving institution with ACH transfers, 1-10 characters.
1 <= length <= 10Message sent to the receiving institution with wire transfers, 1-105 characters.
1 <= length <= 105Reference sent to the receiving institution with SEPA transfers, 6-140 characters.
6 <= length <= 140The destination network: [wire, ach, achPush, achPull, achSameDay, swift, sepa, pix]. See Supported Rails & Currencies.
"ach" | "wire" | "sepa" | "pix" | "swift"Response Body
curl -X POST "https://api.spherepay.co/v2/transfer" \
-H "Content-Type: application/json" \
-d '{
"customer": "customer_1234567890",
"quoteId": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"source": {
"type": "wallet",
"id": "wallet_1234567890abcdef1234567890abcdef12345678"
},
"destination": {
"type": "wallet",
"id": "wallet_1234567890abcdef1234567890abcdef12345678"
}
}'{
"id": "payout_a1b2c3d4e5f6a7b8c9d0e1f2",
"externalId": "merchant_ref_123",
"type": "on_ramp",
"status": "pendingFunding",
"customer": "customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
"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"
}
},
"source": {
"id": "bankAccount_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"type": "bank_account"
},
"destination": {
"id": "wallet_e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
"type": "wallet",
"currency": "usdc",
"network": "sol",
"amount": "string",
"exchangeRate": "1.00"
},
"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"
}
},
"quote": {
"id": "quote_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"expiresAt": "2021-01-01T00:00:00.000Z"
},
"updated": "2021-01-01T00:00:00.000Z",
"created": "2021-01-01T00:00:00.000Z"
}{
"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"
}
]
}