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 (prefix cli_)
• Client Secret -- secret key for authentication and HMAC signing (prefix sk_)

Security

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

2. Configure authentication

All requests require the Authorization header with your API Key credentials:

# Header format:
Authorization: ApiKey {client_id}:{client_secret}

The API Key is permanent -- it does not expire. No token generation is required.

3. Check the balance

Test the integration by querying the account balance:

curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Response:

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

Monetary values

Request values are in centavos: R$ 30.00 = 3000. Response values are in base units: 300000 / 10,000 = R$ 30.00. Never use floating point -- always integers.

4. Generate a PIX charge (Cash-In)

Create a QR Code to receive R$ 30.00:

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

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

Response:

{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active"
}

Note that you sent 3000 (centavos) and received 300000 (base units). Both represent R$ 30.00.

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 with the transaction_id:

curl -X GET https://api.owem.com.br/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

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

You can also query by external_id:

curl -X GET https://api.owem.com.br/api/external/transactions/ref/order-9876 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

6. Receive notifications (Webhooks)

To receive real-time notifications (recommended over polling):

BODY='{"url":"https://seusite.com.br/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/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Next Steps

• Authentication -- API Key + HMAC (3 layers of security)
• HMAC-SHA512 -- how to sign transactional requests
• PIX Cash-In -- generate charges
• PIX Cash-Out -- send PIX by key
• Statement -- query transactions
• Webhooks -- real-time notifications
• Concepts -- values, status, external_id, idempotency, and PIX keys