PIX Cash Out Copia e Cola

Realiza uma transferencia PIX utilizando o codigo EMV (copia e cola) extraido de um QR Code PIX.

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)

Request Body

Campo	Tipo	Obrigatorio	Descricao
amount	Integer	Sim	Valor em centavos. R$ 30,00 = 3000
emv_code	String	Sim	Codigo EMV copia e cola do QR Code PIX
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.

Codigo Copia e Cola

O campo emv_code aceita o codigo EMV completo copiado de um QR Code PIX. A API extrai automaticamente a chave PIX, os dados do recebedor e o valor original da cobranca a partir do payload EMV.

Valor da transferencia

O campo amount deve ser informado mesmo quando o QR Code ja contem um valor. A API valida que o valor informado seja compativel com o QR Code (estatico ou dinamico).

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,
    "emv_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865802BR5913NOME RECEBEDOR6008BRASILIA62070503***6304ABCD",
    "description": "Pagamento via QR Code",
    "external_id": "invoice-4521"
  }'

Resposta de Sucesso -- 200

{
  "worked": true,
  "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
  "end_to_end_id": "E37839059202603091530abcdef01",
  "external_id": "invoice-4521",
  "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
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": "Codigo EMV invalido ou nao reconhecido"
}

Resposta de Erro -- 422

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

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.