Transferências P2P

Transferências P2P (peer-to-peer) são operações entre contas que pertencem ao mesmo ISPB. Como não envolvem comunicação com o SPB, são processadas instantaneamente e com menor custo operacional.

Quando usar P2P

O plugin detecta automaticamente quando uma transferência pode ser processada como P2P:

Cenário	Tipo de transferência
ISPB do destinatário diferente do seu	TED OUT (via SPB)
ISPB do destinatário igual ao seu	P2P (interno)

A detecção é transparente para o cliente da API — o mesmo endpoint é usado para ambos os casos.

Vantagens do P2P

Velocidade: Liquidação em menos de 2 segundos (contra minutos da TED).
Custo: Sem taxas da JD SPB, taxas Lerian reduzidas.
Disponibilidade: Funciona 24/7, sem depender do horário do BACEN.

Comparativo com TED OUT

Aspecto	TED OUT	P2P
Tempo de liquidação	5-10 minutos	< 2 segundos
Horário de funcionamento	Seg-Sex 06:30-17:00	24/7
Custo operacional	Envolve JD SPB	Apenas Midaz
Dependências externas	JD Consultores, BACEN	Nenhuma

Como funciona

O fluxo P2P é simplificado:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Iniciação     │────▶│  Detecção P2P   │────▶│   Validação     │
│   (initiate)    │     │  (mesmo ISPB)   │     │   destinatário  │
└─────────────────┘     └─────────────────┘     └────────┬────────┘
                                                         │
┌─────────────────┐     ┌─────────────────┐              │
│   Concluído     │◀────│   Transação     │◀─────────────┘
│   (completed)   │     │   atômica Midaz │
└─────────────────┘     └─────────────────┘

Iniciação: o cliente chama /v1/transfers/initiate
Detecção: o plugin compara o ISPB do destinatário com o ISPB da organização
Validação: o destinatário é validado no CRM
Confirmação: o cliente chama /v1/transfers/process
Execução: uma transação atômica é criada no Midaz (débito + crédito)
Conclusão: a transferência é concluída imediatamente

Timeline

T+0:     POST /v1/transfers/process
         ├─ Verificar ISPB (mesmo = P2P)
         ├─ Validar destinatário no CRM
         └─ Validar saldo do remetente

T+1s:    Criar transação atômica no Midaz
         ├─ Débito da conta do remetente
         └─ Crédito na conta do destinatário

T+2s:    Transferência concluída
         └─ Status: COMPLETED

SLA: < 2 segundos (vs TED OUT < 10 minutos)

Iniciando uma transferência P2P

O processo é idêntico ao TED OUT. O plugin detecta automaticamente que é P2P.

Etapa 1: Iniciar

POST /v1/transfers/initiate

{
  "senderAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "987654",
    "accountType": "CHECKING",
    "taxId": "98765432100",
    "name": "Ana Costa"
  },
  "amount": 500.00,
  "description": "Transferência interna"
}

Response

{
  "initiationId": "e5f6a7b8-c9d0-1234-efgh-567890123456",
  "feeAmount": 0.00,
  "totalAmount": 500.00,
  "estimatedCompletionAt": "2026-01-21T22:00:02-03:00",
  "expiresAt": "2026-01-22T22:00:00-03:00",
  "status": "PENDING_CONFIRMATION"
}

Note que o estimatedCompletionAt é praticamente imediato (2 segundos), indicando que será processado como P2P.

Etapa 2: Confirmar

POST /v1/transfers/process

{
  "initiationId": "e5f6a7b8-c9d0-1234-efgh-567890123456"
}

Response

{
  "transferId": "f6a7b8c9-d0e1-2345-fghi-678901234567",
  "confirmationNumber": "P2P20260121001",
  "status": "COMPLETED",
  "feeAmount": 0.00,
  "totalAmount": 500.00
}

O status já retorna como COMPLETED — a transferência é instantânea.

Estados do P2P

O ciclo de estados é mais simples que o TED OUT:

CREATED → PROCESSING → COMPLETED
                    → FAILED
       → CANCELLED

Estado	Descrição
`CREATED`	Transferência criada
`PROCESSING`	Executando transação no Midaz
`COMPLETED`	Transferência concluída
`FAILED`	Erro no Midaz (raro)
`CANCELLED`	Cancelada antes do processamento

Na prática, a transição de CREATED para COMPLETED ocorre em menos de 2 segundos.

Consultar transferência P2P

GET /v1/transfers/{transferId}

{
  "transferId": "f6a7b8c9-d0e1-2345-fghi-678901234567",
  "type": "P2P",
  "status": "COMPLETED",
  "sender": {
    "accountId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "João Santos"
  },
  "recipient": {
    "accountId": "660e8400-e29b-41d4-a716-446655440001",
    "ispb": "12345678",
    "branch": "0001",
    "account": "987654",
    "accountType": "CHECKING",
    "taxId": "98765432100",
    "name": "Ana Costa"
  },
  "amount": 500.00,
  "feeAmount": 0.00,
  "totalAmount": 500.00,
  "confirmationNumber": "P2P20260121001",
  "createdAt": "2026-01-21T22:00:00-03:00",
  "completedAt": "2026-01-21T22:00:01-03:00",
  "statusHistory": [
    {"status": "CREATED", "timestamp": "2026-01-21T22:00:00-03:00"},
    {"status": "PROCESSING", "timestamp": "2026-01-21T22:00:00-03:00"},
    {"status": "COMPLETED", "timestamp": "2026-01-21T22:00:01-03:00"}
  ]
}

O campo type é P2P e não há controlNumber (pois não passou pelo JD SPB).

Tarifas P2P

Tarifas para transferências P2P são configuradas separadamente das tarifas de TED:

Configuração	Descrição
`p2p_fee_enabled`	Habilita cobrança de tarifa em P2P
`p2p_fee_type`	Tipo de tarifa (fixa, percentual, escalonada)

É comum que instituições não cobrem tarifa em transferências internas, mas a configuração está disponível.

Funcionamento 24/7

Diferente do TED, transferências P2P podem ser realizadas a qualquer momento:

Dias úteis: funciona normalmente
Finais de semana: funciona normalmente
Feriados: funciona normalmente
Madrugada: funciona normalmente

Não há validação de horário de funcionamento para P2P, pois a operação não depende do SPB.

Validação do destinatário

O plugin valida o destinatário de duas formas:

Por dados bancários

Se o destinatário for informado com ISPB, agência e conta:

Verifica se o ISPB corresponde ao da organização
Busca a conta no CRM pelos dados bancários
Valida se o documento confere

Por accountId (otimizado)

Se você já conhece o accountId Midaz do destinatário, você pode usar uma validação mais direta através do CRM.

Tratamento de erros

Destinatário não encontrado (404)

{
  "code": "BTF-0500",
  "title": "Account Not Found",
  "message": "Recipient account not found in CRM.",
  "fields": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "987654"
  }
}

Saldo insuficiente (422)

{
  "code": "BTF-2001",
  "title": "Insufficient Balance",
  "message": "Sender account does not have sufficient balance.",
  "fields": {
    "available": 300.00,
    "required": 500.00
  }
}

Mesma conta de origem e destino (400)

{
  "code": "BTF-0001",
  "title": "Invalid Input",
  "message": "Sender and recipient cannot be the same account."
}

Casos de uso comuns

Caso	Descrição
Transferência entre usuários	Cliente A transfere para Cliente B
Movimentação entre contas próprias	Cliente move entre conta corrente e poupança
Pagamento interno	Empresa paga funcionário na mesma instituição
Split de pagamento	Distribuição de valores entre múltiplas contas

Atomicidade

Transferências P2P são atômicas no Midaz:

O débito e o crédito ocorrem na mesma transação
Se qualquer parte falhar, toda a operação é revertida
Não há estado intermediário onde o dinheiro “desaparece”

Isso garante consistência mesmo em cenários de falha.

Sem risco de duplicação: A transação Midaz atômica elimina a necessidade de janela de deduplicação para P2P.

​Quando usar P2P

​Vantagens do P2P

​Comparativo com TED OUT

​Como funciona

​Timeline

​Iniciando uma transferência P2P

​Etapa 1: Iniciar

​Response

​Etapa 2: Confirmar

​Response

​Estados do P2P

​Consultar transferência P2P

​Tarifas P2P

​Funcionamento 24/7

​Validação do destinatário

​Por dados bancários

​Por accountId (otimizado)

​Tratamento de erros

​Destinatário não encontrado (404)

​Saldo insuficiente (422)

​Mesma conta de origem e destino (400)

​Casos de uso comuns

​Atomicidade

Quando usar P2P

Vantagens do P2P

Comparativo com TED OUT

Como funciona

Timeline

Iniciando uma transferência P2P

Etapa 1: Iniciar

Response

Etapa 2: Confirmar

Response

Estados do P2P

Consultar transferência P2P

Tarifas P2P

Funcionamento 24/7

Validação do destinatário

Por dados bancários

Por accountId (otimizado)

Tratamento de erros

Destinatário não encontrado (404)

Saldo insuficiente (422)

Mesma conta de origem e destino (400)

Casos de uso comuns

Atomicidade