Registrar uma Conta Bancária do Cliente para Transferências

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
}

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 este endpoint para registrar a conta bancária fiat existente de um cliente no SpherePay. O SpherePay não abre nem gerencia contas bancárias — ele vincula uma conta que seu cliente já possui ao perfil do SpherePay para que possa ser usada como origem ou destino em transferências fiat. Você deve registrar pelo menos uma conta bancária (bank_account) antes de criar uma transferência que envolva moeda fiat. O cliente deve ter pelo menos um perfil de verificação aprovado antes que você possa registrar uma conta bancária em seu nome.

Autorizações

Authorization

string

header

obrigatório

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

Corpo

application/json

Option 1
EUR
BRL
MXN

accountDetails

any

obrigatório

USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber, bic.

accountName

string

obrigatório

A descriptive name for this bank account (e.g., "Checking Account", "Business Account").

Minimum string length: 1

Exemplo:

"Checking Account"

accountOwner

object

obrigatório

Information about the account owner, including their name, address, and relationship to the customer.

Show child attributes

bankName

string

obrigatório

The name of the financial institution where the account is held.

Minimum string length: 1

Exemplo:

"Bank of America"

currency

enum<string>

obrigatório

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.

Opções disponíveis:

usd

Exemplo:

"usd"

customerId

string

obrigatório

The unique identifier of the customer who owns this bank account.

Minimum string length: 1

Exemplo:

"customer_66c4168d418a410eae282b83883bdc39"

networks

obrigatório

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: 1

Opções disponíveis:

ach,

wire

Exemplo:

["wire", "ach"]

Resposta

accountDetails

object

obrigatório

USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic.

Option 1
Option 2

Show child attributes

accountName

string

obrigatório

A descriptive name for this bank account.

Exemplo:

"Checking Account"

accountOwner

object

obrigatório

Information about the account owner, including their name and relationship to the customer.

Show child attributes

bankName

string

obrigatório

The name of the financial institution where the account is held.

Exemplo:

"Bank of America"

created

string

obrigatório

The ISO 8601 timestamp when the bank account was created.

Exemplo:

"2025-01-01T00:00:00Z"

currency

enum<string>

obrigatório

The currency of the bank account.

Opções disponíveis:

usd

Exemplo:

"usd"

customerId

string

obrigatório

The unique identifier of the customer who owns this bank account.

Exemplo:

"customer_66c4168d418a410eae282b83883bdc39"

string

obrigatório

The unique identifier of the bank account.

Exemplo:

"bankAccount_ce745ef7f3df4b9a8bff1301ce24b045"

networks

obrigatório

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

Opções disponíveis:

ach,

wire

Exemplo:

["wire", "ach"]

status

enum<string>

obrigatório

The current status of the bank account.

Opções disponíveis:

pending,

active,

inactive,

invalid

Exemplo:

"active"

updated

string

obrigatório

The ISO 8601 timestamp when the bank account was last updated.

Exemplo:

"2025-01-01T00:00:00Z"

Última modificação em 22 de junho de 2026

Onboarding

Contas

Movimentação de dinheiro

Webhooks

Registrar uma Conta Bancária do Cliente para Transferências

Autorizações

Corpo

Resposta