Introduction

This guide outlines the process for integrating FlexPay's failed payment recovery solution using batch file uploads via SFTP. To ensure smooth processing, it’s essential that transaction files are correctly formatted before uploading. In this document, you'll learn how to set up your integration, format your input files, establish a connection, and manage the upload process. By following these steps, you can reduce validation errors and improve transaction processing efficiency.

Setup

FlexPay will set up two subfolders for you in our SFTP: Inputs and Outputs. You will upload your input files to be processed to the Inputs folder and download the processed output files from the Outputs folder.

Your Client Success Manager will provide you with credentials for the SFTP server.

You will need to provide FlexPay with the IP address of the machine which you will be uploading the files from.

Naming Your Input Files

Your input file must adhere to the following format: yyyyMMddHHmmss.txt

Where is the character’s code you used to define your company code in FlexPay's Client Portal

Example:

Company Code: FP_01

File Name: FP_0120220115000000.txt

You can find the code by going to the Companies section under Account Settings.

Connection

System Requirements

• An SFTP client software that uses SSH2.

Connection Details

To connect to the FlexPay Gateway SFTP server, you will require the following:

File Upload Steps

To utilize the Quick Start Recovery process and obtain credit card authorization or any of the other operation types, you must have obtained an account, username, and password from FlexPay.

1. Establish a session with FlexPay's SFTP server host using your SFTP client software.
2. Log in using your credentials.
3. Upload the flat file. When uploading a file, it must be put in your Inputs folder.

Input File Format

The file format is comma-delimited, with a txt extension, and no headers file. Attached to this document, you will find a sample with a handful of transactions to illustrate how the Input file should be formated.

Required: Fields that are mandatory for the recovery process to work. The file won't pass our initial validation if these fields are not provided:

• orderID
• transactionType
• currencyCode
• amount
• retryCount
• PaymentMethodMerchantAccountReferenceId (this is the MID / Merchant ID)

Conditional: Fields that are conditional. You must provide one or the other. It's better if you can provide both.

• referenceTransactionId (required only for REFUND or VOID)
• customerID OR billingEmail
• firstName & lastName OR fullName
• creditCardNumber OR PaymentMethodGatewayPaymentMethodId (payment token stored at the gateway) OR PaymentMethodGatewayTransactionId

Fields listed as optional are"good to have" and can assist our machine learning models, but are not mandatory for the transaction to be processed.

❗️

Note

Please make sure to always send ALL columns in the file. If you are not providing information for an optional field, you must leave the column intact to avoid changing the format of the file.

Downloading Your Output File

If your file fails the validation stage, it will not be processed, and our support team will contact you.

When it comes to the generation of output files, there are two options available to you. Please consult with your Customer Success Manager (CSM) to have your account configured according to your needs. It’s important to understand that the result of each transaction will only appear in one output file, so careful consideration of the options is essential.

• Option 1: Receive up to two output files per day for each input file. If your file is successfully processed, FlexPay will generate a corresponding output file, which will be available for download from your designated Output folder at 15:00 UTC and 22:00 UTC each day. For example, if a transaction is processed at 14:00 UTC, it will appear in the 15:00 UTC output file but not in the 22:00 UTC file. To ensure you have the complete list of processed transactions, you'll need to retrieve and review both daily output files.
• Option 2: Receive one consolidated output file per day for all transactions processed the previous day. Regardless of how many input files were processed, you will receive a single output file containing all results. This file will be made available at 15:00 UTC.

Output File Format

The output file generated by FlexPay will contain the results for all transactions included in your input file. The file is formatted as a comma-delimited text file (with a .txt extension) and does not include headers. The naming convention for the output file will vary based on the number of output files you receive each day, as outlined in the previous section.

Option 1: The file name will match your input file name, followed by an underscore (_) and a timestamp.

Option 2: The file name will follow this format: -3-yyyyMMdd.txt (where the date represents the day the transactions were processed).

For reference, see the attached output file template included with this guide.

Response Codes

For details on response codes, please refer to https://documentation.flexpay.io/reference/response-codes