Getting Started
FlexPay’s batch charge processing service allows merchants to perform the Authorize, Capture, Refund, and Void charge actions in bulk by connecting to FlexPay’s servers via SFTP and uploading encrypted files containing the relevant transaction data to a designated INPUTS folder.
FlexPay will process files and will output processed files to a designated OUTPUTS folder where they will be available for you to download.
The payment gateway only accepts upload transaction files that are formatted correctly. Before you upload a transaction file, it is important that you understand how to format and customize transaction information. Preparing upload transaction files will decrease transaction validation and processing errors, which saves you time.
Setup
FlexPay will set up two subfolders for you: 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.
Naming Your Input Files
Your input file must adhere to the following format: <companycode>yyyyMMddHHmmss.txt
Where <companycode> is the character’s code you used to define your company code.
Example
Company Code: CompA
File Name: compa20170112014532.txt
Once you have created your input file, it is ready to be uploaded to your security key.
Secured FTP Connection
When you upload transaction files, they contain sensitive data such as card numbers. For this reason, it is necessary to upload these files over a secure FTP connection. Part of this process includes creating a security key, which is used when connecting with FlexPay. This security key has two parts: a private key, which you keep on your PC, and a public key, which you will email to FlexPay.
Type of key to generate: SSH2 DSA
When we have received your public key and our own setup is complete, we will email you a confirmation. Once you receive this confirmation, you can begin to upload transaction files.
Uploading Your Input File
Once your file is encrypted, upload it via SFTP to your designated Inputs folder.
Uploaded transaction files pass through three stages.
- File Upload – You choose which file of transactions to upload from your local system.
- Data Formatting – The payment gateway validates the transaction file for formatting errors.
- Transaction Processing – Files that pass the data format validation are then placed in the current batch to await settlement.
Once you have created your input file, it is ready to be uploaded to your security key.
Connection
System Requirements
- You will require an SFTP client software which must use SSH2.
File Upload Steps
To utilize the batch file upload and obtain credit card authorization or any of the other operation types, you must have obtained a Batch account username and password from FlexPay.
- Establish an SFTP session with FlexPay SFTP server host using your SFTP client software.
- Log in using your Batch account username and password. Contact your Client Success Manager to request your Sandbox or production SFTP Batch Upload credentials.
- Upload the Batch File. When uploading a file, it must be put in your inputs folder.
- Retrieve your response file from the outputs directory.
- When a file is completed, the response file is sent to the outputs folder. The filename will be identical to what was uploaded.
Connection Details
To connect to the FlexPay Gateway SFTP server, you will require the following.
| Field | Description |
| Host URL | ftp.flexpay.io |
| Port | 22 |
Configuring your CRM system
Though every Customer Relationship Management system or sales tool is different there are key areas that will need to be adjusted during FlexPay integration.
| Configuration point | Description |
| Bank Routes | A bank route will need to be created to allow transactions to be routed to FlexPay. |
| Batch Reports | Batch reports sending transactions to FlexPay will need to be configured to be dropped to the SFTP provided by FlexPay. |
| Retry logic | Any pre-existing retry logic in your system will have to be disabled to allow FlexPay retries to take precedence. |
Processing Environment
Batch account username is used to distinguish between the FlexPay QA environment available for testing versus the live production environment which will connect to the live processing host.
Input File Format
| Field | Type | Required | Description |
| merchantTransactionId | String (50) | Yes | This field is your unique ID number associated with each transaction request. You create this value and submit it with the transaction. |
| orderId | String (50) | Yes | Merchant-assigned order identification number. |
| description | String (255) | No | Describe the transaction to help reconciliation. |
| transactionType | String (15) | Yes | Indicates the type of transaction and it must be exactly one of CHARGE, AUTHORIZE, CAPTURE, REFUND, VOID. If the value in the field does not match any of the values stated, the transaction will be rejected. If no value is submitted in this field, the gateway will process the transaction as a CAPTURE. |
| referenceTransactionId | String (50) | Yes | ID of a transaction previously authorized/capture by the gateway. May be required and necessary only for REFUND, VOID or CAPTURE (after AUTHORIZED) type transactions. |
| customerId | String (50) | No | 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. |
| currencyCode | String (3) | Yes | Three-digit currency code (e.g. USD, CAD). ISO 4217 Currency Codes |
| amount | Integer | Yes | Amount in cents (e.g. 1957 is equivalent to 19.57) |
| creditCardNumber | String (22) | Yes | This field is the card number you are charging for this transaction. |
| expiryMonth | String (2) | Yes | Card expiry month expressed as MM (e.g. 06 for June) |
| expiryYear | String (4) | Yes | Card expiry year expressed as YYYY (e.g. 2017) |
| cvv | String (4) | No | 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) | No | 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) | No | 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) | No | 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) | No | 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) | No | Contains the address line2 of the customer associated with the billing address for the transaction. |
| postalCode | String (100) | Yes | 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) | Yes | The field contains the city of the customer associated with the billing address for the transaction. |
| billingState | String (100) | Yes | 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) | Yes | 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) | No | Cardholder's email address. Optional if customer ID is provided. |
| billingPhoneNumber | String (100) | No | Cardholder's phone number. Optional if customer Id is provided. |
| customerIp | String (15) | No | IP address of the customer initiating the transaction. The required format is 255.255.255.255. |
| shippingAddress1 | String (255) | No | Contains the address line 1 of the customer associated with the shipping address for the transaction. |
| shippingAddress2 | String (255) | No | Contains the address line 2 of the customer associated with the shipping address for the transaction. |
| shippingPostalCode | String (100) | No | Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction. |
| shippingCity | String (100) | No | The field contains the city of the customer associated with the shipping address for the transaction. |
| shippingState | String (100) | No | 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) | No | 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) | No | This field is the gateway associated with a merchant account against which the request will be made on a next attempt. |
| productSku | String (150) | No | The field contains the unique product identifier (SKU). |
| productCategory | String (150) | No | Contains the primary category code associated with the product. |
| billingPlan | String (50) | No | Contains the code associated with the billing plan. |
| retryCount | Integer | Yes | 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 optional | Integer | No | When the transaction is for a recurring payment, the field contains billing cycle number. Start at 1. |
| dateFirstAttempt | DateTime | No | 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) | No | Reference data received from the gateway when a payment failed. Return this data on retry transaction for the same payment. |
| customVariable1 | String (50) | No | Optional user defined string value. |
| customVariable2 | String (50) | No | Optional user defined string value. |
| customVariable3 | String (50) | No | Optional user defined string value. |
| customVariable4 | String (50) | No | Optional user defined string value. |
| customVariable5 | String (50) | No | Optional user defined string value. |
Downloading Your Output File
If your file fails the validation stage, it will not be processed and our support team will contact you.
If your file processed successfully, FlexPay will create a corresponding output file with the same filename and extension as the input and make it available for download from your designated OUTPUT folder.
Output File Format
The output file generated by FlexPay will contain the updated statuses of all the transactions included in your input file. The file format is comma-delimited and uses a double-quote and uses (“) encapsulation character without header. Each transaction row in the output file will be formatted and ordered as follows:
Response Codes
| Fields | Code Range | Description |
| Approved | 10000 | The request was successful. |
| Soft Decline | 20000 | The request declined, though subsequent attempts may be successful. |
| Hard Decline | 30000 | The request declined. Most hard declines require the Issuer or Cardholder to rectify the outstanding issue(s) before a subsequent attempt can be made. |
| Risk Responses | 40000 | The request triggered a risk response. The status of the response (responseCode and status) will depend on the action specified in your risk settings on your gateway. |
| API Validation | 50000 | The request triggered a risk response. The status of the response (responseCode and status) will depend on the action specified in your risk settings on your gateway. |
Follow this link to see the full list of FlexPay Response Codes.