Uma Transfer representa um saque do saldo disponível de uma empresa para sua conta bancária. É a etapa final do ciclo financeiro.
Máquina de Estados
TransferStatus
Default PENDING. PAID indica transferência efetivada.
| Status | Descrição |
|---|
PENDING | Criada, aguardando processamento |
PROCESSING | Em processamento no provedor |
PAID | Efetivada com sucesso |
FAILED | Falhou |
CANCELED | Cancelada |
Pré-requisitos
- A Company deve ter um BankAccount cadastrado.
- A Company deve estar apta a receber saldo no provider de billing.
- O saldo disponível (consultado no provedor) deve cobrir o valor solicitado.
BankAccount
| Campo | Descrição |
|---|
bankAccountId | Identificador único |
organizationId | Organização da empresa dona da conta |
companyId | Empresa dona da conta |
externalProvider | Provedor vinculado |
externalProviderId | ID da conta no provedor |
bankCode | Código do banco |
bankName | Nome do banco |
agencyNumber | Número da agência |
accountNumber | Número da conta |
accountType | CHECKING ou SAVINGS |
holderName | Nome do titular |
holderDocument | Documento do titular |
holderDocumentType | CPF, CNPJ ou RG |
status | ACTIVE ou INACTIVE |
createdBy | Usuário que criou o registro, quando aplicável |
createdAt | Timestamp da criação |
updatedBy | Usuário que fez a última atualização, quando aplicável |
updatedAt | Timestamp da última atualização |
Cada empresa possui uma única conta bancária. Alterações de conta bancária são sincronizadas com o provider de billing e com o cadastro da empresa.
Withdrawal Flow
Saldo disponível
O saldo disponível é sempre obtido pelo provider de billing, que é a fonte da verdade para valores liquidados e disponíveis para saque.
Consultas de saldo devem usar a visão retornada pelo provider de billing.
Atualização via webhook
A transferência nasce PENDING. O resultado chega pelo webhook do provedor (UPDATE_TRANSFER), que atualiza o status para PAID, FAILED ou CANCELED.
Rastreamento externo
O par externalProvider + externalProviderId identifica a transferência externa e evita duplicidade de processamento.
Ciclo financeiro completo
