PIX Cash Out by Key

Performs a PIX transfer using the recipient's PIX key.

Endpoint

POST /api/external/pix/cash-out

Headers

Header	Type	Required	Description
Authorization	String	Yes	ApiKey {client_id}:{client_secret}
Content-Type	String	Yes	application/json
hmac	String	Yes	HMAC-SHA512 signature of the body (hex)
Idempotency-Key	String	No	Unique key to prevent duplicate processing (max 256 chars)

Authentication

See Authentication. The HMAC signature must be generated as described in HMAC-SHA512.

Request Body

Field	Type	Required	Description
amount	Integer	Yes	Amount in centavos. R$ 30.00 = 3000
pix_key	String	Yes	Recipient's PIX key
pix_key_type	String	No	Key type: cpf, cnpj, email, phone, evp. If omitted, auto-detected from the key value.
description	String	No	Transfer description (max 140 characters)
external_id	String	No	Your system identifier for tracking. Max 128 chars. Only a-zA-Z0-9._:-. Returned in responses and webhooks.

Monetary values

Request values are in centavos (R$ 1.00 = 100). Response values are in base units (R$ 1.00 = 10000). To convert the response to BRL, divide by 10,000. Never use floating point.

Example

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

Success Response -- 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"
}

Field	Type	Description
worked	Boolean	true indicates the request was accepted
transaction_id	String	Unique transaction identifier
end_to_end_id	String	End-to-End identifier in SPI/BACEN (format E{ISPB}...)
external_id	String	Your identifier, returned as sent. null if not provided
amount	Integer	Transfer amount in base units (/ 10,000 for BRL). 300000 = R$ 30.00
fee_amount	Integer	Fee charged in base units (/ 10,000 for BRL)
net_amount	Integer	Net amount (amount + fee) in base units
status	String	accepted (accepted for processing) or completed (settled)
detail	String	Descriptive message

Error Response -- 400

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

Error Response -- 422

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

PIX Key Types

Type	Format	Example
cpf	11 digits (no punctuation)	12345678901
cnpj	14 digits (no punctuation)	12345678000199
email	Email address	nome@empresa.com.br
phone	+55 + area code + number	+5511999998888
evp	UUID v4	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

11-Digit Keys — CPF vs Phone Ambiguity

Keys with exactly 11 digits can be either a CPF or a mobile phone number (area code + 9xxxx-xxxx). When the key is ambiguous, the API returns the pix_key_ambiguous error.

Recommended solution:

1. Use the CPF Validation endpoint (POST /api/external/cpf/validate) to check if the 11 digits form a valid CPF
2. If valid: true → send pix_key_type: "cpf" in the cash-out request
3. If valid: false → it's a phone number, send pix_key_type: "phone" (the API automatically adds the +55 prefix)

// Example automated flow
async function resolveKeyType(key) {
  if (key.length !== 11 || /\D/.test(key)) return null; // no ambiguity
  
  const { data } = await api.post('/api/external/cpf/validate', { cpf: key });
  return data.valid ? 'cpf' : 'phone';
}

Tip: Keys with formatting (dots, dashes) or with the +55 prefix are auto-detected — pix_key_type is only needed for raw 11-digit numbers.

Next Steps

After creating the transfer, track the status via:

• Query by ID
• Query by E2E ID
• Query by Tag
• Query by External ID -- GET /api/external/transactions/ref/{external_id}

Or receive confirmation automatically via Webhook.