Quick Start Recovery
Discover how to leverage FlexPay's failed payment recovery using flat file uploads via SFTP for seamless transaction processing.
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:
Field | Value |
---|---|
Host URL | ftp.flexpay.io |
Protocol | SFTP |
Port | 22 |
Authentication Type | Normal |
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.
- Establish a session with FlexPay's SFTP server host using your SFTP client software.
- Log in using your credentials.
- 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.
Field | Type | Requirement | Description |
---|---|---|---|
merchantTransactionId | String (50) | Optional | This field is your unique ID number associated with each transaction request. You create this value and submit it with the transaction. If you decide to provide this value, it will only be used in the first retry attempt. Subsequent attempts will have a value generated by FlexPay |
orderId | String (50) | Required | Merchant-assigned order identification number. |
description | String (255) | Optional | Describe the transaction to help reconciliation. |
transactionType | String (15) | Required | Indicates the type of transaction which must be either CHARGE, REFUND, VOID. If the value in the field does not match any of the values stated, the transaction will be rejected. |
referenceTransactionId | String (50) | Conditional | ID of a transaction previously approved by the gateway. Required when sending REFUND or VOID transaction type |
customerId | String (50) | Conditional | Merchant-defined, unique identifier to represent the customer associated with the transaction. Required if the email is not provided. Otherwise, a new customer ID is created and returned. |
currencyCode | String (3) | Required | Three-digit currency code (e.g. USD, CAD). ISO 4217 Currency Codes |
amount | Integer | Required | Amount in cents (e.g. 1957 is equivalent to 19.57) |
creditCardNumber | String (22) | Conditional | Required if no PaymentMethodGatewayPaymentMethodId is passed. This field is the card number you are charging for this transaction. |
expiryMonth | String (2) | Required | Card expiry month expressed as MM (e.g. 06 for June) |
expiryYear | String (4) | Required | Card expiry year expressed as YYYY (e.g. 2027) |
cvv | String (4) | Do not include | This is the 3- or 4-digit security code that appears on the back of the card of a credit card following the card number. This code does not appear on imprints. |
firstName | String (50) | Optional | Recommended if fullName not included. Contains the first name of the customer associated with the billing address for the transaction. Note: This field is required for some payment gateways |
lastName | String (50) | Optional | Recommended if fullName not included. Contains the last name of the customer associated with the billing address for the transaction. Note: This field is required for some payment gateways |
fullName | String (100) | Optional | Recommended if firstName & lastName not included. The full name of the cardholder. If provided, will be parsed to determine firstName and lastName. Note: This field is required for some payment gateways |
billingAddress1 | String (255) | Optional | Contains the address line 1 of the customer associated with the billing address for the transaction. Suggested for Address Verification System (AVS). |
billingAddress2 | String (255) | Optional | Contains the address line2 of the customer associated with the billing address for the transaction. |
postalCode | String (100) | Optional | Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction. Suggested for Address Verification System (AVS). Can be 5 or 9 digits in length. |
billingCity | String (100) | Optional | The field contains the city of the customer associated with the billing address for the transaction. |
billingState | String (100) | Optional | The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name. |
billingCountry | String (3) | Optional | The field contains the country of the customer associated with the billing address for the transaction. Three-letter country codes defined in ISO 3166-1. |
billingEmail | String (100) | Conditional | Cardholder's email address. |
billingPhoneNumber | String (100) | Optional | Cardholder's phone number. |
customerIp | String (15) | Optional | IP address of the customer initiating the transaction. The required format is 255.255.255.255. |
shippingAddress1 | String (255) | Optional | Contains the address line 1 of the customer associated with the shipping address for the transaction. |
shippingAddress2 | String (255) | Optional | Contains the address line 2 of the customer associated with the shipping address for the transaction. |
shippingPostalCode | String (100) | Optional | Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction. |
shippingCity | String (100) | Optional | The field contains the city of the customer associated with the shipping address for the transaction. |
shippingState | String (100) | Optional | The field contains the state of the customer associated with the shipping address for the transaction. Any valid two characters’ state code or full state name. |
shippingCountry | String (3) | Optional | The field contains the country of the customer associated with the shipping address for the transaction. Three-letter country codes defined in ISO 3166-1 |
assignedGatewayToken | String (50) | Optional | This field is the gateway associated with a merchant account against which the request will be made on a next attempt. |
productSku | String (150) | Optional | The field contains the unique product identifier (SKU). |
productCategory | String (150) | Optional | Contains the primary category code associated with the product. |
billingPlan | String (50) | Optional | Contains the code associated with the billing plan. |
retryCount | Integer | Required | The field contains the number of retry of the billing cycle. The initial attempt is 0 and all others retries will increase the count by 1. |
billingCycle | Integer | Optional | When the transaction is for a recurring payment, the field contains billing cycle number. Start at 1 |
dateFirstAttempt | DateTime | Optional | The field contains the date of the first transaction attempt for this billing cycle. The date is required when the retry count is greater than 1. UTC and date format(Iso 8601) YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00) |
referenceData | String (512) | Optional | This field is for internal use only. FlexPay will generate this value and use it to link a series of retry attempts. |
customVariable1 | String (50) | Optional | Optional user defined string value. |
customVariable2 | String (50) | Optional | Optional user defined string value. |
customVariable3 | String (50) | Optional | Optional user defined string value. |
customVariable4 | String (50) | Optional | Optional user defined string value. |
customVariable5 | String (50) | Optional | Optional user defined string value. |
PaymentMethodToken | String (22) | Optional | This field is needed when using tokens generated in FlexPay's vault. It will also be used for the RedactPaymentMethod transaction type when using credit cards. Please consult with your Client Success Manager for details. |
PaymentMethodMerchantAccountReferenceId | String (512) | Conditional | Gateway identifier configured in a FlexPay Payment Gateway. Typically the Merchant Account Reference Id is the same value as a Merchant Account ID in order to facilitate reconciliation. |
PaymentMethodGatewayPaymentMethodId | String (256) | Conditional | This is the payment token stored at the payment gateway. This is required if the full credit card number is not provided. |
PaymentMethodGatewayTransactionId | String (50) | Conditional | Certain gateways use a transaction ID to represent a payment method (for example: NMI). |
PaymentMethodFirstSixDigits | String (6) | Optional | The first six digits of the customers credit card. This is used to determine strategies within our machine learning system. |
PaymentMethodLastFourDigits | String (4) | Optional | The last four digits of the customers credit card. This is used to determine strategies within our machine learning system. |
DelayedDate | DateTime | Optional | When this value is set, we will process the transaction at the given time |
gatewaySpecificFields | JSON | Optional | JSON object containing the gateway specific fields. See our documentation for your particular gateway. If not providing any info, please add empty brackets in double quotes "{}" |
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.
Field | Type | Description |
---|---|---|
merchantTransactionId | String (50) | This data is typically used to refere nce transactions on the host systems. This information is to be stored by the merchant. |
transactionStatus | Integer | Indicates the result of the transaction: 1 = Approved, 2 = Declined, 3 = Error |
responseCode | String (6) | FlexPay's Transaction Response Code |
message | String (500) | FlexPay's Transaction Response Message |
transactionId | String (50) | FlexPay's transaction identifier |
referenceTransactionId | String (50) | FlexPay's identifier of a transaction previously charged/authorized/captured. |
transactionDate | Date | Timestamp from the moment the transaction was processed. ISO 8601 |
avsCode | String (1) | Indicates the address verification result code |
avsMessage | String (250) | Indicates the address verification result message |
cvvCode | String (15) | Indicates the CVV verification result code |
cvvMessage | String (250) | Indicates the CVV verification result message |
errorCode | String (15) | Indicates the gateway response code |
errorDetail | String (250) | Indicates the gateway response message |
currencyCode | String (3) | Three-character currency code (e.g. USD, CAD). ISO 4217 |
amount | Integer | Amount in cents (e.g. 1957 is equivalent to 19.57) |
gatewayToken | String (50) | This field is FlexPay's gateway identifier associated with a merchant account against which the request is made. |
gatewayType | String (50) | Code to identify on which gateway the transaction has been attempted (e.g. worldpay_litle) |
gatewayTransactionId | String (50) | Transaction ID returned by the gateway |
merchantAccountReferenceId | String (50) | Reference ID tied to the merchant account used for the transaction |
customerId | String (50) | Merchant-defined, unique identifier to represent the customer associated with the transaction. Required if the email is not provided. Otherwise, a new customer ID is created and return. |
assignedGatewayToken | String (50) | This field is FlexPay's gateway identifier associated with a merchant account against which the request will be made on a next attempt. |
orderId | String (50) | Return the merchant-assigned order identification number from the request. |
transactionType | String (15) | This field indicates the type of transaction: CHARGE, AUTHORIZE, CAPTURE, REFUND, VOID or REDACTPAYMENTMETHOD |
creditCardNumber | String (22) | This field is the masked card number you are charging for this transaction. (Example: 451112**4259). It will be blank if a different payment method was used or if transaction type is Capture, Refund or Void |
referenceData | String (512) | Reference data generated by FlexPay. This value is sent back in the next retry transaction for the same payment. |
retryDate | DateTime | Indicates the date and time when the transaction will be retried |
retryCount | Integer | The number of retries of the billing cycle. The initial attempt is 0 and all other retries will increase the count by 1. |
dateFirstAttempt | DateTime | The field contains the date of the first transaction attempt for this billing cycle. Date Format Iso 8601 and is UTC |
customVariable1 | String (50) | Optional user defined string value. |
customVariable2 | String (50) | Optional user defined string value. |
customVariable3 | String (50) | Optional user defined string value. |
customVariable4 | String (50) | Optional user defined string value. |
customVariable5 | String (50) | Optional user defined string value. |
PaymentMethodId | String (22) | FlexPay vault token |
PaymentMethodStorageState | String (50) | Storage status of the payment method |
PaymentMethodMerchantAccountReferenceId | String (512) | Merchant account linked to the payment method |
PaymentMethodType | String (50) | The type of payment method |
gatewaySpecificResponseFields | String (512) | JSON payload containing the gateway specific response fields. NOTE: this is only included if the gateway supports it and if the JSON column was included in the Input file. |
Response Codes
For details on response codes, please refer to https://documentation.flexpay.io/reference/response-codes
Updated 3 months ago