Vue d'Ensemble de l'API

L'API Owem Pay permet d'integrer les paiements PIX a votre systeme. Toutes les operations sont authentifiees via API Key + HMAC-SHA512 avec liste blanche d'IP obligatoire.

URL de Base

Environnement	URL
Production	https://api.owem.com.br
Homologation	https://api-hml.owem.com.br

Authentification

Trois couches de securite independantes :

1. Liste blanche d'IP -- l'IP d'origine doit figurer dans la liste blanche configuree sur l'API Key
2. API Key -- En-tete Authorization: ApiKey {client_id}:{client_secret} dans toutes les requetes
3. HMAC-SHA512 -- Signature du body de la requete (obligatoire pour les endpoints POST)

Consultez Authentification et HMAC-SHA512 pour les details.

Format

Champ	Format
Content-Type	application/json
Valeurs d'entree (request)	Entiers en centavos (R$ 30,00 = 3000)
Valeurs de reponse	Entiers en unites de base (R$ 30,00 = 300000, / 10 000 pour reais)
Dates	ISO 8601 (2026-03-09T15:30:00Z)
IDs	UUID v4 ou chaine alphanumerique
E2E ID	E{ISPB}{YYYYMMDD}{HHMM}{6-digit-seq}

Conversion des valeurs

Pour envoyer : multipliez les reais par 100. R$ 30,00 = 3000. Pour lire les reponses : divisez par 10 000. 300000 / 10 000 = R$ 30,00. N'utilisez jamais de virgule flottante -- toujours des entiers.

Schema de Reponse

Succes

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

Erreur

{
  "worked": false,
  "detail": "Saldo insuficiente"
}

Codes HTTP

Code	Signification
200	Succes
201	Ressource creee (webhook)
400	Parametres invalides
401	API Key absente ou invalide / HMAC invalide
403	IP non autorise dans la liste blanche
404	Ressource introuvable
422	Validation echouee (solde insuffisant, cle invalide)
429	Rate limit depasse
500	Erreur interne

Rate Limiting

Type	Limite
Par IP (authentifie)	60 000 requetes/minute
Par IP (non authentifie)	5 requetes/minute

En-tetes de reponse :

X-RateLimit-Remaining: 59997
Retry-After: 3  (uniquement lors d'un 429)

Idempotence

Les requetes POST acceptent l'en-tete Idempotency-Key pour eviter le traitement en double. Le resultat est mis en cache pendant 24 heures. Si la meme cle est renvoyee, l'API retourne la reponse originale avec l'en-tete X-Idempotent-Replay: true.

Idempotency-Key: unique-request-id-123

External ID

Champ optionnel external_id (max 128 chars, alphanumerique + ._:-) accepte dans les cash-in et cash-out. Retourne dans les reponses et webhooks. Permet la consultation par reference :

GET /api/external/transactions/ref/{external_id}

Consultez Concepts pour les details.

Endpoints

PIX Cash Out (Envoi)

Methode	Endpoint	Description
POST	/api/external/pix/cash-out	Envoyer un PIX par cle ou copier-coller
POST	/api/external/pix/cash-out/approve	Approuver un cash-out en attente

PIX Cash In (Encaissement)

Methode	Endpoint	Description
POST	/api/external/pix/cash-in	Generer un QR Code pour encaissement

Consultations

Methode	Endpoint	Description
GET	/api/external/transactions	Lister les transactions
GET	/api/external/transactions/:id	Consulter une transaction par ID
GET	/api/external/transactions/e2e/:e2e_id	Consulter par E2E ID
GET	/api/external/transactions/tag/:tag	Consulter par tag (prefixe)
GET	/api/external/transactions/ref/:external_id	Consulter par external_id
GET	/api/external/transactions/:id/receipt	Recu

Compte

Methode	Endpoint	Description
GET	/api/external/balance	Solde du compte
GET	/api/external/statement	Releve

Cles PIX

Methode	Endpoint	Description
GET	/api/external/pix/keys	Lister les cles PIX du compte

Remboursement

Methode	Endpoint	Description
POST	/api/external/pix/refund	Remboursement PIX (total ou partiel)

MED

Methode	Endpoint	Description
GET	/api/external/med	Lister les MEDs
GET	/api/external/med/:id	Details d'un MED

Validation

Methode	Endpoint	Description
POST	/api/external/cpf/validate	Valider un CPF

Webhooks

Methode	Endpoint	Description
GET	/api/external/webhooks	Lister les webhooks
POST	/api/external/webhooks	Enregistrer un webhook
DELETE	/api/external/webhooks/:id	Supprimer un webhook