There will often be instances when you as a merchant will want to process high volumes of data in a single operation, rather than making individual calls to the API. For example, importing existing mandates, enrolling a large number of customers or creating dozens, hundreds or even thousands of payment orders simultaneously.
All of these batch processes can be handled using SlimPay’s File API.
Batch files (in either version 1 or version 2 format) submitted to the File API can be uploaded via the Back Office (Dashboard V.1) or deposited via SFTP. SlimPay can also configure specific connections to suit your individual needs.
Just like the Web API, there are two File API environments:
- Preprod: a sandbox environment for your development and testing phases
- Production: your live, business environment where you will collect payments
For SFTP connection to each environment, you will need to provide a public key. Once access is created, SlimPay will provide you with:
- The host
- The port
- Your username
A dedicated SFTP folder will then be created for you, containing two subfolders:
in: this is where you will deposit your batch files
out: acknowledgement (
.ack) and error reporting (
.err) files will be deposited here by SlimPay following each file injection
Here is an example of a standard SFTP connection using command line:
sftp -o Port=<port> -o IdentityFile=<path_to_private_key> <username>@<host>
Most of the operations available in our File API can be handled using a simplified CSV format. The charset should be encoded in UTF-8, with the fields of each line separated by a semi-colon
;. For more specific details on the file format, please see our Payments or Remittance File section.
File acknowledgement and error handling
After a batch CSV file is injected (either via SFTP or the Back Office), SlimPay will first verify its encoding and syntax, to ensure that it is formatted correctly (for example, checking whether all mandatory fields have been populated). If your file is correctly formatted, a file with the same name but with the extension
.ack is immediately created to acknowledge receipt of the batch file.
If the injected file is incorrectly formatted, a file with the same name but with the extension
.err is immediately created, containing messages clarifying syntactical errors.
Please note: generation of an
.ack file offers no guarantee regarding the quality of the data provided. It is purely a format validation. In other words, an injected file that is syntactically correct will be acknowledged, but could still contain erroneous data.
Following this initial validation check, the file and its data will then be processed. Except for direct debit and credit transfer orders, SlimPay will always generate a results (
.res) file, which identifies any potential errors regarding the quality of the injected data (for example, a mandate’s unique reference may already exist, or a customer’s IBAN may be invalid etc).
For direct debit and credit transfer orders, a
.res file is not created by default, because the outcome of the payment orders is not known at the time the file is processed. If a payment order does fail, however, SlimPay will generate an NOP/REJ file outlining the specific payment issues.