PIX Cash Out por Clave

Realiza una transferencia PIX utilizando la clave PIX del destinatario.

Endpoint

POST /api/external/pix/cash-out

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}
Content-Type	String	Si	application/json
hmac	String	Si	Firma HMAC-SHA512 del body (hex)
Idempotency-Key	String	No	Clave unica para evitar procesamiento duplicado (max 256 chars)

Autenticacion

Vea Autenticacion. La firma HMAC debe generarse conforme lo descrito en HMAC-SHA512.

Request Body

Campo	Tipo	Obligatorio	Descripcion
amount	Integer	Si	Valor en centavos. R$ 30,00 = 3000
pix_key	String	Si	Clave PIX del destinatario
pix_key_type	String	No	Tipo de clave: cpf, cnpj, email, phone, evp. Si se omite, se detecta automaticamente a partir de la clave.
description	String	No	Descripcion de la transferencia (max 140 caracteres)
external_id	String	No	Identificador de su sistema para rastreo. Max 128 chars. Solo a-zA-Z0-9._:-. Retornado en respuestas y webhooks.

Valores monetarios

Los valores de entrada son en centavos (R$ 1,00 = 100). Los valores de respuesta son en unidades base (R$ 1,00 = 10000). Para convertir la respuesta a reales, divida por 10.000. Nunca use punto flotante.

Ejemplo

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"
  }'

Respuesta de Exito -- 200

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

Campo	Tipo	Descripcion
worked	Boolean	true indica que la solicitud fue aceptada
transaction_id	String	Identificador unico de la transaccion
end_to_end_id	String	Identificador End-to-End en el SPI/BACEN (formato E{ISPB}...)
external_id	String	Su identificador, retornado tal como fue enviado. null si no fue informado
amount	Integer	Valor de la transferencia en unidades base (/ 10.000 para reales). 300000 = R$ 30,00
fee_amount	Integer	Tarifa cobrada en unidades base (/ 10.000 para reales)
net_amount	Integer	Valor neto (amount + fee) en unidades base
status	String	processing (en liquidacion) o completed (liquidado)
detail	String	Mensaje descriptivo

Respuesta de Error -- 400

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

Respuesta de Error -- 422

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

Tipos de Clave PIX

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

Proximos Pasos

Despues de crear la transferencia, acompane el estado via:

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

O reciba la confirmacion automaticamente via Webhook.