Concepts

Fundamental concepts for integrating with the Owem Pay API.

Authentication Model

The API uses two-level authentication:

Component	Description	Usage
Bearer Token	JWT generated via /api/v2/external/auth-token	Header Authorization: Bearer {token} in all requests
HMAC-SHA512	Request body signature	Header hmac in transactional requests (POST)

Authentication Flow

1. Send client_id and client_secret to the auth-token endpoint
2. Receive the access_token (valid for 60 minutes)
3. Include the token in all requests: Authorization: Bearer {access_token}
4. For POST requests, calculate the HMAC-SHA512 of the body and send it in the hmac header

Full details: Authentication | HMAC-SHA512

Monetary Values

All values are represented as integers in cents. Never use floating point.

Value	Representation	JSON Field
BRL 1.00	100	"amount": 100
BRL 150.50	15050	"amount": 15050
BRL 1,000.00	100000	"amount": 100000
BRL 10,000.00	1000000	"amount": 1000000

Conversion

To convert cents to BRL: divide by 100. To convert BRL to cents: multiply by 100 and round.

Transaction Status

Status	Description
pending	Awaiting payment or approval
processing	Transaction in processing at SPI
completed	Transaction completed successfully
settled	Settlement confirmed by BACEN
failed	Transaction failed
refunded	Transaction refunded (total or partially)
cancelled	Transaction cancelled or expired

End-to-End ID (E2E ID)

Unique identifier of a PIX transaction within the Central Bank ecosystem. Standard format:

E{ISPB}{YYYYMMDDHHMM}{sequential}

Example: E37839059202603071530000001

Component	Value	Description
E	Fixed prefix	Identifies as E2E ID
37839059	Owem Pay ISPB	8 digits
202603071530	UTC date and time	YYYYMMDDHHMM (12 digits)
000001	Sequential	6 digits

The E2E ID is automatically generated by Owem Pay and returned in the response of each PIX operation. Use it to track transactions between institutions.

PIX Key Types

Type	Format	Example	Individual Limit	Business Limit
cpf	11 digits	12345678901	1	--
cnpj	14 digits	12345678000190	--	1
email	Valid email	contato@empresa.com.br	5	20
phone	+55 + area code + number	+5511999998888	5	20
evp	UUID v4 (random key)	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d	5	20

Response Pattern

All API responses follow the pattern:

Success

{
  "worked": true,
  ...
}

Error

{
  "worked": false,
  "detail": "Error description"
}

The worked field indicates whether the operation was successful (true) or failed (false). In case of error, the detail field describes the reason.