Glossaire

Définitions des identifiants et références utilisés dans les contrats d'intégration Epayment.

Identifiants de session et de paiement

Terme	Format	Portée	Description
order_id	Chaîne (1-128 car.)	Application	Identifiant métier du dossier ou de la commande côté intégrateur. Unique par application active. Sert à l'idempotence métier et à la corrélation webhook.
session_id	chs_…	Session checkout	Identifiant technique de la session de paiement. Présent dans les URL checkout (/c/{session_id}, /embed/{session_id}) et les réponses API.
client_secret	chs_secret_…	Session embed	Jeton d'accès à la session en mode embarqué. Combiné avec session_id pour le SDK ({session_id}:{client_secret}). Expire avec la session. Ne pas journaliser ni exposer hors du navigateur.
completion_token	cpt_…	Usage unique	Jeton émis à la fin d'un paiement embed. TTL court (~10 min), consommé par POST /checkout/sessions/verify-completion. Permet la confirmation synchrone côté ministry sans attendre le webhook.
payment_ref	16 chiffres	Notice / session	Référence citoyen pour paiement en agence. Communiquée au guichetier connecté. Distincte de order_id (métier) et de notice_id (interne).
offer_id	string	Checkout citoyen	Identifiant d'offre de paiement (momo, airtel, paddle, cash_agency). Le SI ministry ne le choisit pas et n'appelle pas de route de collecte : le citoyen sélectionne l'offre sur le checkout.
currency	ISO 4217 (3 car.)	Session	Défaut XAF (MM et agence). Devises carte (USD, EUR, …) pour l'offre paddle. Voir Référence API.
amount	entier (unités mineures)	Session	Plus petite unité de la devise : XAF sans décimale (5000 = 5 000 FCFA) ; EUR en centimes (10000 = 100,00 EUR).
notice_id	UUID	Notice Epayment	Identifiant interne de l'avis de paiement. Présent dans les webhooks checkout.completed pour corrélation côté plateforme.

Identifiants ERP et portail citoyen

Terme	Format	Portée	Description
subject_ref	Chaîne (ERP)	Contribuable	Clé stable du contribuable ou du redevable dans le SI régie. Paramètre de GET /dues?subject_ref= lors du tirage des créances pour le portail citoyen.
erp_due_ref	Chaîne (ERP)	Créance	Identifiant d'une créance dans l'ERP. Retourné par GET /dues, repris dans POST /payment-confirmations pour imputation côté régie.
batch_ref	Chaîne (ERP)	Lot disbursement	Référence d'un lot de paiements en masse. Paramètre de GET /disbursements?batch_ref= pour charger les lignes bénéficiaires avant exécution.

Identifiants de configuration

Terme	Format	Portée	Description
tenant_id	UUID ou slug	Régie	Identifiant de la régie (locataire). Obligatoire avec une clé API plateforme (sk_ scope platform). Filtre les applications et les webhooks cibles.
application_id	UUID	Application	Identifiant de l'application intégrateur. Présent dans les webhooks pour corrélation. Une régie peut avoir plusieurs applications (ex. portail casiers, API batch).
service_code	Chaîne (snake_case)	Catalogue régie	Code du service de recette dans le catalogue Epayment (ex. casier_judiciaire). Optionnel à la création de session ; permet le mapping vers les lignes de recette et l'affichage citoyen.

Relations entre identifiants

Un order_id peut générer plusieurs session_id successives (retry après échec ou expiration), chacune avec son propre client_secret et payment_ref. La confirmation métier reste idempotente sur order_id.