CentralPay File Import Service

The File Import Service allows you to manage CentralPay operations in bulk by uploading simple CSV files instead of calling the API line by line.

To date, two types of files are supported:

• Customer files: to create your customer profiles in CentralPay, optionally with a bank account (BankAccount) and/or a SEPA direct debit mandate (SDD).
• Operation files: to initiate SEPA direct debits (SDD) on your customer profiles and/or outgoing SEPA credit transfers (SCT) to your customer profiles’ bank accounts.

For each file uploaded, CentralPay sends you report files indicating, line by line, what was accepted, refused, or rejected.

1. Who is this service for?

This service is designed for merchants who process large volumes of operations and prefer file exchange over real-time API integration: recurring direct debit collections, grouped outgoing payments, creation or migration of a customer/SEPA mandate repository, etc.

The exchange occurs asynchronously: you upload your files, CentralPay processes them, then makes the reports available to you.

2. Prerequisites

2.1 Common Prerequisites

• An active CentralPay merchant account with access to the Merchant Portal.
• Your CentralPay merchant ID (UUID). The first 8 characters of this UUID are used to name your files (see section 5.1 Rules common to all files).
• The setup of a secure exchange channel (SFTP, see section 4. SFTP Setup) unless another channel has been agreed upon with your CentralPay contact.
• A testing phase with the CentralPay integration team before going live.

2.2 Prerequisites for outgoing SEPA credit transfer operations (CREDIT / SCT)

• The outgoing SEPA credit transfer service must be activated on your merchant profile.

2.3 Prerequisites for SEPA direct debit operations (DEBIT / SDD)

Direct debits require additional prerequisites, to be validated before any first submission:

• Your ICS (SEPA Creditor Identifier) must be declared in your CentralPay merchant profile (procedure carried out with your CentralPay contact).
• The SEPA direct debit service must be activated on your merchant profile (procedure carried out with your CentralPay contact).
• Validation of Mandate Management Mode Compliance. In this integration process, CentralPay does not collect the mandate signature: you transmit, in the Customer file, the mandate reference (MANDATE_RUM) and its signature date (MANDATE_SIGN_DATE). Consequently:
  • Your CentralPay contact must validate the principle upstream of mandate management via this method, whether it concerns the migration of existing mandates or newly collected mandates by you.
  • You remain responsible for the collection, legal validity, and retention of signed mandates, as well as for providing prior information to your customers (pre-notification, UMR, ICS).

Without these prerequisites, files containing direct debits cannot be processed, whether in the testing or production environment.

3. How does the processing cycle work?

1. Upload. You upload your CSV files (Customer and/or Operation) to the SFTP, in the upload folder.
2. Technical Control (ACK). CentralPay checks each line (format, mandatory fields, consistency) and sends you an .ACK file: each line is marked ACCEPTED or REFUSED, with the error reason if applicable.
3. Bank processing. Technically valid lines are transmitted to the SEPA banking circuits.
4. Settlement Report (SET). For operations, CentralPay produces .SET files indicating the settlement progress (ACCEPTED / PENDING / REFUSED) once bank feedback is available.
5. Post-settlement Rejections (RET). In case of a SEPA rejection occurring after settlement (e.g., a customer dispute), CentralPay produces an .RET file detailing the reason and the returned amount.

Customer files do not generate a bank report (.SET / .RET): only an .ACK is returned.

4. SFTP Setup

SFTP is the recommended exchange channel. It ensures secure upload and retrieval, and allows CentralPay to automatically retrieve and process your files.

4.1 Exchange Model

The SFTP is hosted by the merchant.

CentralPay connects to your SFTP, retrieves files from an outgoing folder, and deposits reports into an incoming folder.

4.2 Folder Convention

The exchange relies on two directories:

Directory	Direction	Content
Upload folder (named /OUT)	Merchant → CentralPay	Your Customer and Operation files to be processed
Return folder (named /IN)	CentralPay → Merchant	The .ACK, .SET, reports .RET

4.3 Setup Steps

1. Request activation from your CentralPay contact.
2. Exchange access credentials: authentication via SSH key.
   • Two spaces should be created: one SFTP dedicated to testing and one dedicated to production.
   • The SFTP information (host + login) must be provided to us by email.
   • For us to connect to your SFTP, a CentralPay public key (per environment) will be communicated to you.
   • Furthermore, it is recommended to whitelist CentralPay’s IP addresses (these will be communicated to you during your integration).
3. Use the directory structure defined previously (upload /OUT and return /IN folders).
4. Test in the testing environment with an example file, validate the correct reception of .ACK, then switch to production.

5. Prepare your files

5.1 Rules common to all files

• Format: CSV. The header row is mandatory in all files, both input and output.
• Naming:
  • Customer file: <8 premiers caractères de votre UUID marchand en minucules>_CUST_<référence libre>.csv
  • Operations file: <8 premiers caractères de votre UUID marchand en minucules>_OPER_<référence libre>.csv
  • The free reference is at your discretion (often a timestamp). The full name must not exceed 100 characters.
  • Examples: c494f877_CUST_20241025110500.csv · c494f877_OPER_20241025110500.csv
• Amounts: expressed in minor unit (euro cents) and always positive. The direction (debit/credit) is indicated by the OPERATION_TYPE column, not by the sign of the amount.
• Column Legend in the tables below:
  • Mandatory: the line is rejected if the value is missing.
  • Optional: can be left blank.
  • Conditional: required only in the described case.

5.2 File Customer

This file creates your customer profiles. Depending on your needs, it can create in a single line: the customer profile alone, the customer + a bank account, or the customer + a bank account + an SDD mandate.

Column	Format	Status	Description
MERCHANT_ID	UUID	Mandatory	Your CentralPay merchant ID
MERCHANT_CUSTOMER_ID	String(100)	Optional	Your internal customer reference (must be unique). Highly recommended for reconciling your operations.
DESCRIPTION	String(256)	Optional	Free field for your use
TYPE	INDIVIDUAL / LEGAL_ENTITY	Mandatory	Individual or legal entity
SOCIAL_REASON	String(35)	Conditional	Required if TYPE = LEGAL_ENTITY (company name)
FIRST_NAME	String(35)	Mandatory	First name (of the legal representative if LEGAL_ENTITY)
LAST_NAME	String(35)	Mandatory	Last name (of the legal representative if LEGAL_ENTITY)
EMAIL	String(255)	Optional
PHONE	String(25)	Optional	International format +<indicatif><numéro>
ADDRESS_LINE_1	String(255)	Mandatory
ADDRESS_LINE_2/3/4	String(255)	Optional	Address supplements
POSTAL_CODE	String(15)	Mandatory	Allowed characters: letters, numbers, space, hyphen
CITY	String(35)	Mandatory
COUNTRY	ISO 3166 alpha-3 code	Mandatory	Ex. FRA
IBAN	String(34)	Conditional	Required to create a bank account (thus for any future outgoing transfer or direct debit). Validated according to ISO 13616
BIC	String(11)	Conditional	Required with IBAN
MANDATE_RUM	String(35)	Conditional	Required to create an SDD mandate. Unique Mandate Reference (UMR) of the mandate already signed on the merchant side
MANDATE_SIGN_DATE	Date YYYY-MM-DD	Conditional	Required to create an SDD mandate. Mandate signature date

"With or Without" Logic

➜ Customer only: fill in identity and address, leave IBAN/BIC and mandate columns blank.

➜ Customer + bank account (necessary for a future outgoing transfer): add IBAN + BIC.

➜ Customer + SDD mandate (necessary for a future SEPA direct debit): add IBAN + BIC + MANDATE_RUM + MANDATE_SIGN_DATE.

Example file Customer

Three customers: one individual (INDIVIDUAL, without company name) and two legal entities (LEGAL_ENTITY), each with their own bank account and SDD mandate.

Key takeaways from this example:

• The phone number is in international format (+33..., without the initial 0).
• For customer INDIVIDUAL, the SOCIAL_REASON field is left empty (two consecutive ;); it is only filled in for LEGAL_ENTITY.
• Each customer has their own IBAN/BIC and their own MANDATE_RUM. The IBAN/BICs above are test credentials provided for the testing environment: replace them with your customers’ real credentials in production.

In return, the .ACK file will send you a CUSTOMER_ID (UUID) for each accepted line. Keep these identifiers: you will reuse them in your Operation files.

Columns added by CentralPay in the .ACK return file:

Column	Description
STATUS	ACCEPTED or REFUSED (no PENDING for customer files)
ERROR_CODE	Valued if REFUSED (e.g., INVALID_PARAMETERS)
ERROR_MESSAGE	Technical detail (in English)
CUSTOMER_ID	UUID of the created customer, valued if ACCEPTED (to be kept for your future operations)

5.3 File Operation

This file triggers operations on customer profiles already existing in CentralPay.

Column	Format	Status	Description
MERCHANT_ID	UUID	Mandatory	Your CentralPay merchant ID
POINT_OF_SALE_ID	UUID	Optional	Concerned point of sale. If empty, the default point of sale is used.
MERCHANT_TRANSACTION_ID	String(35)	Optional	Your operation reference (unique to you)
DESCRIPTION	String(140)	Optional	Description for your use
END_TO_END_ID	String(35)	Optional	SEPA end-to-end reference visible to the end customer. Otherwise, it uses MERCHANT_TRANSACTION_ID
REMITTANCE_INFO	String(140)	Optional	SEPA label (unstructured remittance information) visible to the end customer. Otherwise, it uses DESCRIPTION
CUSTOMER_ID	UUID	Conditional	CentralPay customer identifier. CUSTOMER_ID or MERCHANT_CUSTOMER_ID must be provided
MERCHANT_CUSTOMER_ID	String(100)	Conditional	Your internal customer reference (alternative to the CUSTOMER_ID generated by CentralPay)
MANDATE_RUM	String(35)	Optional	To target a specific mandate if the customer has several (if OPERATION_TYPE = DEBIT)
AMOUNT	Integer	Mandatory	Amount in euro cents, positive value only
CURRENCY	ISO Code	Mandatory	EUR (mandatory euro currency for SEPA transfers and direct debits)
OPERATION_TYPE	DEBIT / CREDIT	Mandatory	DEBIT = SEPA direct debit (SDD) CREDIT = outgoing SEPA credit transfer (payout)
EXPECTED_SETTLEMENT_DATE	Date YYYY-MM-DD	Optional	Desired settlement date. Default: J+1 business day

Choose the correct  OPERATION_TYPE

➜ DEBIT (direct debit): If you wish to debit your customer's bank account via a SEPA direct debit. Requires the customer profile to have a valid SDD mandate.  

➜ CREDIT (transfer): If you wish to credit your customer's bank account via an outgoing SEPA credit transfer. Requires the customer to have a declared bank account (IBAN/BIC). 

Example file Operation

Five operations on customers created in the previous step, referenced by their CUSTOMER_ID (the UUIDs returned in the .ACK of the Customer file): three direct debits (DEBIT) and two credit transfers (CREDIT).

Key takeaways from this example:

• The customer is identified by their CUSTOMER_ID (stable and unique UUID). It can also be identified by your MERCHANT_CUSTOMER_ID but you must ensure its uniqueness and correct formatting.
• MERCHANT_TRANSACTION_ID and END_TO_END_ID are unique for each operation.
• The amounts are in cents (4990 = €49.90) and always positive; OPERATION_TYPE indicates the direction (debit or credit).
• REMITTANCE_INFO carries an explicit label, visible to the end customer on their statement. Prioritize simple characters (SEPA standard: no accents or special characters).

Columns added by CentralPay in the return files:

In the .ACK (technical control):

Column	Description
STATUS	ACCEPTEDPENDING, or REFUSED
ERROR_CODE	Valued if REFUSED
ERROR_MESSAGE	Technical detail
OPERATION_ID	Operation UUID, valued if ACCEPTED (tracking key in subsequent files)

In the .SET (settlement report):

Column	Description
STATUS	ACCEPTEDPENDING, or REFUSED
ERROR_CODE	Valued if REFUSED (e.g., FRAUD_ALERT)
ERROR_MESSAGE	Bank refusal detail
SETTLEMENT_DATE	Value date if ACCEPTED
OPERATION_ID	Operation UUID

In the .RET (post-settlement rejection):

Column	Description
REASON_CODE	SEPA rejection code (e.g., AC04 = account closed)
REASON_MESSAGE	Textual detail of the rejection
RETURN_AMOUNT	Returned amount (positive)
RETURN_DATE	Rejection date
OPERATION_ID	Original operation UUID

6. Understanding the return files

6.1 Naming of return files

Return files use the name of your original file, followed by the report type, a processing fingerprint, and a timestamp:

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

• <hash> : fingerprint of the processed file (allows linking the return to the processing).
• <timestamp> : processing timestamp.

Example:

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

6.2 The three levels of reporting

File	When	What it tells you
.ACK	Immediately upon receipt	Technical validity line by line. All lines are returned, including those refused.
.SET	Once bank feedback is available (operations only)	Progress of settlement. Only lines ACCEPTED at the .ACK level are included.
.RET	In case of rejection after settlement (operations only)	Subsequent SEPA rejections (e.g., customer dispute)

Indicative settlement times (business days): credit transfer (SCT) 1 to 2 days; SEPA direct debit (SDD) 3 to 5 days. A post-settlement rejection (.RET) can occur up to 8 weeks after the operation in case of dispute. 

6.3 Best practices for reconciliation

• OPERATION_ID is the matching key between the .ACK, .SET, and .RET files of the same operation. Keep it.
• CUSTOMER_ID (returned in the customer .ACK) is the identifier to reuse in your Operation files.
• Systematically provide your own references (MERCHANT_CUSTOMER_ID, MERCHANT_TRANSACTION_ID) to facilitate reconciliation on your end.

7. Common errors

7.1 Technical rejections (.ACK file)

Code	Meaning	Action
MISSING_COLUMNS	Expected column(s) missing	Check the CSV header and structure
INVALID_PARAMETERS	Invalid field value	Correct the erroneous data (format, length, enumeration)
BAD_ROW	Malformed line	Check the separator and the number of columns in the line
COMPUTATION_EXCEPTION	Internal processing error	Contact CentralPay support

(Non-exhaustive list. Messages are returned line by line and may concatenate multiple errors.)

7.2 Customer reconciliation anomalies

Message	Meaning	Action
No customer fetch error	The customer linked to the operation is not found	Check the consistency of CUSTOMER_ID / MERCHANT_CUSTOMER_ID. If necessary, upload a Customer file for missing customers.
Too much customer found for merchant	Multiple customers share the same MERCHANT_CUSTOMER_ID	Ensure the uniqueness of your customer reference; contact us to arbitrate (merge / update).
Unexpected service response	CentralPay internal error	Contact CentralPay support

8. Points of attention

• The header row is mandatory in each file.
• The amounts are in cents and always positive.
• An operation may appear in several successive .SET if its status changes (PENDING → ACCEPTED/REFUSED).
• Maintain the OPERATION_ID / CUSTOMER_ID mapping between your systems and CentralPay.
• Any initial setup is subject to a testing phase with the integration team before production.

9. Getting Started

1. Check your prerequisites, especially the ICS chain + SDD service + Compliance validation if you plan direct debits.
2. Request SFTP channel activation from your CentralPay contact.
3. Prepare an example file and validate it in the testing environment.
4. Go live.

For any questions regarding setup, contact your CentralPay representative or support.