Registrar Cuenta Bancaria del Cliente para Transferencias

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
}

Usa este endpoint para registrar la cuenta bancaria fiat existente de un cliente en SpherePay. SpherePay no abre ni gestiona cuentas bancarias — vincula una cuenta que tu cliente ya tiene a su perfil de SpherePay para que pueda usarse como origen o destino para transferencias fiat. Debes registrar al menos una cuenta bancaria antes de crear una transferencia que involucre divisa fiat. El cliente debe tener al menos un perfil de verificación aprobado antes de que puedas registrar una cuenta bancaria 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

Option 1
EUR
BRL
MXN

accountDetails

any

requerido

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

accountName

string

requerido

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

Minimum string length: 1

Ejemplo:

"Checking Account"

accountOwner

object

requerido

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

Show child attributes

bankName

string

requerido

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

Minimum string length: 1

Ejemplo:

"Bank of America"

currency

enum<string>

requerido

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.

Opciones disponibles:

usd

Ejemplo:

"usd"

customerId

string

requerido

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

Minimum string length: 1

Ejemplo:

"customer_66c4168d418a410eae282b83883bdc39"

networks

requerido

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

Opciones disponibles:

ach,

wire

Ejemplo:

["wire", "ach"]

Respuesta

accountDetails

object

requerido

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

Option 1
Option 2

Show child attributes

accountName

string

requerido

A descriptive name for this bank account.

Ejemplo:

"Checking Account"

accountOwner

object

requerido

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

Show child attributes

bankName

string

requerido

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

Ejemplo:

"Bank of America"

created

string

requerido

The ISO 8601 timestamp when the bank account was created.

Ejemplo:

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

currency

enum<string>

requerido

The currency of the bank account.

Opciones disponibles:

usd

Ejemplo:

"usd"

customerId

string

requerido

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

Ejemplo:

"customer_66c4168d418a410eae282b83883bdc39"

string

requerido

The unique identifier of the bank account.

Ejemplo:

"bankAccount_ce745ef7f3df4b9a8bff1301ce24b045"

networks

requerido

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

Opciones disponibles:

ach,

wire

Ejemplo:

["wire", "ach"]

status

enum<string>

requerido

The current status of the bank account.

Opciones disponibles:

pending,

active,

inactive,

invalid

Ejemplo:

"active"

updated

string

requerido

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

Ejemplo:

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

Última modificación el 22 de junio de 2026

Incorporación

Cuentas

Movimiento de dinero

Webhooks

Registrar Cuenta Bancaria del Cliente para Transferencias

Autorizaciones

Cuerpo

Respuesta