Skip to main content
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 '
{
  "customerId": "customer_66c4168d418a410eae282b83883bdc39",
  "bankName": "Bank of America",
  "accountName": "Checking Account",
  "currency": "usd",
  "accountDetails": "<unknown>",
  "accountOwner": {
    "accountHolderName": "Sarah Johnson",
    "address": {
      "line1": "233 South Wacker Drive",
      "city": "Chicago",
      "country": "USA",
      "line2": "Suite 4700",
      "state": "IL",
      "postalCode": "60606"
    },
    "relationship": "self"
  },
  "networks": [
    "wire",
    "ach"
  ]
}
'
{
  "id": "bankAccount_ce745ef7f3df4b9a8bff1301ce24b045",
  "status": "active",
  "customerId": "customer_66c4168d418a410eae282b83883bdc39",
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-01-01T00:00:00Z",
  "bankName": "Bank of America",
  "accountName": "Checking Account",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "****7890",
    "routingNumber": "021000021",
    "accountType": "checking"
  },
  "accountOwner": {
    "accountHolderName": "John Doe",
    "relationship": "self"
  },
  "networks": [
    "wire",
    "ach"
  ]
}
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

​
Authorization
string
header
required

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

Body

application/json
​
customerId
string
required

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

Minimum string length: 1
Example:

"customer_66c4168d418a410eae282b83883bdc39"

​
bankName
string
required

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

Minimum string length: 1
Example:

"Bank of America"

​
accountName
string
required

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

Minimum string length: 1
Example:

"Checking Account"

​
currency
enum<string>
required

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"

​
accountDetails
any
required

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

​
accountOwner
object
required

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

​
networks
required

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
Available options:
ach,
wire
Example:
["wire", "ach"]

Response

​
id
string
required

The unique identifier of the bank account.

Example:

"bankAccount_ce745ef7f3df4b9a8bff1301ce24b045"

​
status
enum<string>
required

The current status of the bank account.

Available options:
pending,
active,
inactive,
invalid
Example:

"active"

​
customerId
string
required

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

Example:

"customer_66c4168d418a410eae282b83883bdc39"

​
created
string
required

The ISO 8601 timestamp when the bank account was created.

Example:

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

​
updated
string
required

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

Example:

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

​
bankName
string
required

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

Example:

"Bank of America"

​
accountName
string
required

A descriptive name for this bank account.

Example:

"Checking Account"

​
currency
enum<string>
required

The currency of the bank account.

Available options:
usd
Example:

"usd"

​
accountDetails
object
required

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

​
accountOwner
object
required

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

​
networks
required

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"]
Last modified on June 18, 2026