Uma conta bancária (bank_account) no SpherePay é o registro da conta bancária fiat existente do seu cliente. O SpherePay não abre nem gerencia contas bancárias — ele vincula uma conta que seu cliente já possui ao perfil SpherePay dele para que possa ser usada como origem ou destino para transferências fiat. Você deve registrar pelo menos uma conta bancária antes de criar qualquer transferência que envolva moeda fiat.
O SpherePay registra uma conta bancária existente — não abre uma nova conta em nome do seu cliente. A conta já deve existir no banco do cliente antes do registro.
Registrar uma conta bancária
POST https://api.spherepay.co/v2/bank-account
Para o esquema completo de requisição e resposta, consulte a referência da API de Criar Conta Bancária.
Rails e moedas suportados
| Moeda | Rails Suportados |
|---|
| USD | ACH, Wire |
| EUR | SEPA |
| BRL | PIX |
Campos obrigatórios por moeda
Os campos obrigatórios para registrar uma conta bancária dependem da moeda. Use as abas abaixo para ver os campos obrigatórios e um exemplo de requisição para cada uma.
Tanto ACH quanto Wire usam os mesmos detalhes de conta. Inclua ambos em networks para registrar nos dois rails com uma única requisição.| Campo | Obrigatório |
|---|
customerId | Sim |
bankName | Sim |
accountName | Sim |
accountOwner.accountHolderName | Sim |
accountOwner.address | Sim |
currency | Sim — "usd" |
accountDetails.accountNumber | Sim |
accountDetails.routingNumber | Sim |
accountDetails.accountType | Sim — "checking" ou "savings" |
networks | Sim — ["ach"], ["wire"] ou ["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"]
}
Contas em EUR usam IBAN e BIC para transferências SEPA.| Campo | Obrigatório |
|---|
customerId | Sim |
bankName | Sim |
accountName | Sim |
accountOwner.accountHolderName | Sim |
accountOwner.address | Sim |
currency | Sim — "eur" |
accountDetails.iban | Sim |
accountDetails.bic | Sim |
networks | Sim — ["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"]
}
Contas em BRL usam PIX, a rede de pagamentos instantâneos do Brasil. Em vez de número de conta e agência, você fornece uma chave PIX e o tipo de chave.| Campo | Obrigatório |
|---|
customerId | Sim |
bankName | Sim |
accountName | Sim |
accountOwner.accountHolderName | Sim |
accountOwner.address | Sim — postalCode é obrigatório |
currency | Sim — "brl" |
accountDetails.pixKey | Sim |
accountDetails.pixKeyType | Sim — "cpf", "cnpj", "email", "phone" ou "random" |
networks | Sim — ["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"]
}
Transferências em BRL requerem um perfil de verificação separado (kyc_profile_b para pessoas físicas, kyb_profile_b para empresas). Entre em contato com seu representante SpherePay para habilitar o acesso ao BRL/PIX. Consulte Restrições de transferências BRL/PIX para a lista completa de regras. Usando o ID retornado
O id retornado na resposta é sua referência persistente a esta conta bancária. Armazene-o contra o registro do cliente e passe-o como source.id ou destination.id ao criar transferências.
{
"id": "bank_account_abc123",
"customerId": "customer_1234567890",
"currency": "usd",
"networks": ["ach", "wire"],
...
}
