How to prepare, transmit, and process a file of purchase, preauthorization, preauthorization completion, and refund transactions through PayFacto's batch payment system — via FTP or the on-line interface.
Contents
Batch payment allows a merchant to prepare a file containing a list of transactions that will subsequently be processed by PayFacto's solution. The files may be submitted manually via PayFacto Solution's on-line interface, or more automatically via FTP. The files are processed daily.
The batch payment system, as included in PayFacto's solution, allows a merchant to perform purchase and preauthorization transactions, as well as to close preauthorization. These transactions are sent as part of a file to PayFacto's solution, which processes them on a daily basis.
The FTP transmission process is as follows. The merchant must first create a transaction file and upload it to an FTP server. At the set processing time, the payment solution connects to the merchant's FTP server and downloads the transaction files. The downloaded files are then checked for consistency. In case of error, a file describing the error is returned to the merchant. Accepted files are processed, the included transactions are run, and the results are recorded. Upon completion of all transactions, the payment solution creates a response file containing all transactions and their outcomes (approved, declined, etc.).
To submit transaction files manually, a merchant must first create a transaction file and use the payment solution's on-line interface to upload the file to PayFacto. The received files are then checked for consistency. In case of error, the browser displays an error message.
The received files are put on hold and processed at the time set by PayFacto's solution. All transactions are processed individually and the payment solution creates a response file containing all transactions and their outcome (approved, declined, etc.). This file is available via the Web interface.
This section informs the merchant of the steps they must take to enable them to make batch payments with the PayFacto payment solution. Merchants who wish to transmit the transaction files via FTP must use a specific configuration.
The merchant must create a user name on the FTP server as well as three directories that can be both read from and written to.
Send Directory
The merchant must first create a directory that will contain the files for the PayFacto Solution to download. The merchant may give the directory any name. In this directory, the merchant must create a sub-directory named "done", which will contain the files that have been sent to PayFacto.
Receive Directory
Another directory must be created to contain the response files, including error files and transaction result files.
Merchants who wish to transfer files via FTP must contact Customer Service and provide the necessary information to connect to the FTP server:
It is now possible to configure a transfer via a standard secure protocol: SFTP (FTP over SSH) and FTPS (FTP over SSL). The last one may be used with implicit and explicit mode. It is possible to use a special port (other than the default) for these two modes of transfer. You need to notify your integrator during the integration process.
Security Notice
Our customers' servers are not within the PayFacto PCI-DSS scope. It is the customer's responsibility to configure their SFTP or FTPS servers, with a strong encryption, to meet the PCI-DSS standards.
Before transmitting transactions, the merchant must build a file containing all the transactions performed. These transactions consist of purchases, preauthorization, and preauthorization closings.
Six transaction types are supported. The obligatory parameters are as follows:
| Transaction | Required Parameters |
|---|---|
| Purchase | Transaction code, client number, amount, card number, expiration date, bill number |
| Preauthorization | Transaction code, client number, amount, card number, expiration date, bill number |
| Preauthorization completion | Transaction code, client number, amount, bill number, transaction number, authorization number, original bill number |
| Refund | Transaction code, client number, amount, card number, expiration date, bill number |
| Purchase without card (with token) | Transaction code, client number, amount, token, bill number. Optional parameters are ignored when performing the transaction. |
| Refund without card | Transaction code, client number, amount, bill number, original transaction number, original bill number |
The transaction file has two main sections: the header, which contains information about the merchant and the transaction batch, and the transaction section. The file must be in text format.
The header contains three parameters that need to be specified. Each parameter must be separated by a comma.
| Field | Format | Description |
|---|---|---|
| Batch number | 8 characters [A-Z, 0-9] | Unique identifier for the submitted transaction batch. The batch number may not be reused. |
| Merchant number | 8 characters [0-9] | The merchant identification number provided by PayFacto. |
| Number of transactions | 8 characters [0-9] | The number of characters in the file. [Source wording as provided — see note below.] |
Source Inconsistency Flagged
The source material describes "Number of transactions" as "the number of characters in the file," which reads inconsistently with the field name (a count of transactions vs. a count of characters). Reproduced verbatim per content-integrity rules — please confirm the intended meaning before publishing. [CONFIRM]
Transactions must be entered on separate lines after the header. Transactions may have 6 to 9 parameters, depending on the type: purchases and preauthorization each require 6 parameters, while authorization closings require 9 parameters. Each parameter must be separated by a comma.
Transaction code — 00, 01, 02, 03, 52, or 50 — indicates which type of transaction was performed:
00 : purchase01 : preauthorization02 : preauthorization completion03 : refund52 : purchase without card (with token)50 : refund without card| Field | Format | Description |
|---|---|---|
| Client number | 8 characters [a-Z, 0-9] | The client merchant's ID number (the person who performs the purchase with the merchant service). |
| Amount | 11 characters [0-9] | Amount of the transaction, 11 characters, without a decimal point. E.g.: 10.14 = 00000001014. |
| Card number | Up to 40 characters [0-9, space] | The client's credit card number to which the amount will be charged. For a purchase without card, the token replaces the card number. |
| Token | 35 characters [a-z, 0-9] | Purchase without card only. Replaces the card number; associated with a customer and a credit card number. Supplied by PayFacto upon registration of a client in the recurrence module — see the "Recurrence" documentation for details. |
| Expiration date | 4 characters [0-9] | Credit card expiration date, format MMYY. E.g.: April 08 = 0408. For a purchase without card, enter 4 spaces. |
| Bill number | 12 characters [A-Z, 0-9] | The merchant bill number for this transaction. Must contain 12 characters. E.g.: 123456789123. |
| Transaction number | Completion only. Up to 12 characters [0-9] | The transaction number of the preauthorization to close. Returned in the response file following the preauthorization. |
| Authorization number | Completion only. 8 characters [A-Z, 0-9, space] | The authorization number of the preauthorization to close. Returned in the response file following the preauthorization. |
| Original bill number | Completion only. 12 characters [0-9] | The bill number of the transaction to close. |
Empty parameters between commas are needed if they fall between required parameters. For a transaction code 50 line, the card number and expiration date are left empty because they fall between required parameters, while for a transaction code 00 line, unneeded parameters at the end of the line can simply be omitted.
Example File Image Not Provided
The source material references an "Example of Transaction File" image that was not included with the content provided. [CONFIRM: attach the example transaction-file screenshot/image before publishing]
The files must be on the FTP server by the time determined for batch processing. All files must have a .txt or .csv extension.
FTP Return File
When using an FTP server, return codes are sent to the current directory in a file that has the same name as the original file but a .err extension.
Web Interface Returns
In the Web interface, only import errors are reported. Errors are displayed during the importing.
Only basic validation procedures are performed when importing a batch file. If the file contains the correct number of parameters and if the parameters have the required length, the file is approved. However, the file may be declined later in the process if one or more of the following parameters do not meet the requirements:
Return file: [Batch Number].cvs
Return file name: yyyMMddhhmm_FileName.enc
Encrypted file name: BatchNumber_yyyyMMddhhmm.csv
Source Inconsistency Flagged
The source material gives three different, non-matching filename patterns for the return file (.cvs extension, a yyyMMddhhmm pattern with only three "y" characters, and a separately named encrypted file). Reproduced verbatim per content-integrity rules. [CONFIRM: correct return-file naming pattern]
Header line: batch number, merchant number, number of transactions.
| Field | Format |
|---|---|
| Batch number | 8 characters [A-Z, 0-9] |
| Merchant number | 8 characters [0-9] |
| Number of transactions | Digit [0-9] |
One line per transaction: transaction code, client number, amount, card number, expiration date, bill number, return code, transaction number, authorization number.
| Field | Format |
|---|---|
| Transaction code | 00, 01, or 02 |
| Client number | 8 characters [A-Z, 0-9] |
| Amount | 11 characters [0-9] |
| Card number | Up to 40 characters [space, 0-9] |
| Expiration date | 4 characters [0-9], MMYY |
| Bill number | 12 characters [A-Z, 0-9] |
| Return code | Up to 4 characters [A-Z, 0-9] — detailed separately, see Return Codes below |
| Transaction number | Completed transaction. Up to 12 characters [0-9] |
| Authorization number | Authorized transaction. 8 characters [A-Z, 0-9, space] |
If more than one merchant uses batch processing, a list of merchants will be displayed.
All batches are displayed in reverse chronological order. A batch has either a "Processing" or "Completed" status. If the batch is completed, the response file (the same one that was transferred via FTP) may be downloaded.
All batches are displayed in reverse chronological order. A batch has either a "Received", "Processing", or "Completed" status. A batch with a "Received" status may be deleted. If the batch is completed, the response file may be downloaded.
If the import was successful, the Web interface returns the message "Status Received (0)". Otherwise, a 60XX error message is displayed.
Batch payment's return codes (6000 series) are explained in the Return Codes document. [CONFIRM: link to the current Return Codes article]