Guia de Integração: PIX Cash-Out

Este guia descreve o fluxo completo para integrar pagamentos PIX (cash-out) via API Owem.

---

Fluxo de Vida de um Pagamento

POST /api/external/pix/cash-out
         │
         ▼
   ┌─────────────┐
   │  accepted    │ ← HTTP 200, worked: true, final: false
   │  (pendente)  │
   └──────┬──────┘
          │
    ┌─────┴─────┐
    ▼           ▼
┌────────┐  ┌────────┐
│settled │  │rejected│
│(final) │  │(final) │
└────────┘  └────────┘

Importante

• worked: true significa que o pagamento foi aceito para processamento, NÃO que foi liquidado.
• final: true significa que o pagamento atingiu estado terminal (settled ou rejected).
• final: false significa que ainda está em processamento.

---

Enviando um Pagamento

curl -X POST https://api.owem.com.br/api/external/pix/cash-out \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC_SHA512" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "amount": 3000,
    "pix_key": "12345678901",
    "pix_key_type": "cpf",
    "description": "Pagamento fornecedor",
    "external_id": "order-12345"
  }'

Campos do Request

Campo	Tipo	Obrigatório	Descrição
amount	Integer	Sim	Valor em centavos (R$ 30,00 = 3000)
pix_key	String	Condicional	Chave PIX (CPF, CNPJ, email, telefone, EVP)
pix_key_type	String	Recomendado	cpf, cnpj, email, phone, evp
emv	String	Condicional	Copia e Cola (alternativa a pix_key)
description	String	Não	Descrição (max 140 caracteres)
external_id	String	Não	ID no seu sistema (max 128 chars, a-zA-Z0-9._:-)
Idempotency-Key	Header	Recomendado	Previne duplicatas em retry

Chaves de 11 dígitos

Se a chave tem exatamente 11 dígitos, pode ser CPF ou telefone. Envie pix_key_type para evitar erro pix_key_ambiguous.

Resposta de Sucesso (HTTP 200)

{
  "worked": true,
  "final": false,
  "transaction_id": "PIXOUT20260405abc123",
  "end_to_end_id": "E37839059202604051530abcdef01",
  "external_id": "order-12345",
  "amount": 30000000,
  "fee_amount": 3500,
  "net_amount": 30003500,
  "status": "accepted",
  "detail": "PIX enviado para processamento"
}

Unidades de valor na resposta

O amount na resposta está em unidades base (subcentavos). Para converter para reais: amount / 10000. Exemplo: 30000000 / 10000 = R$ 3.000,00.

---

Acompanhando o Status

Opção 1: Webhooks (recomendado)

Configure um webhook para receber notificações automáticas:

Evento	Quando	Significado
pix.payout.confirmed	Liquidação BACEN	Pagamento confirmado (terminal)
pix.payout.failed	Rejeição BACEN	Pagamento rejeitado (terminal)

Opção 2: Polling (GET)

# Por transaction_id
GET /api/external/transactions/{transaction_id}

# Por E2E ID
GET /api/external/transactions/e2e/{end_to_end_id}

# Por external_id
GET /api/external/transactions/ref/{external_id}

Frequência de polling

O BACEN liquida em ~1.6 segundos. Recomendamos polling a cada 2 segundos, máximo 5 tentativas. Após isso, confie nos webhooks.

---

Requests Sequenciais

Requests simultâneos para a mesma conta

O sistema usa lock exclusivo por conta com backoff progressivo para garantir consistência de saldo. Requests concorrentes são enfileirados internamente e processados em sequência. Se o saldo é insuficiente, o request retorna insufficient_balance.

Recomendação: para melhor desempenho, envie requests sequencialmente quando possível.

---

Códigos de Erro

Validação (HTTP 422)

Código	Descrição	Ação
invalid_amount	Valor inválido (<=0 ou não inteiro)	Corrigir valor
pix_key_ambiguous	11 dígitos pode ser CPF ou telefone	Enviar pix_key_type
destination_not_found	Chave PIX não registrada no DICT	Verificar chave
self_transfer	Transferência para própria chave	Usar TEF
same_institution_transfer	Destinatário na mesma instituição	Usar TEF
nighttime_limit_exceeded	Fora do horário permitido	Aguardar horário

Integração (HTTP 400)

Código	Descrição	Ação
insufficient_balance	Saldo insuficiente (valor + taxa)	Verificar saldo
lock_unavailable	Outra transação em andamento	Eliminado -- requests concorrentes agora retornam insufficient_balance se o saldo é insuficiente, ou sucedem se o saldo está disponível
provider_timeout	Timeout na comunicação BACEN	Reenviar após 5s

---

Idempotência

Envie o header Idempotency-Key com um ID único do seu sistema. Se o mesmo key for enviado novamente, a API retorna o resultado da primeira execução sem processar novamente.

# Primeira chamada — processa normalmente
curl -H "Idempotency-Key: pay-001" ...

# Segunda chamada com mesmo key — retorna resultado anterior
curl -H "Idempotency-Key: pay-001" ...

---

Circuit Breaker (recomendação)

Implemente circuit breaker no seu cliente:

1. Contagem: Após 3 erros consecutivos (timeout ou 5xx), pare de enviar por 30 segundos
2. Half-open: Após 30s, envie 1 request de teste
3. Reset: Se o teste funcionar, retome operação normal

---

Comprovante

Após liquidação (final: true), o comprovante está disponível:

GET /api/external/transactions/{transaction_id}/receipt

Retorna dados estruturados do comprovante (pagador, recebedor, valor, data, E2E).