Concepts

Concepts fondamentaux pour integrer l'API Owem Pay.

Architecture de Securite

L'API utilise trois couches de protection independantes. Toutes sont obligatoires.

Couche 1 -- API Key + Secret

Chaque integrateur recoit une paire d'identifiants (client_id et client_secret). Le secret n'est jamais stocke en clair -- nous conservons uniquement le hash. Lorsqu'une requete arrive, le secret envoye est compare au hash stocke. S'il ne correspond pas, la requete est rejetee immediatement, avant d'atteindre la logique metier.

Couche 2 -- Signature HMAC-SHA512 par Requete

En plus de l'API Key, chaque requete transactionnelle (POST) doit envoyer une signature HMAC-SHA512 dans l'en-tete hmac.

Le processus fonctionne ainsi :

1. L'integrateur serialise le body de la requete en JSON
2. Genere le hash HMAC-SHA512 en utilisant le client_secret comme cle
3. Envoie le hash en hexadecimal dans l'en-tete hmac

De notre cote, nous recalculons le hash avec la meme methode et le comparons a la valeur recue. Si un seul octet du contenu est modifie en transit (par exemple, lors d'une attaque man-in-the-middle), la signature ne correspondra pas et la requete sera rejetee avec une erreur 401. Cette comparaison est effectuee en temps constant (constant-time comparison), ce qui empeche les attaques par timing qui tentent de decouvrir la signature octet par octet.

Couche 3 -- Liste Blanche d'IP Obligatoire

Chaque API Key ne peut etre utilisee qu'a partir d'IPs prealablement autorisees. Meme si quelqu'un a acces aux identifiants, il ne pourra pas utiliser l'API depuis un autre IP. Les requetes provenant d'IPs non autorisees recoivent 403 Forbidden.

Protections Supplementaires

Protection	Description
Rate Limiting	60 000 requetes/minute par IP. Endpoints non authentifies : 5 req/min
Cloud Armor (WAF)	Pare-feu applicatif protegeant le cluster GKE
HTTPS obligatoire	TLS 1.2 ou superieur sur toutes les connexions
HSTS	HTTP Strict Transport Security active

Details complets : Authentification | HMAC-SHA512

Pourquoi HMAC et non mTLS ?

Le mTLS (mutual TLS) ajoute une authentification via certificat X.509 au niveau de la connexion. C'est une couche valide, mais dans notre contexte le HMAC par requete offre une protection equivalente ou plus adaptee :

Aspect	mTLS	HMAC-SHA512
Ce qu'il valide	La connexion (canal TLS)	Chaque requete individuellement
Integrite du payload	Non -- si la connexion est fiable, les requetes passent	Oui -- toute modification du body rejette la requete
Gestion operationnelle	Complexe : emission, rotation, revocation, CRL/OCSP	Simple : genere une nouvelle paire, met a jour, invalide la precedente
Incidents courants	Certificats expires ou mal geres	Rares -- la cle est une chaine de caracteres, sans cycle de vie complexe

Le TLS garantit deja le chiffrement du transport. Le HMAC intervient comme couche supplementaire, garantissant l'integrite et l'authenticite du payload -- ce que le mTLS seul ne couvre pas.

Valeurs Monetaires

L'API Owem Pay utilise deux unites differentes selon la direction :

Direction	Unite	Echelle	Exemple R$ 30,00
Requete envoyee (request body)	centavos	BRL x 100	3000
Reponse recue (response body)	unites de base	BRL x 10 000	300000

Conversion rapide

• Pour envoyer : multipliez la valeur en 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

Table de reference

Valeur BRL	Request (centavos)	Response (unites de base)
R$ 1,00	100	10000
R$ 30,00	3000	300000
R$ 150,50	15050	1505000
R$ 1 000,00	100000	10000000

Attention

La valeur 3000 dans la requete (R$ 30,00) devient 300000 dans la reponse. C'est la meme valeur en BRL, representee dans des unites differentes. Si vous divisez la reponse par 100 au lieu de 10 000, vous obtiendrez R$ 3 000,00 au lieu de R$ 30,00.

External ID

Le champ external_id est un identifiant optionnel que vous definissez dans votre systeme pour suivre les transactions. Il est accepte dans les endpoints de cash-in et cash-out et retourne dans toutes les reponses et webhooks associes.

Attribut	Valeur
Obligatoire	Non
Taille maximale	128 caracteres
Caracteres autorises	Alphanumeriques, ., _, :, -
Regex	^[a-zA-Z0-9._:\-]+$
Exemple	"order-9876", "invoice-4521", "ref:2026-03-07:001"

En plus d'etre retourne dans les reponses, vous pouvez consulter une transaction par external_id :

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

Suivi

Utilisez external_id pour correler les transactions Owem Pay avec les commandes, factures ou enregistrements de votre systeme. Les valeurs dupliquees ne sont pas rejetees, mais nous recommandons l'unicite pour faciliter le rapprochement.

Idempotence

Les requetes d'ecriture (POST) acceptent l'en-tete Idempotency-Key pour eviter le traitement en double. Si la meme cle est envoyee dans une seconde requete identique dans les 24 heures, l'API retourne la reponse originale mise en cache au lieu de traiter a nouveau.

Idempotency-Key: unique-request-id-123

Attribut	Valeur
En-tete	Idempotency-Key
Taille maximale	256 caracteres
TTL du cache	24 heures
S'applique a	Uniquement POST (cash-in, cash-out, refund, webhooks, CPF)
Reponse rejouee	En-tete X-Idempotent-Replay: true

Important

La cle d'idempotence considere methode + chemin + cle. Deux requetes vers des endpoints differents avec la meme cle sont traitees comme des operations distinctes.

Statuts de Transaction

Cash In (Encaissements)

Statut	Description
active	QR Code genere, en attente de paiement
pending	Paiement detecte, en cours de traitement
completed	Paiement confirme et credite sur le compte
failed	Paiement echoue
cancelled	QR Code expire (24h) ou annule

Cash Out (Envois)

Statut	Description
pending_approval	En attente d'approbation (flux creer + approuver)
processing	Envoye au SPI, en attente de liquidation
completed	Liquide avec succes
failed	Rejete par le SPI ou erreur de traitement
refunded	Rembourse (totalement ou partiellement)

End-to-End ID (E2E ID)

Identifiant unique d'une transaction PIX dans l'ecosysteme de la Banque Centrale. Format standard :

E{ISPB}{YYYYMMDDHHMM}{sequentiel}

Exemple : E37839059202603071530000001

Composant	Valeur	Description
E	Prefixe fixe	Identifie comme E2E ID
37839059	ISPB d'Owem Pay	8 chiffres
202603071530	Date et heure UTC	AAAAMMJJHHMM (12 chiffres)
000001	Sequentiel	6 chiffres

L'E2E ID est genere automatiquement par Owem Pay et retourne dans la reponse de chaque operation PIX. Utilisez-le pour suivre les transactions entre institutions.

Types de Cle PIX

Type	Format	Exemple	Limite PF	Limite PJ
cpf	11 chiffres	12345678901	1	--
cnpj	14 chiffres	12345678000190	--	1
email	E-mail valide	contato@empresa.com.br	5	20
phone	+55 + indicatif + numero	+5511999998888	5	20
evp	UUID v4 (cle aleatoire)	a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d	5	20

Schema de Reponse

Toutes les reponses de l'API suivent le schema :

Succes

{
  "worked": true,
  ...
}

Erreur

{
  "worked": false,
  "detail": "Description de l'erreur"
}

Le champ worked indique si l'operation a reussi (true) ou echoue (false). En cas d'erreur, le champ detail decrit le motif.