Support

Submit a ticket My tickets Knowledge Base API Reference
Welcome
Login  Sign up
Open navigation

FlexPay Batch Integration Guide

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.

  1. Establish an SFTP session with FlexPay SFTP server host using your SFTP client software.
  2. Log in using your Batch account username and password. Contact your Client Success Manager to request your Sandbox or production SFTP Batch Upload credentials.
  3. Upload the Batch File. When uploading a file, it must be put in your inputs folder.
  4. Retrieve your response file from the outputs directory.
  5. 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.


FieldDescription
Host URLftp.flexpay.io
Port22


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

FieldsCode RangeDescription
Approved10000The request was successful.
Soft Decline20000The request declined, though subsequent attempts may be successful.
Hard Decline30000The request declined. Most hard declines require the Issuer or Cardholder to rectify the outstanding issue(s) before a subsequent attempt can be made.
Risk Responses40000The 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 Validation50000The 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.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.