Quando usar P2P
P2P é o tipo de transferência adequado sempre que tanto o remetente quanto o destinatário possuem contas na sua instituição. Cenários comuns incluem:
- Movimentação de dinheiro entre as próprias contas do cliente — um cliente transferindo da conta corrente para a conta poupança, ou entre duas contas que ele gerencia.
- Pagamento para outro cliente na mesma instituição — um cliente enviando dinheiro para um amigo, familiar ou empresa que também é cliente da sua instituição.
- Movimentações internas de tesouraria — divisão de saldos entre contas corporativas mantidas na mesma organização.
- Divisão de pagamentos — distribuição de valores entre múltiplas contas para folha de pagamento, rateio de despesas ou cashback.
Principais vantagens
| Aspecto | P2P | TED OUT |
|---|---|---|
| Tempo de liquidação | Menos de 2 segundos | 5–10 minutos |
| Horário de operação | 24/7, incluindo fins de semana e feriados | Seg–Sex, 06:30–17:00 |
| Tarifa (padrão) | Nenhuma | Configurável |
| Dependência do BACEN | Nenhuma | Obrigatória (JD SPB) |
Como funciona
O P2P reutiliza a mesma API do TED OUT, mantendo sua integração consistente entre os tipos de transferência. O processo é de duas etapas do ponto de vista do cliente:
- Iniciar — O cliente submete os detalhes da transferência. O plugin valida o destinatário, verifica o saldo do remetente e confirma a tarifa (tipicamente R$ 0,00). O cliente vê o resumo da transferência antes de confirmar.
- Confirmar — O cliente confirma. O plugin cria um débito + crédito atômico no Midaz. A transferência é concluída imediatamente — tipicamente em menos de 2 segundos.
Estados da transferência
| Estado | O que significa |
|---|---|
CREATED | Transferência iniciada, aguardando confirmação do cliente |
PROCESSING | Transação atômica no Midaz em andamento |
COMPLETED | Transferência liquidada — fundos foram movimentados |
FAILED | Erro interno; nenhum fundo foi movimentado |
CANCELLED | Cancelada pelo cliente antes da confirmação |
O estado
PENDING não se aplica a transferências P2P. PENDING é utilizado no TED OUT para indicar fundos reservados enquanto aguardam submissão ao SPB. O P2P é liquidado inteiramente dentro do Midaz, de modo que a transferência vai diretamente de PROCESSING para COMPLETED — tipicamente em menos de 2 segundos.Configuração de tarifas
As tarifas P2P são desabilitadas por padrão. A maioria das instituições oferece transferências internas sem cobrança, mas a configuração está disponível caso seu modelo de precificação exija. Para habilitar tarifas para P2P, consulte configuração do TED.
Validação do destinatário
O destinatário deve ser uma conta cadastrada dentro da mesma instituição. Ao submeter uma transferência, o plugin localiza o destinatário no CRM usando os dados bancários fornecidos (ISPB, agência, conta e documento do titular). Se o destinatário não for encontrado, a transferência é rejeitada e nenhum fundo é movimentado. O cliente deve verificar os dados da conta e tentar novamente.
Integração técnica
O P2P utiliza os mesmos endpoints do TED OUT. Nenhum trabalho adicional de integração é necessário além do que você já construiu para transferências de saída.
- Iniciar Transferência — POST /v1/transfers/initiate
- Processar Transferência — POST /v1/transfers/process
- Obter Transferência — GET /v1/transfers/
O campo
type na resposta da transferência será P2P. Não há controlNumber em transferências P2P, pois elas não passam pelo JD SPB.Tratamento de erros
Transferências P2P são atômicas: o débito e o crédito são criados em uma única transação no Midaz. Se qualquer parte da operação falhar, toda a transação é revertida. Não existe estado intermediário em que os fundos estão parcialmente movimentados ou temporariamente ausentes de uma conta. Se uma transferência falhar, o saldo do cliente permanece inalterado e ele pode tentar novamente. Consulte a lista completa de erros para códigos de erro específicos e orientações de recuperação.