Create a Bank Account
curl --request POST \
--url https://api.spherepay.co/v2/bank-account \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"accountDetails": "<unknown>",
"accountName": "Checking Account",
"accountOwner": {
"accountHolderName": "Sarah Johnson",
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"relationship": "self"
},
"bankName": "Bank of America",
"currency": "usd",
"customerId": "customer_66c4168d418a410eae282b83883bdc39",
"networks": [
"wire",
"ach"
]
}
'import requests
url = "https://api.spherepay.co/v2/bank-account"
payload = {
"accountDetails": "<unknown>",
"accountName": "Checking Account",
"accountOwner": {
"accountHolderName": "Sarah Johnson",
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"relationship": "self"
},
"bankName": "Bank of America",
"currency": "usd",
"customerId": "customer_66c4168d418a410eae282b83883bdc39",
"networks": ["wire", "ach"]
}
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({
accountDetails: '<unknown>',
accountName: 'Checking Account',
accountOwner: {
accountHolderName: 'Sarah Johnson',
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
relationship: 'self'
},
bankName: 'Bank of America',
currency: 'usd',
customerId: 'customer_66c4168d418a410eae282b83883bdc39',
networks: ['wire', 'ach']
})
};
fetch('https://api.spherepay.co/v2/bank-account', 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/bank-account",
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([
'accountDetails' => '<unknown>',
'accountName' => 'Checking Account',
'accountOwner' => [
'accountHolderName' => 'Sarah Johnson',
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'relationship' => 'self'
],
'bankName' => 'Bank of America',
'currency' => 'usd',
'customerId' => 'customer_66c4168d418a410eae282b83883bdc39',
'networks' => [
'wire',
'ach'
]
]),
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/bank-account"
payload := strings.NewReader("{\n \"accountDetails\": \"<unknown>\",\n \"accountName\": \"Checking Account\",\n \"accountOwner\": {\n \"accountHolderName\": \"Sarah Johnson\",\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"relationship\": \"self\"\n },\n \"bankName\": \"Bank of America\",\n \"currency\": \"usd\",\n \"customerId\": \"customer_66c4168d418a410eae282b83883bdc39\",\n \"networks\": [\n \"wire\",\n \"ach\"\n ]\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/bank-account")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"accountDetails\": \"<unknown>\",\n \"accountName\": \"Checking Account\",\n \"accountOwner\": {\n \"accountHolderName\": \"Sarah Johnson\",\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"relationship\": \"self\"\n },\n \"bankName\": \"Bank of America\",\n \"currency\": \"usd\",\n \"customerId\": \"customer_66c4168d418a410eae282b83883bdc39\",\n \"networks\": [\n \"wire\",\n \"ach\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/bank-account")
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 \"accountDetails\": \"<unknown>\",\n \"accountName\": \"Checking Account\",\n \"accountOwner\": {\n \"accountHolderName\": \"Sarah Johnson\",\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"relationship\": \"self\"\n },\n \"bankName\": \"Bank of America\",\n \"currency\": \"usd\",\n \"customerId\": \"customer_66c4168d418a410eae282b83883bdc39\",\n \"networks\": [\n \"wire\",\n \"ach\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"accountDetails": {
"accountNumber": "****7890",
"accountType": "checking",
"routingNumber": "021000021"
},
"accountName": "Checking Account",
"accountOwner": {
"accountHolderName": "John Doe",
"relationship": "self"
},
"bankName": "Bank of America",
"created": "2025-01-01T00:00:00Z",
"currency": "usd",
"customerId": "customer_66c4168d418a410eae282b83883bdc39",
"id": "bankAccount_ce745ef7f3df4b9a8bff1301ce24b045",
"networks": [
"wire",
"ach"
],
"status": "active",
"updated": "2025-01-01T00:00:00Z"
}{
"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
}Bank Accounts
Register a Customer Bank Account for Transfers
Create a new bank account for a customer. Requires at least one of the customer’s verification profiles to be approved.
Create a Bank Account
curl --request POST \
--url https://api.spherepay.co/v2/bank-account \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"accountDetails": "<unknown>",
"accountName": "Checking Account",
"accountOwner": {
"accountHolderName": "Sarah Johnson",
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"relationship": "self"
},
"bankName": "Bank of America",
"currency": "usd",
"customerId": "customer_66c4168d418a410eae282b83883bdc39",
"networks": [
"wire",
"ach"
]
}
'import requests
url = "https://api.spherepay.co/v2/bank-account"
payload = {
"accountDetails": "<unknown>",
"accountName": "Checking Account",
"accountOwner": {
"accountHolderName": "Sarah Johnson",
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"relationship": "self"
},
"bankName": "Bank of America",
"currency": "usd",
"customerId": "customer_66c4168d418a410eae282b83883bdc39",
"networks": ["wire", "ach"]
}
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({
accountDetails: '<unknown>',
accountName: 'Checking Account',
accountOwner: {
accountHolderName: 'Sarah Johnson',
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
relationship: 'self'
},
bankName: 'Bank of America',
currency: 'usd',
customerId: 'customer_66c4168d418a410eae282b83883bdc39',
networks: ['wire', 'ach']
})
};
fetch('https://api.spherepay.co/v2/bank-account', 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/bank-account",
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([
'accountDetails' => '<unknown>',
'accountName' => 'Checking Account',
'accountOwner' => [
'accountHolderName' => 'Sarah Johnson',
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'relationship' => 'self'
],
'bankName' => 'Bank of America',
'currency' => 'usd',
'customerId' => 'customer_66c4168d418a410eae282b83883bdc39',
'networks' => [
'wire',
'ach'
]
]),
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/bank-account"
payload := strings.NewReader("{\n \"accountDetails\": \"<unknown>\",\n \"accountName\": \"Checking Account\",\n \"accountOwner\": {\n \"accountHolderName\": \"Sarah Johnson\",\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"relationship\": \"self\"\n },\n \"bankName\": \"Bank of America\",\n \"currency\": \"usd\",\n \"customerId\": \"customer_66c4168d418a410eae282b83883bdc39\",\n \"networks\": [\n \"wire\",\n \"ach\"\n ]\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/bank-account")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"accountDetails\": \"<unknown>\",\n \"accountName\": \"Checking Account\",\n \"accountOwner\": {\n \"accountHolderName\": \"Sarah Johnson\",\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"relationship\": \"self\"\n },\n \"bankName\": \"Bank of America\",\n \"currency\": \"usd\",\n \"customerId\": \"customer_66c4168d418a410eae282b83883bdc39\",\n \"networks\": [\n \"wire\",\n \"ach\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/bank-account")
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 \"accountDetails\": \"<unknown>\",\n \"accountName\": \"Checking Account\",\n \"accountOwner\": {\n \"accountHolderName\": \"Sarah Johnson\",\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"relationship\": \"self\"\n },\n \"bankName\": \"Bank of America\",\n \"currency\": \"usd\",\n \"customerId\": \"customer_66c4168d418a410eae282b83883bdc39\",\n \"networks\": [\n \"wire\",\n \"ach\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"accountDetails": {
"accountNumber": "****7890",
"accountType": "checking",
"routingNumber": "021000021"
},
"accountName": "Checking Account",
"accountOwner": {
"accountHolderName": "John Doe",
"relationship": "self"
},
"bankName": "Bank of America",
"created": "2025-01-01T00:00:00Z",
"currency": "usd",
"customerId": "customer_66c4168d418a410eae282b83883bdc39",
"id": "bankAccount_ce745ef7f3df4b9a8bff1301ce24b045",
"networks": [
"wire",
"ach"
],
"status": "active",
"updated": "2025-01-01T00:00:00Z"
}{
"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 register a customer’s existing fiat bank account with SpherePay. SpherePay does not open or manage bank accounts — it links an account your customer already holds to their SpherePay profile so it can be used as the source or destination for fiat transfers. You must register at least one bank account before creating a transfer that involves fiat currency. The customer must have at least one approved verification profile before you can register a bank account on their behalf.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
- Option 1
- EUR
- BRL
- MXN
USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber, bic.
A descriptive name for this bank account (e.g., "Checking Account", "Business Account").
Minimum string length:
1Example:
"Checking Account"
Information about the account owner, including their name, address, and relationship to the customer.
Show child attributes
Show child attributes
The name of the financial institution where the account is held.
Minimum string length:
1Example:
"Bank of America"
The currency of the bank account. When set to usd, accountDetails must contain either (accountNumber, routingNumber, accountType) for ACH/Wire or (accountNumber, bic) for SWIFT.
Available options:
usd Example:
"usd"
The unique identifier of the customer who owns this bank account.
Minimum string length:
1Example:
"customer_66c4168d418a410eae282b83883bdc39"
The payment networks supported by this bank account. For USD ACH/Wire accounts, must include at least one of "ach" or "wire". For USD SWIFT accounts, must be exactly ["swift"].
Minimum array length:
1Available options:
ach, wire Example:
["wire", "ach"]
Response
- USD
- EUR
- BRL
- MXN
USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic.
- Option 1
- Option 2
Show child attributes
Show child attributes
A descriptive name for this bank account.
Example:
"Checking Account"
Information about the account owner, including their name and relationship to the customer.
Show child attributes
Show child attributes
The name of the financial institution where the account is held.
Example:
"Bank of America"
The ISO 8601 timestamp when the bank account was created.
Example:
"2025-01-01T00:00:00Z"
The currency of the bank account.
Available options:
usd Example:
"usd"
The unique identifier of the customer who owns this bank account.
Example:
"customer_66c4168d418a410eae282b83883bdc39"
The unique identifier of the bank account.
Example:
"bankAccount_ce745ef7f3df4b9a8bff1301ce24b045"
The payment networks supported by this bank account. For USD ACH/Wire accounts, includes at least one of "ach" or "wire". For USD SWIFT accounts, is exactly ["swift"].
Available options:
ach, wire Example:
["wire", "ach"]
The current status of the bank account.
Available options:
pending, active, inactive, invalid Example:
"active"
The ISO 8601 timestamp when the bank account was last updated.
Example:
"2025-01-01T00:00:00Z"
Last modified on June 18, 2026