PIX Cash Out por Chave

Realiza uma transferencia PIX utilizando a chave PIX do destinatario.

Endpoint

POST /api/external/pix/cash-out

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	String	Sim	ApiKey {client_id}:{client_secret}
Content-Type	String	Sim	application/json
hmac	String	Sim	Assinatura HMAC-SHA512 do body (hex)
Idempotency-Key	String	Nao	Chave unica para evitar processamento duplicado (max 256 chars)

Autenticacao

Veja Autenticacao. A assinatura HMAC deve ser gerada conforme descrito em HMAC-SHA512.

Request Body

Campo	Tipo	Obrigatorio	Descricao
amount	Integer	Sim	Valor em centavos. R$ 30,00 = 3000
pix_key	String	Sim	Chave PIX do destinatario
pix_key_type	String	Nao	Tipo da chave: cpf, cnpj, email, phone, evp. Se omitido, detectado automaticamente a partir da chave.
description	String	Nao	Descricao da transferencia (max 140 caracteres)
external_id	String	Nao	Identificador do seu sistema para rastreamento. Max 128 chars. Apenas a-zA-Z0-9._:-. Retornado em respostas e webhooks.

Valores monetarios

Valores de entrada sao em centavos (R$ 1,00 = 100). Valores de resposta sao em unidades base (R$ 1,00 = 10000). Para converter a resposta para reais, divida por 10.000. Nunca use ponto flutuante.

Exemplo

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" \
  -d '{
    "amount": 3000,
    "pix_key": "12345678901",
    "pix_key_type": "cpf",
    "description": "Pagamento fornecedor",
    "external_id": "order-9876"
  }'

Resposta de Sucesso -- 200

{
  "worked": true,
  "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
  "end_to_end_id": "E37839059202603091530abcdef01",
  "external_id": "order-9876",
  "amount": 300000,
  "fee_amount": 350,
  "net_amount": 300350,
  "status": "accepted",
  "detail": "PIX enviado para processamento"
}

Campo	Tipo	Descricao
worked	Boolean	true indica que a requisicao foi aceita
transaction_id	String	Identificador unico da transacao
end_to_end_id	String	Identificador End-to-End no SPI/BACEN (formato E{ISPB}...)
external_id	String	Seu identificador, retornado tal como enviado. null se nao informado
amount	Integer	Valor da transferencia em unidades base (÷ 10.000 para reais). 300000 = R$ 30,00
fee_amount	Integer	Tarifa cobrada em unidades base (÷ 10.000 para reais)
net_amount	Integer	Valor liquido (amount + fee) em unidades base
status	String	accepted (aceito para processamento) ou completed (liquidado)
detail	String	Mensagem descritiva

Resposta de Erro -- 400

{
  "worked": false,
  "detail": "Chave PIX invalida"
}

Resposta de Erro -- 422

{
  "worked": false,
  "detail": "Saldo insuficiente"
}

Tipos de Chave PIX

Tipo	Formato	Exemplo
cpf	11 digitos (sem pontuacao)	12345678901
cnpj	14 digitos (sem pontuacao)	12345678000199
email	Endereco de e-mail	nome@empresa.com.br
phone	+55 + DDD + numero	+5511999998888
evp	UUID v4	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

Chaves de 11 digitos — Ambiguidade CPF vs Telefone

Chaves com exatamente 11 digitos podem ser tanto um CPF quanto um telefone celular (DDD + 9xxxx-xxxx). Quando a chave e ambigua, a API retorna o erro pix_key_ambiguous.

Solucao recomendada:

1. Use o endpoint Validacao CPF (POST /api/external/cpf/validate) para verificar se os 11 digitos formam um CPF valido
2. Se valid: true → envie pix_key_type: "cpf" no cash-out
3. Se valid: false → e um telefone, envie pix_key_type: "phone" (a API adiciona automaticamente o prefixo +55)

// Exemplo de fluxo automatizado
async function resolveKeyType(key) {
  if (key.length !== 11 || /\D/.test(key)) return null; // sem ambiguidade
  
  const { data } = await api.post('/api/external/cpf/validate', { cpf: key });
  return data.valid ? 'cpf' : 'phone';
}

Dica: chaves com formatacao (pontos, tracos) ou com prefixo +55 sao detectadas automaticamente — pix_key_type so e necessario para 11 digitos puros.

Proximos Passos

Apos criar a transferencia, acompanhe o status via:

• Consultar por ID
• Consultar por E2E ID
• Consultar por Tag
• Consultar por External ID -- GET /api/external/transactions/ref/{external_id}

Ou receba a confirmacao automaticamente via Webhook.