Getting Started

Integrate your application with the Owem Pay API and perform your first PIX operation in just a few minutes.

1. Obtain your credentials

Request from your Owem Pay account administrator:

• Client ID -- your API Key identifier
• Client Secret -- secret key for authentication and HMAC signing

Security

Never expose the client_secret in frontend code or public repositories. Use environment variables on your server.

2. Obtain an access token

All requests require a Bearer token. Generate a token with your credentials:

curl -X POST https://api.owem.com.br/api/v2/external/auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-api-key-id",
    "client_secret": "your-api-key-secret"
  }'

Response:

{
  "worked": true,
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The token expires in 60 minutes. Implement automatic renewal before expiration.

3. Check the balance

Test the integration by querying the account balance:

curl -X GET https://api.owem.com.br/api/v2/external/balance \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "worked": true,
  "balance": 150000,
  "available": 150000,
  "pending": 0,
  "currency": "BRL"
}

Values in cents

All monetary values are integers in cents. 150000 = BRL 1,500.00.

4. Generate a PIX charge (Cash-In)

Create a QR Code to receive a payment:

BODY='{"amount":10000,"description":"Order #1234"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/v2/external/pix/cash-in \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Response:

{
  "worked": true,
  "transaction_id": "PIXIN20260307a1b2c3d4e5f6",
  "end_to_end_id": "E37839059202603071234000001",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,...",
  "amount": 10000,
  "status": "pending"
}

Display the qr_code_image or the copy-and-paste code (qr_code) to the payer.

5. Check the status

Track the payment by querying the transaction_id:

curl -X GET https://api.owem.com.br/api/v2/external/transactions/PIXIN20260307a1b2c3d4e5f6 \
  -H "Authorization: Bearer $TOKEN"

When the payment is confirmed, the status changes to completed.

6. Receive notifications (Webhooks)

To receive real-time notifications (recommended instead of polling):

BODY='{"url":"https://yoursite.com/webhook","events":["pix.received","pix.completed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/v2/external/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Next Steps

• Authentication -- token flow details
• HMAC-SHA512 -- how to sign transactional requests
• PIX Cash-In -- generate charges
• Statement -- query transactions
• Webhooks -- real-time notifications
• Concepts -- values, statuses, and PIX keys