Concepts

Concepts fondamentaux pour l'integration avec l'API Owem Pay.

Modele d'Authentification

L'API utilise une authentification a deux niveaux :

Composant	Description	Utilisation
Bearer Token	JWT genere via /api/v2/external/auth-token	En-tete Authorization: Bearer {token} dans toutes les requetes
HMAC-SHA512	Signature du body de la requete	En-tete hmac dans les requetes transactionnelles (POST)

Flux d'Authentification

1. Envoyez client_id et client_secret a l'endpoint auth-token
2. Recevez le access_token (valide pendant 60 minutes)
3. Incluez le token dans toutes les requetes : Authorization: Bearer {access_token}
4. Pour les requetes POST, calculez le HMAC-SHA512 du body et envoyez-le dans l'en-tete hmac

Details complets : Authentification | HMAC-SHA512

Valeurs Monetaires

Toutes les valeurs sont representees comme des entiers en centimes. N'utilisez jamais de virgule flottante.

Valeur	Representation	Champ JSON
R$ 1,00	100	"amount": 100
R$ 150,50	15050	"amount": 15050
R$ 1.000,00	100000	"amount": 100000
R$ 10.000,00	1000000	"amount": 1000000

Conversion

Pour convertir des centimes en reais : divisez par 100. Pour convertir des reais en centimes : multipliez par 100 et arrondissez.

Statuts de Transaction

Statut	Description
pending	En attente de paiement ou d'approbation
processing	Transaction en cours de traitement dans le SPI
completed	Transaction terminee avec succes
settled	Liquidation confirmee par le BACEN
failed	Transaction echouee
refunded	Transaction remboursee (totalement ou partiellement)
cancelled	Transaction annulee ou expiree

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	contact@entreprise.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.