Documentation Index
Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
Use this file to discover all available pages before exploring further.
A bank account in SpherePay is a registration of your customer’s existing fiat bank account. 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 any transfer that involves fiat currency.
SpherePay registers an existing bank account — it does not open a new account on your customer’s behalf. The account must already exist at the customer’s bank before registration.
Register a bank account
POST https://api.spherepay.co/v2/bank-account
For the full request and response schema, see the Create Bank Account API reference.
Supported rails and currencies
| Currency | Supported Rails |
|---|
| USD | ACH, Wire |
| EUR | SEPA |
| BRL | PIX |
Required fields by currency
The fields required to register a bank account depend on the currency. Use the tabs below to see the required fields and a request example for each.
Both ACH and Wire use the same account details. Include both in networks to register for both rails with a single request.| Field | Required |
|---|
customerId | Yes |
bankName | Yes |
accountName | Yes |
accountOwner.accountHolderName | Yes |
accountOwner.address | Yes |
currency | Yes — "usd" |
accountDetails.accountNumber | Yes |
accountDetails.routingNumber | Yes |
accountDetails.accountType | Yes — "checking" or "savings" |
networks | Yes — ["ach"], ["wire"], or ["ach", "wire"] |
{
"customerId": "customer_1234567890",
"bankName": "Chase",
"accountName": "Jane Doe Checking",
"accountOwner": {
"accountHolderName": "Jane Doe",
"address": {
"line1": "233 South Wacker Drive",
"city": "Chicago",
"state": "IL",
"postalCode": "60606",
"country": "USA"
}
},
"currency": "usd",
"accountDetails": {
"accountNumber": "1234567890",
"routingNumber": "123456789",
"accountType": "checking"
},
"networks": ["ach", "wire"]
}
EUR accounts use IBAN and BIC for SEPA transfers.| Field | Required |
|---|
customerId | Yes |
bankName | Yes |
accountName | Yes |
accountOwner.accountHolderName | Yes |
accountOwner.address | Yes |
currency | Yes — "eur" |
accountDetails.iban | Yes |
accountDetails.bic | Yes |
networks | Yes — ["sepa"] |
{
"customerId": "customer_1234567890",
"bankName": "Deutsche Bank",
"accountName": "Jane Doe SEPA",
"accountOwner": {
"accountHolderName": "Jane Doe",
"address": {
"line1": "10 Rue de Rivoli",
"city": "Paris",
"postalCode": "75001",
"country": "FRA"
}
},
"currency": "eur",
"accountDetails": {
"iban": "DE89370400440532013000",
"bic": "COBADEFFXXX"
},
"networks": ["sepa"]
}
BRL accounts use PIX, Brazil’s instant payment network. Instead of an account number and routing number, you provide a PIX key and key type.| Field | Required |
|---|
customerId | Yes |
bankName | Yes |
accountName | Yes |
accountOwner.accountHolderName | Yes |
accountOwner.address | Yes — postalCode is required |
currency | Yes — "brl" |
accountDetails.pixKey | Yes |
accountDetails.pixKeyType | Yes — "cpf", "cnpj", "email", "phone", or "random" |
networks | Yes — ["pix"] |
{
"customerId": "customer_1234567890",
"bankName": "Itaú",
"accountName": "Alice Santos PIX",
"accountOwner": {
"accountHolderName": "Alice Santos",
"address": {
"line1": "Rua Augusta 100",
"city": "Sao Paulo",
"state": "SP",
"postalCode": "01304-001",
"country": "BRA"
}
},
"currency": "brl",
"accountDetails": {
"pixKey": "alice@example.com",
"pixKeyType": "email"
},
"networks": ["pix"]
}
BRL transfers require a separate verification profile (kyc_profile_b for individuals, kyb_profile_b for businesses). Contact your SpherePay representative to enable BRL/PIX access. See BRL/PIX transfer constraints for the full list of rules. Using the returned ID
The id returned in the response is your persistent reference to this bank account. Store it against the customer record and pass it as the source.id or destination.id when creating transfers.
{
"id": "bank_account_abc123",
"customerId": "customer_1234567890",
"currency": "usd",
"networks": ["ach", "wire"],
...
}
