Pular para o conteúdo principal

​
Visão Geral

O fluxo de PIX OUT permite que você transfira valores da sua conta Owem para qualquer conta bancária no Brasil, usando uma chave PIX.

​
Fluxo Completo

​
Passo 1: Validar Saldo

Antes de enviar, verifique se há saldo suficiente: 
curl -X GET "https://api.owem.com.br/v4/i/bank-accounts/{accountId}/balance" \
  -u "API_KEY:API_SECRET"

​
Passo 2: Enviar Transferência

curl -X POST "https://api.owem.com.br/v4/i/bank-accounts/{accountId}/transfer/external" \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "[email protected]",
    "amount": 500.00,
    "description": "Pagamento Fornecedor #123",
    "externalId": "PAG-20251226-001"
  }'

​
Parâmetros Importantes

CampoDescrição
pixKeyChave PIX de destino (CPF, CNPJ, email, telefone, aleatória)
amountValor em BRL (> 0, duas casas decimais)
descriptionDescrição da transferência (máx. 140 caracteres)
externalIdSeu identificador único para idempotência
Sempre envie externalId para garantir idempotência. Se a requisição falhar e você repetir, não haverá duplicação.

​
Passo 3: Acompanhar Status

A resposta inicial pode vir como processing. Use uma das opções abaixo para acompanhar:

​
Opção A: Webhook (Recomendado)

Configure webhook para pix_out:processing. O status final será succeeded ou failed. 
{
  "webhookId": "wh_abc123",
  "event": "pix_out:processing",
  "object": {
    "endToEndId": "E123456789...",
    "externalId": "PAG-20251226-001",
    "status": "succeeded",
    "grossAmount": 500.0,
    "feeAmount": 0.08,
    "netAmount": 500.08
  }
}

​
Opção B: Consulta Direta

curl -X GET "https://api.owem.com.br/v4/i/bank-accounts/{accountId}/transfer/external/{endToEndId}" \
  -u "API_KEY:API_SECRET"

​
Opção C: Consulta no Ledger

# Por externalId (seu identificador)
curl -X GET "https://api.owem.com.br/v4/i/ledger/external-id/{externalId}" \
  -u "API_KEY:API_SECRET"

# Por endToEndId (identificador PIX)
curl -X GET "https://api.owem.com.br/v4/i/ledger/end-to-end/{endToEndId}" \
  -u "API_KEY:API_SECRET"

​
Modo de Teste

Para testar sem afetar o saldo real: 
{
  "pixKey": "[email protected]",
  "amount": 0.01,
  "description": "Teste",
  "externalId": "TEST-001",
  "test": true,
  "testStatus": "succeeded"
}
Operações com test: true não afetam o saldo, não geram movimentação no Ledger e não disparam integração PIX real.

​
Tratamento de Erros

HTTPCausaAção
400Chave PIX inválidaVerificar formato da chave
404Conta não encontradaVerificar accountId
422Saldo insuficienteVerificar saldo antes de enviar
422Limite excedidoVerificar limites da conta
429Rate limitAguardar e tentar novamente

​
Boas Práticas

Garante idempotência e facilita conciliação no seu sistema.
Evita erros 422 e melhora a experiência do usuário.
Não dependa apenas da resposta síncrona. Configure webhooks para receber o status final.
Em caso de timeout ou erro 5xx, implemente retry com backoff exponencial.

​
Eventos de Webhook Relacionados

EventoQuando ocorre
pix_out:processingTransferência registrada/confirmada
pix_out:refunded_processingDevolução iniciada

​
Próximos Passos

Configurar Webhooks

Receba notificações em tempo real

Conciliação

Use o Ledger para reconciliar