Register a Customer Bank Account for Transfers

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.

Endpoint

POST https://api.spherepay.co/v2/bank-account

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer <token>

Request parameters

customerId

string

required

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

bankName

string

required

The name of the financial institution where the account is held (e.g., "Bank of America").

accountName

string

required

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

currency

string

required

The currency of the bank account. Must be "usd", "eur", or "brl". The required accountDetails fields vary by currency — see the per-currency sections below.

accountDetails

object

required

Account-specific details. Required fields depend on currency. See per-currency breakdowns below.

accountOwner

object

required

Information about the account holder, including their name and address.

Show properties

accountHolderName

string

required

Full legal name of the account holder.

address

object

required

Mailing address of the account holder.

Show properties

line1

string

required

Street address line 1.

city

string

required

City.

state

string

State or province. Required for USD accounts.

postalCode

string

Postal code. Required for BRL accounts.

country

string

required

ISO 3166-1 alpha-3 country code (e.g., "USA", "FRA", "BRA").

networks

string[]

required

Payment networks supported by this account. Must match the account currency:

USD: ["ach"], ["wire"], or ["ach", "wire"]
EUR: ["sepa"]
BRL: ["pix"]

Per-currency `accountDetails` fields

USD accounts use ACH and/or Wire. Both rails share the same account details — include both in networks to register for both with a single request.

accountDetails.accountNumber

string

required

The bank account number.

accountDetails.routingNumber

string

required

The 9-digit ABA routing number.

accountDetails.accountType

string

required

Account type. Must be "checking" or "savings".

EUR accounts use SEPA. Set networks to ["sepa"].

accountDetails.iban

string

required

International Bank Account Number (e.g., "DE89370400440532013000").

accountDetails.bic

string

required

Bank Identifier Code / SWIFT code (e.g., "COBADEFFXXX").

BRL accounts use PIX, Brazil’s instant payment network. Set networks to ["pix"]. The account owner’s postalCode is required for BRL accounts.

accountDetails.pixKey

string

required

The PIX key associated with the account (e.g., "alice@example.com").

accountDetails.pixKeyType

string

required

The type of PIX key. Must be one of "cpf", "cnpj", "email", "phone", or "random".

curl -X POST "https://api.spherepay.co/v2/bank-account" \
  -H "Authorization: Bearer $SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_66c4168d418a410eae282b83883bdc39",
    "bankName": "Chase",
    "accountName": "Jane Doe Checking",
    "currency": "usd",
    "accountDetails": {
      "accountNumber": "1234567890",
      "routingNumber": "021000021",
      "accountType": "checking"
    },
    "accountOwner": {
      "accountHolderName": "Jane Doe",
      "address": {
        "line1": "233 South Wacker Drive",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60606",
        "country": "USA"
      }
    },
    "networks": ["ach", "wire"]
  }'

Response fields

string

Unique identifier for the registered bank account. Store this value and use it in transfer requests.

status

string

Account status. Typically "active" on creation.

bankName

string

Name of the financial institution.

accountName

string

Descriptive label for the account.

customerId

string

ID of the customer who owns this account.

currency

string

Currency code: "usd", "eur", or "brl".

accountDetails

object

Masked account details. Sensitive fields such as account numbers are partially redacted.

accountOwner

object

Account holder name and relationship.

networks

string[]

Payment networks registered for this account.

created

string

ISO 8601 timestamp of when the account was registered.

updated

string

ISO 8601 timestamp of the most recent update.

  "id": "bankAccount_ce745ef7f3df4b9a8bff1301ce24b045",
  "status": "active",
  "bankName": "Chase",
  "accountName": "Jane Doe Checking",
  "customerId": "customer_66c4168d418a410eae282b83883bdc39",
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-01-01T00:00:00Z",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "****7890",
    "routingNumber": "021000021",
    "accountType": "checking"
  },
  "accountOwner": {
    "accountHolderName": "Jane Doe",
    "relationship": "self"
  },
  "networks": ["ach", "wire"]
}

Error responses

Status	Code	Description
`400`	`address/invalid`	One or more request parameters are invalid.
`404`	`resource/not-found`	The specified customer ID does not exist.
`422`	`validation/failed`	Validation failed. The response includes a per-field `errors` array.

Onboarding

Accounts

Money movement

Register a Customer Bank Account for Transfers

Endpoint

Authentication

Request parameters

Per-currency `accountDetails` fields

Response fields

Error responses

Onboarding

Accounts

Money movement

Documentation Index

​Endpoint

​Authentication

​Request parameters

​Per-currency accountDetails fields

​Response fields

​Error responses

Endpoint

Authentication

Request parameters

Per-currency `accountDetails` fields

Response fields

Error responses