Premiers Pas

Integrez votre application avec l'API Owem Pay et realisez votre premiere operation PIX en quelques minutes.

1. Obtenez vos identifiants

Demandez a l'administrateur de votre compte Owem Pay :

• Client ID -- identifiant de votre API Key (prefixe cli_)
• Client Secret -- cle secrete pour l'authentification et la signature HMAC (prefixe sk_)

Securite

N'exposez jamais le client_secret dans du code frontend ou des depots publics. Utilisez des variables d'environnement sur votre serveur.

2. Configurez l'authentification

Toutes les requetes exigent l'en-tete Authorization avec vos identifiants API Key :

# Format de l'en-tete :
Authorization: ApiKey {client_id}:{client_secret}

L'API Key est permanente -- elle n'expire pas. Il n'est pas necessaire de generer des tokens.

3. Consultez le solde

Testez l'integration en consultant le solde du compte :

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

Reponse :

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

Valeurs monetaires

Les valeurs d'entree (request) sont en centavos : R$ 30,00 = 3000. Les valeurs de reponse sont en unites de base : 300000 / 10 000 = R$ 30,00. N'utilisez jamais de virgule flottante -- toujours des entiers.

4. Generez une facturation PIX (Cash-In)

Creez un QR Code pour recevoir 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"

Reponse :

{
  "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"
}

Notez que vous avez envoye 3000 (centavos) et recu 300000 (unites de base). Les deux representent R$ 30,00.

Affichez le qr_code_image ou le code copier-coller (qr_code) au payeur.

5. Consultez le statut

Suivez le paiement en consultant par transaction_id :

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

Lorsque le paiement est confirme, le status passe a completed.

Vous pouvez egalement consulter par external_id :

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

6. Recevez des notifications (Webhooks)

Pour recevoir des notifications en temps reel (recommande au lieu du 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"

Prochaines Etapes

• Authentification -- API Key + HMAC (3 couches de securite)
• HMAC-SHA512 -- comment signer les requetes transactionnelles
• PIX Cash-In -- generer des facturations
• PIX Cash-Out -- envoyer un PIX par cle
• Releve -- consulter les transactions
• Webhooks -- notifications en temps reel
• Concepts -- valeurs, statuts, external_id, idempotence et cles PIX