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"

​
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

​
Tratamento de Timeout

Se a requisição resultar em timeout (conexão interrompida antes da resposta), o pedido pode ter sido processado com sucesso mesmo sem você receber a confirmação. Fluxo recomendado em caso de timeout:
  1. Aguarde 10-20 segundos após o timeout
  2. Consulte pelo externalId que você enviou:
curl -X GET "https://api.owem.com.br/v4/i/ledger/external-id/{externalId}" \
  -u "API_KEY:API_SECRET"
  1. Interprete o resultado:
    • 200 com dados: O pedido foi processado com sucesso, use o endToEndId retornado
    • 400 com “Entry not found”: O pedido ainda está sendo processado ou não chegou ao sistema
    • Se após 2-3 minutos ainda retornar “Entry not found”, o pedido não foi recebido e você pode tentar novamente
Nunca reenvie imediatamente após timeout. Sempre consulte pelo externalId primeiro para evitar duplicação de pagamentos.
O webhook será enviado normalmente mesmo em casos de timeout na requisição original. Use webhooks como fonte primária de confirmação.

​
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