Service d’import de fichiers CentralPay

Le Service d’import de fichiers vous permet de piloter des opérations CentralPay en masse, en déposant de simples fichiers CSV plutôt qu’en appelant l’API ligne à ligne.

À ce jour, deux types de fichiers sont pris en charge :

• Fichiers Customer : pour créer vos profils clients (customers) dans CentralPay, avec en option un compte bancaire (BankAccount) et/ou un mandat de prélèvement SEPA (SDD).
• Fichiers Operation : pour déclencher des prélèvements SEPA (SDD) sur vos profils clients et/ou des virements SEPA sortants (SCT) vers les comptes bancaires de vos profils clients.

Pour chaque fichier déposé, CentralPay vous renvoie des fichiers de compte-rendu vous indiquant, ligne par ligne, ce qui a été accepté, refusé ou rejeté.

1. À qui s’adresse ce service ?

Ce service est conçu pour les marchands qui traitent des volumes d’opérations et préfèrent un échange par fichiers à une intégration API en temps réel : encaissements récurrents par prélèvement, versements sortants groupés, constitution ou migration d’un référentiel clients/mandats SEPA, etc.

L’échange s’effectue de façon asynchrone : vous déposez vos fichiers, CentralPay les traite, puis met à votre disposition les comptes-rendus.

2. Prérequis

2.1 Prérequis communs

• Un compte marchand CentralPay actif avec accès au Portail Marchand.
• Votre identifiant marchand (UUID) CentralPay. Les 8 premiers caractères de cet UUID servent à nommer vos fichiers (voir section 5.1 Règles communes à tous les fichiers).
• La mise en place d’un canal d’échange sécurisé (SFTP, voir section 4. Mise en place du SFTP) sauf si un autre canal a été convenu avec votre interlocuteur CentralPay.
• Une phase de recette avec l’équipe intégration CentralPay avant la mise en production.

2.2 Prérequis pour les opérations de virements SEPA sortants (CREDIT / SCT)

• Le service de virement SEPA sortant doit être activé sur votre profil marchand.

2.3 Prérequis pour les opérations prélèvements SEPA (DEBIT / SDD)

Les prélèvements imposent des prérequis supplémentaires, à valider avant tout premier dépôt :

• Votre ICS (Identifiant Créancier SEPA) doit être déclaré dans votre profil marchand CentralPay (démarche réalisée avec votre interlocuteur CentralPay).
• Le service de prélèvement SEPA doit être activé sur votre profil marchand (démarche réalisée avec votre interlocuteur CentralPay).
• Validation de la Conformité du mode de gestion des mandats. Dans ce parcours d’intégration, CentralPay ne recueille pas la signature du mandat : vous transmettez vous-même, dans le fichier Customer, la référence du mandat (MANDATE_RUM) et sa date de signature (MANDATE_SIGN_DATE). En conséquence :
  • Votre interlocuteur CentralPay doit valider en amont le principe de gestion des mandats par ce biais, qu’il s’agisse d’une migration de mandats existants ou de mandats nouvellement collectés par vos soins.
  • Vous restez responsable de la collecte, de la validité juridique et de la conservation des mandats signés, ainsi que de l’information préalable de vos clients (préavis, RUM, ICS).

Sans ces prérequis, les fichiers comportant des prélèvements ne pourront pas être traités, que ce soit en environnement de RCT ou de PROD.

3. Comment fonctionne le cycle de traitement ?

1. Dépôt. Vous déposez vos fichiers CSV (Customer et/ou Operation) sur le SFTP, dans le dossier de dépôt.
2. Contrôle technique (ACK). CentralPay vérifie chaque ligne (format, champs obligatoires, cohérence) et vous renvoie un fichier .ACK : chaque ligne y est marquée ACCEPTED ou REFUSED, avec le motif d’erreur le cas échéant.
3. Traitement bancaire. Les lignes techniquement valides sont transmises aux circuits bancaires SEPA.
4. Compte-rendu de règlement (SET). Pour les opérations, CentralPay produit des fichiers .SET indiquant l’avancement du règlement (ACCEPTED / PENDING / REFUSED) une fois les retours bancaires disponibles.
5. Rejets post-règlement (RET). En cas de rejet SEPA survenant après le règlement (par exemple une contestation client), CentralPay produit un fichier .RET reprenant le motif et le montant retournés.

Les fichiers Customer ne génèrent pas de compte-rendu bancaire (.SET / .RET) : seul un .ACK est renvoyé.

4. Mise en place du SFTP

Le SFTP est le canal d’échange recommandé. Il garantit un dépôt et une récupération sécurisés, et permet à CentralPay de récupérer et traiter automatiquement vos fichiers.

4.1 Modèle d’échange

Le SFTP est hébergé par le marchand.

CentralPay se connecte à votre SFTP, récupère les fichiers dans un dossier de sortie et y dépose les comptes-rendus dans un dossier d’entrée.

4.2 Convention de dossiers

L’échange repose sur deux répertoires :

Répertoire	Sens	Contenu
Dossier de dépôt (nommé /OUT)	Marchand → CentralPay	Vos fichiers Customer et Operation à traiter
Dossier de retour (nommé /IN)	CentralPay → Marchand	Les comptes-rendus .ACK, .SET, .RET

4.3 Étapes de mise en place

1. Demander l’activation auprès de votre interlocuteur CentralPay.
2. Échanger les accès : authentification par clé SSH.
   • Il convient de créer deux espaces : un SFTP dédié à la recette et un dédié à la production
   • Les informations du SFTP (hote + login) devront nous être fournies par email
   • Afin que nous puissions nous connecter à votre SFTP, une clé publique Centralpay (par environnement) vous sera communiquée
   • Par ailleurs, il est recommandé de mettre en liste blanche (whitelist) les adresses IP de CentralPay (celles-ci vous seront communiquées lors de votre intégration).
3. Utilisation de l’arborescence définie précédemment (dossiers de dépôt /OUT et de retour /IN).
4. Tester en recette avec un fichier d’exemple, valider la bonne réception des .ACK, puis basculer en production.

5. Préparer vos fichiers

5.1 Règles communes à tous les fichiers

• Format : CSV. La ligne d’en-tête (header) est obligatoire dans tous les fichiers, en entrée comme en sortie.
• Nommage :
  • Fichier client : <8 premiers caractères de votre UUID marchand en minucules>_CUST_<référence libre>.csv
  • Fichier opérations : <8 premiers caractères de votre UUID marchand en minucules>_OPER_<référence libre>.csv
  • La référence libre est à votre main (souvent un horodatage). Le nom complet ne doit pas dépasser 100 caractères.
  • Exemples : c494f877_CUST_20241025110500.csv · c494f877_OPER_20241025110500.csv
• Montants : exprimés en unité mineure (centimes d’euro) et toujours positifs. Le sens (débit/crédit) est porté par la colonne OPERATION_TYPE, pas par le signe du montant.
• Légende des colonnes dans les tableaux ci-dessous :
  • Obligatoire : la ligne est refusée si la valeur est absente.
  • Facultatif : peut être laissé vide.
  • Conditionnel : requis uniquement dans le cas décrit.

5.2 Fichier Customer

Ce fichier crée vos profils clients. Selon votre besoin, il peut créer en une seule ligne : le profil client seul, le client + un compte bancaire, ou le client + un compte bancaire + un mandat SDD.

Colonne	Format	Statut	Description
MERCHANT_ID	UUID	Obligatoire	Votre identifiant marchand CentralPay
MERCHANT_CUSTOMER_ID	String(100)	Facultatif	Votre référence client interne (doit être unique). Fortement recommandé pour réconcilier vos opérations
DESCRIPTION	String(256)	Facultatif	Champ libre à votre usage
TYPE	INDIVIDUAL / LEGAL_ENTITY	Obligatoire	Personne physique ou morale
SOCIAL_REASON	String(35)	Conditionnel	Requis si TYPE = LEGAL_ENTITY (raison sociale)
FIRST_NAME	String(35)	Obligatoire	Prénom (du représentant légal si LEGAL_ENTITY)
LAST_NAME	String(35)	Obligatoire	Nom (du représentant légal si LEGAL_ENTITY)
EMAIL	String(255)	Facultatif
PHONE	String(25)	Facultatif	Format international +<indicatif><numéro>
ADDRESS_LINE_1	String(255)	Obligatoire
ADDRESS_LINE_2/3/4	String(255)	Facultatif	Compléments d’adresse
POSTAL_CODE	String(15)	Obligatoire	Caractères autorisés : lettres, chiffres, espace, tiret
CITY	String(35)	Obligatoire
COUNTRY	Code ISO 3166 alpha-3	Obligatoire	Ex. FRA
IBAN	String(34)	Conditionnel	Requis pour créer un compte bancaire (donc pour tout virement sortant ou prélèvement futur). Validé selon ISO 13616
BIC	String(11)	Conditionnel	Requis avec l’IBAN
MANDATE_RUM	String(35)	Conditionnel	Requis pour créer un mandat SDD. Référence unique de mandat (RUM) du mandat déjà signé côté marchand
MANDATE_SIGN_DATE	Date YYYY-MM-DD	Conditionnel	Requis pour créer un mandat SDD. Date de signature du mandat

Logique « avec ou sans »

➜ Client seul : renseignez l'identité et l'adresse, laissez IBAN/BIC et les colonnes mandat vides.

➜ Client + compte bancaire (nécessaire pour un virement sortant futur) : ajoutez IBAN + BIC.

➜ Client + mandat SDD (nécessaire pour un prélèvement SEPA futur) : ajoutez IBAN + BIC + MANDATE_RUM + MANDATE_SIGN_DATE.

Exemple de fichier Customer

Trois clients : un particulier (INDIVIDUAL, sans raison sociale) et deux personnes morales (LEGAL_ENTITY), chacun avec son propre compte bancaire et son mandat SDD.

À retenir sur cet exemple :

• Le téléphone est au format international (+33..., sans le 0 initial).
• Pour le client INDIVIDUAL, le champ SOCIAL_REASON est laissé vide (deux ; consécutifs) ; il est renseigné uniquement pour les LEGAL_ENTITY.
• Chaque client a son propre IBAN/BIC et sa propre MANDATE_RUM. Les IBAN/BIC ci-dessus sont des coordonnées de test fournies pour la recette : remplacez-les par les coordonnées réelles de vos clients en production.

En retour, le fichier .ACK vous renverra pour chaque ligne acceptée un CUSTOMER_ID (UUID). Conservez ces identifiants : ce sont eux que vous réutiliserez dans vos fichiers Operation.

Colonnes ajoutées par CentralPay dans le fichier .ACK de retour :

Colonne	Description
STATUS	ACCEPTED ou REFUSED (pas de PENDING pour les fichiers customer)
ERROR_CODE	Valorisé si REFUSED (ex. INVALID_PARAMETERS)
ERROR_MESSAGE	Détail technique (en anglais)
CUSTOMER_ID	UUID du client créé, valorisé si ACCEPTED (à conserver pour vos opérations futures)

5.3 Fichier Operation

Ce fichier déclenche des opérations sur des profils clients déjà existants dans CentralPay.

Colonne	Format	Statut	Description
MERCHANT_ID	UUID	Obligatoire	Votre identifiant marchand CentralPay
POINT_OF_SALE_ID	UUID	Facultatif	Point de vente concerné. Si vide, le point de vente par défaut est utilisé
MERCHANT_TRANSACTION_ID	String(35)	Facultatif	Votre référence d’opération (unique chez vous)
DESCRIPTION	String(140)	Facultatif	Description à votre usage
END_TO_END_ID	String(35)	Facultatif	Référence SEPA end-to-end visible par le client final. À défaut, reprend MERCHANT_TRANSACTION_ID
REMITTANCE_INFO	String(140)	Facultatif	Libellé SEPA (unstructured remittance information) visible par le client final. À défaut, reprend DESCRIPTION
CUSTOMER_ID	UUID	Conditionnel	Identifiant CentralPay du client. CUSTOMER_ID ou MERCHANT_CUSTOMER_ID doit être renseigné
MERCHANT_CUSTOMER_ID	String(100)	Conditionnel	Votre référence client interne (alternative au CUSTOMER_ID généré par CentralPay)
MANDATE_RUM	String(35)	Facultatif	Pour cibler un mandat précis si le client en possède plusieurs (si OPERATION_TYPE = DEBIT)
AMOUNT	Entier	Obligatoire	Montant en centimes d’euro, valeur positive uniquement
CURRENCY	Code ISO	Obligatoire	EUR (devise euros obligatoire pour virements et prélèvements SEPA)
OPERATION_TYPE	DEBIT / CREDIT	Obligatoire	DEBIT = prélèvement SEPA (SDD) CREDIT = virement SEPA sortant (payout)
EXPECTED_SETTLEMENT_DATE	Date YYYY-MM-DD	Facultatif	Date de règlement souhaitée. Par défaut : J+1 ouvré

Choisir le bon OPERATION_TYPE

➜ DEBIT (prélèvement) : Si vous souhaitez débiter le compte bancaire de votre client via un prélèvement SEPA. Nécessite que le profil client dispose d'un mandat SDD valide. 

➜ CREDIT (virement) : Si vous souhaitez créditer le compte bancaire de votre client via un virement SEPA sortant. Nécessite que le client dispose d'un compte bancaire déclaré (IBAN/BIC).

Exemple de fichier Operation

Cinq opérations sur les clients créés à l’étape précédente, référencés par leur CUSTOMER_ID (les UUID renvoyés dans le .ACK du fichier Customer) : trois prélèvements (DEBIT) et deux virements (CREDIT).

À retenir sur cet exemple :

• Le client est désigné par son CUSTOMER_ID (UUID stable et unique). Il peut sinon être désigné par votre MERCHANT_CUSTOMER_ID mais vous devez vous assurer de son unicité et de son bon formatage.
• MERCHANT_TRANSACTION_ID et END_TO_END_ID sont uniques pour chaque opération.
• Les montants sont en centimes (4990 = 49,90 €) et toujours positifs ; c’est OPERATION_TYPE qui donne le sens (débit ou crédit).
• REMITTANCE_INFO porte un libellé explicite, visible du client final sur son relevé. Privilégiez des caractères simples (norme SEPA : pas d’accents ni de caractères spéciaux).

Colonnes ajoutées par CentralPay dans les fichiers de retour :

Dans le .ACK (contrôle technique) :

Colonne	Description
STATUS	ACCEPTED, PENDING ou REFUSED
ERROR_CODE	Valorisé si REFUSED
ERROR_MESSAGE	Détail technique
OPERATION_ID	UUID de l’opération, valorisé si ACCEPTED (clé de suivi dans les fichiers suivants)

Dans le .SET (compte-rendu de règlement) :

Colonne	Description
STATUS	ACCEPTED, PENDING ou REFUSED
ERROR_CODE	Valorisé si REFUSED (ex. FRAUD_ALERT)
ERROR_MESSAGE	Détail bancaire du refus
SETTLEMENT_DATE	Date de valeur si ACCEPTED
OPERATION_ID	UUID de l’opération

Dans le .RET (rejet post-règlement) :

Colonne	Description
REASON_CODE	Code de rejet SEPA (ex. AC04 = compte clos)
REASON_MESSAGE	Détail textuel du rejet
RETURN_AMOUNT	Montant retourné (positif)
RETURN_DATE	Date du rejet
OPERATION_ID	UUID de l’opération d’origine

6. Comprendre les fichiers de retour

6.1 Nommage des fichiers de retour

Les fichiers de retour reprennent le nom de votre fichier d’origine, suivi du type de compte-rendu, d’une empreinte de traitement et d’un horodatage :

<nom du fichier d'origine au format csv>.<ACK|SET|RET>-<hash>-<timestamp>.csv

• <hash> : empreinte du fichier traité (permet de relier le retour au traitement).
• <timestamp> : horodatage du traitement.

Exemple :

C494F877_OPER_20241025110500.csv.ACK-098f6bcd4621d373cade4e832627b4f6-20241025112500.csv

6.2 Les trois niveaux de compte-rendu

Fichier	Quand	Ce qu’il vous dit
.ACK	Immédiatement après réception	Validité technique ligne à ligne. Toutes les lignes sont retournées, y compris celles refusées
.SET	Une fois les retours bancaires disponibles (opérations uniquement)	Avancement du règlement. Seules les lignes ACCEPTED au niveau .ACK y figurent
.RET	En cas de rejet après règlement (opérations uniquement)	Rejets SEPA postérieurs (ex. contestation client)

Délais indicatifs de règlement (jours ouvrés) : virement (SCT) 1 à 2 jours ; prélèvement SEPA (SDD) 3 à 5 jours. Un rejet post-règlement (.RET) peut survenir jusqu'à 8 semaines après l'opération en cas de contestation.

6.3 Bonnes pratiques de réconciliation

• OPERATION_ID est la clé de correspondance entre les fichiers .ACK, .SET et .RET d’une même opération. Conservez-le.
• CUSTOMER_ID (renvoyé dans le .ACK customer) est l’identifiant à réutiliser dans vos fichiers Operation.
• Renseignez systématiquement vos propres références (MERCHANT_CUSTOMER_ID, MERCHANT_TRANSACTION_ID) pour faciliter le rapprochement de votre côté.

7. Erreurs fréquentes

7.1 Refus techniques (fichier .ACK)

Code	Signification	Action
MISSING_COLUMNS	Colonne(s) attendue(s) absente(s)	Vérifier l’en-tête et la structure du CSV
INVALID_PARAMETERS	Valeur de champ invalide	Corriger la donnée fautive (format, longueur, énumération)
BAD_ROW	Ligne mal formée	Vérifier le séparateur et le nombre de colonnes de la ligne
COMPUTATION_EXCEPTION	Erreur de traitement interne	Contacter le support CentralPay

(Liste non exhaustive. Les messages sont retournés ligne par ligne et peuvent concatener plusieurs erreurs.)

7.2 Anomalies de rapprochement client

Message	Signification	Action
No customer fetch error	Le client lié à l’opération est introuvable	Vérifier la cohérence du CUSTOMER_ID / MERCHANT_CUSTOMER_ID. Au besoin, déposer un fichier Customer pour les clients manquants
Too much customer found for merchant	Plusieurs clients partagent le même MERCHANT_CUSTOMER_ID	Garantir l’unicité de votre référence client ; nous contacter pour arbitrer (fusion / mise à jour)
Unexpected service response	Erreur interne CentralPay	Contacter le support CentralPay

8. Points d’attention

• La ligne d’en-tête est obligatoire dans chaque fichier.
• Les montants sont en centimes et toujours positifs.
• Une opération peut apparaître dans plusieurs .SET successifs si son statut évolue (PENDING → ACCEPTED/REFUSED).
• Conservez le mapping OPERATION_ID / CUSTOMER_ID entre vos systèmes et CentralPay.
• Toute première mise en place fait l’objet d’une recette avec l’équipe intégration avant production.

9. Démarrer

1. Vérifiez vos prérequis, en particulier la chaîne ICS + service SDD + validation Conformité si vous prévoyez des prélèvements.
2. Demandez l’ouverture du canal SFTP auprès de votre interlocuteur CentralPay.
3. Préparez un fichier d’exemple et validez-le en recette.
4. Passez en production.

Pour toute question sur la mise en place, contactez votre interlocuteur CentralPay ou le support.