Una cuenta bancaria (bank_account) en SpherePay es un registro de la cuenta bancaria fiat existente de tu cliente. 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 cualquier transferencia que involucre moneda fiat.
SpherePay registra una cuenta bancaria existente — no abre una nueva cuenta en nombre de tu cliente. La cuenta debe existir ya en el banco del cliente antes del registro.
Registrar una cuenta bancaria
POST https://api.spherepay.co/v2/bank-account
Para el esquema completo de solicitud y respuesta, consulta la referencia API de Crear Cuenta Bancaria.
Rieles y divisas soportados
| Divisa | Rieles Soportados |
|---|
| USD | ACH, Wire |
| EUR | SEPA |
| BRL | PIX |
Campos requeridos por divisa
Los campos requeridos para registrar una cuenta bancaria dependen de la divisa. Usa las pestañas a continuación para ver los campos requeridos y un ejemplo de solicitud para cada uno.
Tanto ACH como Wire usan los mismos detalles de cuenta. Incluye ambos en networks para registrar para ambos rieles con una sola solicitud.| Campo | Requerido |
|---|
customerId | Sí |
bankName | Sí |
accountName | Sí |
accountOwner.accountHolderName | Sí |
accountOwner.address | Sí |
currency | Sí — "usd" |
accountDetails.accountNumber | Sí |
accountDetails.routingNumber | Sí |
accountDetails.accountType | Sí — "checking" o "savings" |
networks | Sí — ["ach"], ["wire"], o ["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"]
}
Las cuentas EUR usan IBAN y BIC para transferencias SEPA.| Campo | Requerido |
|---|
customerId | Sí |
bankName | Sí |
accountName | Sí |
accountOwner.accountHolderName | Sí |
accountOwner.address | Sí |
currency | Sí — "eur" |
accountDetails.iban | Sí |
accountDetails.bic | Sí |
networks | Sí — ["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"]
}
Las cuentas BRL usan PIX, la red de pago instantáneo de Brasil. En lugar de un número de cuenta y número de enrutamiento, proporcionas una clave PIX y el tipo de clave.| Campo | Requerido |
|---|
customerId | Sí |
bankName | Sí |
accountName | Sí |
accountOwner.accountHolderName | Sí |
accountOwner.address | Sí — postalCode es requerido |
currency | Sí — "brl" |
accountDetails.pixKey | Sí |
accountDetails.pixKeyType | Sí — "cpf", "cnpj", "email", "phone" o "random" |
networks | Sí — ["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"]
}
Las transferencias BRL requieren un perfil de verificación separado (kyc_profile_b para individuos, kyb_profile_b para empresas). Contacta a tu representante de SpherePay para habilitar el acceso BRL/PIX. Consulta Restricciones de transferencias BRL/PIX para la lista completa de reglas. Usar el ID devuelto
El id devuelto en la respuesta es tu referencia persistente a esta cuenta bancaria. Guárdalo contra el registro del cliente y pásalo como source.id o destination.id al crear transferencias.
{
"id": "bank_account_abc123",
"customerId": "customer_1234567890",
"currency": "usd",
"networks": ["ach", "wire"],
...
}
