Vue d'ensemble de l'API

L'API Owem Pay permet d'intégrer les paiements PIX à votre système. Toutes les opérations exigent une API Key et une IP Whitelist ; les endpoints POST ajoutent HMAC-SHA512 sur le body.

URL de base

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

Authentification

Couches de sécurité (par type de requête) :

1. IP Whitelist (toutes) -- l'IP d'origine doit figurer dans la whitelist configurée sur l'API Key
2. API Key (toutes) -- En-tête Authorization: ApiKey {client_id}:{client_secret} dans toutes les requêtes
3. HMAC-SHA512 (uniquement POST) -- Signature du body de la requête ; obligatoire pour POST /pix/cash-in, POST /pix/cash-out, POST /cpf/validate, POST /webhooks, POST /pix/refund. Les requêtes GET et DELETE ne portent pas de HMAC (aucun body à signer).

Ordre alphabétique obligatoire dans le body HMAC

Les requêtes POST qui exigent HMAC doivent signer le body avec les clés en ordre alphabétique. Le backend exécute Jason.decode + Jason.encode! sur le body pour validation, ce qui réordonne les clés. Si votre client n'alphabétise pas avant de signer, le HMAC calculé localement ne correspondra pas à celui du serveur → HTTP 401.

Détails complets : HMAC-SHA512.

Consultez Authentification et HMAC-SHA512 pour les détails.

Format

Champ	Format
Content-Type	application/json
Valeurs d'entrée (request)	Entiers en centavos (R$ 1,00 = 100)
Valeurs de réponse	Entiers en subcentavos (unités de base ; R$ 1,00 = 10000, ÷ 10 000 pour obtenir des reais)
Dates	ISO 8601 en UTC avec suffixe Z (2026-03-09T15:30:00Z)
IDs	UUID v4 ou chaîne alphanumérique
E2E ID	^E\d{8}[a-zA-Z0-9]{22,26}$ (standard BACEN, 31-35 caractères, le suffixe peut contenir des lettres)

Terminologie

Dans cette documentation, subcentavos et unités de base désignent la même unité (10 000 = R$ 1,00). Le terme « unités de base » apparaît dans quelques exemples historiques ; considérez-le comme synonyme de subcentavos. Divisez toujours la valeur de la réponse par 10 000 pour obtenir des reais.

E2E peut contenir des lettres

Le suffixe après E + ISPB + timestamp est alphanumérique de 9 à 13 caractères (pas uniquement des chiffres). Des banques comme Nubank émettent des E2E avec des lettres à la fin. Validez toujours avec la regex complète. Détails dans PIX Cash-In par E2E ID.

Conversion des valeurs

Pour envoyer : multipliez les reais par 100. R$ 1,00 = 100. Pour lire les réponses : divisez par 10 000. 10000 ÷ 10 000 = R$ 1,00. N'utilisez jamais de virgule flottante -- uniquement des entiers.

Casse des clés (camelCase optionnel)

Les réponses JSON utilisent snake_case par défaut (ex. : transaction_id, end_to_end_id). Si votre client préfère camelCase, envoyez l'en-tête :

X-Key-Case: camelCase

Le backend convertit toutes les clés du JSON de réponse (y compris les objets imbriqués) automatiquement. Exemple : transaction_id → transactionId, pix_key_type → pixKeyType. L'en-tête n'affecte pas le body d'entrée — envoyez toujours en snake_case lors d'un POST.

Schéma de réponse

Succès

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

Erreur

Le format de l'erreur varie selon la couche qui a rejeté la requête :

// Plug HMAC (401 signature invalide)
{ "worked": false, "detail": "Invalid HMAC signature" }

// ApiKeyAuth (401 / 403)
{ "error": { "status": 401, "message": "Invalid API key" } }

// FallbackController (404 / 400 / 409 / 422 / 500 — cas métier)
{ "errors": { "not_found": "transaction not found" } }

Consultez le tableau complet dans Authentification -- Réponses d'erreur.

Codes HTTP

Code	Signification
200	Succès
201	Ressource créée (webhook)
400	Paramètres invalides
401	API Key absente ou invalide / HMAC invalide
403	IP non autorisé dans la whitelist
404	Ressource introuvable
422	Validation échouée (solde insuffisant, clé invalide)
429	Rate limit dépassé
500	Erreur interne

Rate Limiting

Type	Limite
Par IP (authentifié)	90 000 requêtes/minute (1 500 req/s)
Par IP (authentification / login)	5 requêtes/minute
GET /balance	sans rate limit (polling haute fréquence autorisé)

En-têtes de réponse :

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

Idempotence

Les requêtes POST acceptent l'en-tête Idempotency-Key (max. 256 caractères) pour éviter le traitement en double. Seules les réponses 2xx (succès) sont mises en cache pendant 24 heures. Si la même clé est renvoyée pour la même méthode et le même endpoint, l'API retourne la réponse originale avec l'en-tête X-Idempotent-Replay: true.

Idempotency-Key: unique-request-id-123

Portée de la clé

La clé est liée à méthode + path + Idempotency-Key. La même clé peut être réutilisée sur des endpoints différents sans collision. Les réponses d'erreur (4xx/5xx) ne sont pas mises en cache -- le client peut réessayer après avoir corrigé le problème.

GET/DELETE et Idempotency-Key

Les requêtes GET et DELETE ignorent silencieusement l'en-tête Idempotency-Key -- le plug n'agit que sur POST. Envoyer la clé sur ces méthodes ne provoque pas d'erreur, mais ne génère ni cache ni replay.

Politiques de retry et de quarantaine

• Quarantaine (stage=5) : un PIX Cash-Out bloqué en status: "processing" pendant plus de 30 minutes est déplacé en quarantaine, où il reste en attente de résolution manuelle par l'équipe Owem. Le statut reste "processing" du point de vue du client jusqu'à la finalisation. Détails dans le flux : PIX Lifecycle.
• Retry automatique des webhooks : les deliveries en échec (timeout, 5xx, connexion fermée) sont replanifiées jusqu'à 7 tentatives (intervalles [0, 30s, 2min, 10min, 30min, 1h, 2h, 4h]). Voir Webhooks.
• Retry côté client : en cas de 429, respectez Retry-After. En cas de 500 ou timeout, utilisez un backoff exponentiel + Idempotency-Key pour éviter la duplication. Voir Authentification pour les détails.
• Fenêtre anti-replay du webhook : l'en-tête X-Owem-Timestamp est un Unix time en secondes. Le serveur ne rejette pas les webhooks anciens ; il appartient à votre endpoint d'écarter les livraisons avec |now - timestamp| > 300s (± 5 minutes) comme défense en profondeur contre le replay. Voir Webhooks -- Validation de la signature.

External ID

Champ optionnel external_id (max 128 caractères, alphanumérique + ._:-) accepté dans cash-in et cash-out. Retourné dans les réponses et webhooks. Permet la consultation par référence :

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

Consultez Concepts pour les détails.

Endpoints

PIX Cash Out (Envoi)

Méthode	Endpoint	Description
POST	/api/external/pix/cash-out	Envoyer un PIX par clé ou copier-coller

PIX Cash In (Encaissement)

Méthode	Endpoint	Description
POST	/api/external/pix/cash-in	Générer un QR Code pour encaissement

Consultations

Méthode	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 (préfixe)
GET	/api/external/transactions/ref/:external_id	Consulter par external_id
GET	/api/external/transactions/:id/receipt	Reçu

Compte

Méthode	Endpoint	Description
GET	/api/external/balance	Solde du compte
GET	/api/external/statement	Relevé

Clés PIX

Méthode	Endpoint	Description
GET	/api/external/pix/keys	Lister les clés PIX du compte

Remboursement

Méthode	Endpoint	Description
POST	/api/external/pix/refund	Remboursement PIX (total ou partiel)

MED

Méthode	Endpoint	Description
GET	/api/external/med	Lister les MED
GET	/api/external/med/:id	Détails d'un MED

Validation

Méthode	Endpoint	Description
POST	/api/external/cpf/validate	Valider un CPF

Webhooks

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