API Overview

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

Base URL

Environment	URL
Production	https://api.owem.com.br

Authentication

All requests require:

1. Auth Token — JWT obtained via POST /api/v2/external/auth-token
2. HMAC-SHA512 — Request body signature (required for transactional endpoints)

See Auth Token and HMAC-SHA512 for details.

Format

Field	Format
Content-Type	application/json
Monetary values	Integer in cents (BRL 100.00 = 10000)
Dates	ISO 8601 (2026-03-09T15:30:00Z)
IDs	UUID v4 or alphanumeric string
E2E ID	E{ISPB}{YYYYMMDD}{HHMM}{6-digit-seq}

Response Pattern

Success

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

Error

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

HTTP Codes

Code	Meaning
200	Success
400	Invalid parameters
401	Missing or expired token
403	Invalid HMAC
404	Resource not found
422	Validation failed (insufficient balance, invalid key)
429	Rate limit exceeded
500	Internal error

Rate Limiting

Type	Limit
Per API Key	120 requests/minute
Per IP	5 requests/minute (unauthenticated)

Response headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1709990520

Idempotency

Write requests (POST) accept the Idempotency-Key header to prevent duplicate processing. The result is cached for 24 hours.

Idempotency-Key: unique-request-id-123

Endpoints

Method	Endpoint	Description
POST	/api/v2/external/auth-token	Generate JWT token
POST	/api/v2/external/pix/cash-out	Send PIX
POST	/api/v2/external/pix/cash-out/approve	Approve pending cash-out
POST	/api/v2/external/pix/cash-in	Generate QR Code for receiving
GET	/api/v2/external/transactions	List transactions
GET	/api/v2/external/transactions/:id	Query transaction by ID
GET	/api/v2/external/transactions/e2e/:e2e_id	Query by E2E ID
GET	/api/v2/external/transactions/tag/:tag	Query by tag
GET	/api/v2/external/transactions/:id/receipt	Receipt
GET	/api/v2/external/balance	Account balance
GET	/api/v2/external/statement	Statement
GET	/api/v2/external/pix/keys	List PIX keys
POST	/api/v2/external/pix/refund	PIX refund
GET	/api/v2/external/med	List MEDs
GET	/api/v2/external/med/:id	MED details
POST	/api/v2/external/cpf/validate	Validate CPF
GET	/api/v2/external/webhooks	List webhooks
POST	/api/v2/external/webhooks	Register webhook
DELETE	/api/v2/external/webhooks/:id	Remove webhook