Introducing Starknet Network:   OffRamp and OnRamp USDC are now supported for Starknet network.  View changelog for details →.
Sphere Paysphere
Bank account

Create Bank Account

A **bank account** is an account held at a bank or other financial institution on behalf of your company or customers. A **bank account** is owned either by your customers or your application. It can be used as a source or destination when creating transfers. Sphere verifies every **bank account** upon creation. When a **bank account** is created, it will initially have a `pending` status until it is verified by Sphere. Once verified, its status will change to `active`.

POST
/v2/customers/{customer_id}/bank-account

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

customer_idstring

The customer's id.

Request Body

accountNamestring

A unique identifier to remember the bank account

bankNamestring

The name of the bank associated with the account, such as Bank of America.

currencystring

The currency code in which the bank account operates. Refer to our Currency Code for the full list.

accountDetailsobject

The account details contain the details of the bank account, tailored to each different currency. Please refer to our Bank Account Creation for a detailed information on constructing the payment request.

beneficiaryAddressobject

Response Body

curl -X POST "https://api.sandbox.spherepay.co/v2/customers/{{customer_id}}/bank-account" \
  -H "Content-Type: application/json" \
  -d '{
    "accountName": "wise",
    "bankName": "wise",
    "accountHolderName": "John Doe",
    "currency": "usd",
    "accountDetails": {
      "accountNumber": "352777177759389",
      "routingNumber": 84009519,
      "accountType": "savings"
    },
    "beneficiaryAddress": {
      "line1": "1 Main st",
      "line2": "01-101",
      "city": "Bentonville",
      "postalCode": "12345",
      "state": "AR",
      "country": "USA"
    }
  }'
const body = JSON.stringify({
  "accountName": "wise",
  "bankName": "wise",
  "accountHolderName": "John Doe",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "352777177759389",
    "routingNumber": 84009519,
    "accountType": "savings"
  },
  "beneficiaryAddress": {
    "line1": "1 Main st",
    "line2": "01-101",
    "city": "Bentonville",
    "postalCode": "12345",
    "state": "AR",
    "country": "USA"
  }
})

fetch("https://api.sandbox.spherepay.co/v2/customers/{{customer_id}}/bank-account", {
  body
})
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://api.sandbox.spherepay.co/v2/customers/{{customer_id}}/bank-account"
  body := strings.NewReader(`{
    "accountName": "wise",
    "bankName": "wise",
    "accountHolderName": "John Doe",
    "currency": "usd",
    "accountDetails": {
      "accountNumber": "352777177759389",
      "routingNumber": 84009519,
      "accountType": "savings"
    },
    "beneficiaryAddress": {
      "line1": "1 Main st",
      "line2": "01-101",
      "city": "Bentonville",
      "postalCode": "12345",
      "state": "AR",
      "country": "USA"
    }
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
import requests

url = "https://api.sandbox.spherepay.co/v2/customers/{{customer_id}}/bank-account"
body = {
  "accountName": "wise",
  "bankName": "wise",
  "accountHolderName": "John Doe",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "352777177759389",
    "routingNumber": 84009519,
    "accountType": "savings"
  },
  "beneficiaryAddress": {
    "line1": "1 Main st",
    "line2": "01-101",
    "city": "Bentonville",
    "postalCode": "12345",
    "state": "AR",
    "country": "USA"
  }
}
response = requests.request("POST", url, json = body, headers = {
  "Content-Type": "application/json"
})

print(response.text)
{
  "id": "bankAccount_1c19dcf3caaa447bb209df0e5d599e8d",
  "status": "active",
  "bankName": "Chase",
  "accountHolderName": "John Mock-Doe",
  "accountName": "Savings Account",
  "customer": "customer_68f1c089703945e7bbff6f04bf1c5041",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "**********6789",
    "routingNumber": "**********6789",
    "accountType": "checking | savings"
  }
}
{
  "ok": false,
  "object": "error",
  "statusCode": 500,
  "error": {
    "message": "Invalid enum value. Expected 'usd' | 'eur' | 'brl' | 'cad' | 'cop' | 'idr' | 'inr' | 'mxn' | 'php' | 'sgd' | 'thb' | 'vnd' | 'gbp', received 'brlx'",
    "errors": {
      "currency": [
        "Invalid enum value. Expected 'usd' | 'eur' | 'brl' | 'cad' | 'cop' | 'idr' | 'inr' | 'mxn' | 'php' | 'sgd' | 'thb' | 'vnd' | 'gbp', received 'brlx'"
      ]
    }
  },
  "message": "Invalid enum value. Expected 'usd' | 'eur' | 'brl' | 'cad' | 'cop' | 'idr' | 'inr' | 'mxn' | 'php' | 'sgd' | 'thb' | 'vnd' | 'gbp', received 'brlx'",
  "data": null,
  "ts": "2025-04-12T17:57:06.572Z",
  "request": "request_1e9f6c83a0114008add80204fdd15f93"
}