API Overview

The Owem Pay API allows you to integrate PIX payments into your system. All operations are authenticated via API Key + HMAC-SHA512 with mandatory IP Whitelist.

Base URL

Environment	URL
Production	https://api.owem.com.br
Homologation	https://api-hml.owem.com.br

Authentication

Three independent security layers:

1. IP Whitelist -- Source IP must be in the whitelist configured on the API Key
2. API Key -- Header Authorization: ApiKey {client_id}:{client_secret} in all requests
3. HMAC-SHA512 -- Request body signature (required for POST endpoints)

See Authentication and HMAC-SHA512 for details.

Format

Field	Format
Content-Type	application/json
Request values	Integers in centavos (R$ 30.00 = 3000)
Response values	Integers in base units (R$ 30.00 = 300000, / 10,000 for BRL)
Dates	ISO 8601 (2026-03-09T15:30:00Z)
IDs	UUID v4 or alphanumeric string
E2E ID	E{ISPB}{YYYYMMDD}{HHMM}{6-digit-seq}

Value conversion

To send: multiply BRL by 100. R$ 30.00 = 3000. To read responses: divide by 10,000. 300000 / 10,000 = R$ 30.00. Never use floating point -- always integers.

Response Pattern

Success

{
  "worked": true,
  "transaction_id": "PIXOUT20260309abcdef123456",
  "status": "processing"
}

Error

{
  "worked": false,
  "detail": "Insufficient balance"
}

HTTP Codes

Code	Meaning
200	Success
201	Resource created (webhook)
400	Invalid parameters
401	Missing or invalid API Key / Invalid HMAC
403	IP not authorized in whitelist
404	Resource not found
422	Validation failed (insufficient balance, invalid key)
429	Rate limit exceeded
500	Internal error

Rate Limiting

Type	Limit
Per IP (authenticated)	60,000 requests/minute
Per IP (unauthenticated)	5 requests/minute

Response headers:

X-RateLimit-Remaining: 59997
Retry-After: 3  (only when 429)

Idempotency

POST requests accept the Idempotency-Key header to prevent duplicate processing. The result is cached for 24 hours. If the same key is resent, the API returns the original response with the header X-Idempotent-Replay: true.

Idempotency-Key: unique-request-id-123

External ID

Optional external_id field (max 128 chars, alphanumeric + ._:-) accepted in cash-in and cash-out. Returned in responses and webhooks. Allows lookup by reference:

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

See Concepts for details.

Endpoints

PIX Cash Out (Send)

Method	Endpoint	Description
POST	/api/external/pix/cash-out	Send PIX by key or copy-and-paste
POST	/api/external/pix/cash-out/approve	Approve pending cash-out

PIX Cash In (Receive)

Method	Endpoint	Description
POST	/api/external/pix/cash-in	Generate QR Code for receiving

Queries

Method	Endpoint	Description
GET	/api/external/transactions	List transactions
GET	/api/external/transactions/:id	Query transaction by ID
GET	/api/external/transactions/e2e/:e2e_id	Query by E2E ID
GET	/api/external/transactions/tag/:tag	Query by tag (prefix)
GET	/api/external/transactions/ref/:external_id	Query by external_id
GET	/api/external/transactions/:id/receipt	Receipt

Account

Method	Endpoint	Description
GET	/api/external/balance	Account balance
GET	/api/external/statement	Statement

PIX Keys

Method	Endpoint	Description
GET	/api/external/pix/keys	List account PIX keys

Refund

Method	Endpoint	Description
POST	/api/external/pix/refund	PIX refund (total or partial)

MED

Method	Endpoint	Description
GET	/api/external/med	List MEDs
GET	/api/external/med/:id	MED details

Validation

Method	Endpoint	Description
POST	/api/external/cpf/validate	Validate CPF

Webhooks

Method	Endpoint	Description
GET	/api/external/webhooks	List webhooks
POST	/api/external/webhooks	Register webhook
DELETE	/api/external/webhooks/:id	Remove webhook