Help Desk

Submit a ticket My tickets
Welcome
Login  Sign up

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 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 Tungsten 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 Tungsten 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 account 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. Maybe 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)
Yes
Contains the first name of the customer associated with the billing address for the transaction.
lastName
String (50)
Yes
Contains the last name of the customer associated with the billing address for the transaction.
fullName
String (100)
No
The full name of the cardholder. If provided, will be parsed to determine firstName and lastName.
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.


CodeDescription
10000Approved.
10001The reversal was processed successfully.


CodeDescription
20000You need to refer to the Card Issuer
20002Invalid or inactive merchant
20003Declined - do not honor
20012
Re-enter transaction or transaction has been expired
20013Invalid response
20018Completed partially
20022Bank decline
20023The card has been declined due to insufficient funds
20039Response timeout
20043Transaction cannot be completed
20046System error
20047Other / Unidentified responses
20048Unable to authorize
20050Over daily limit
20056Customer token/Id is incorrect or invalid
20057Your merchant account authentication failed
20068Invalid API access token
20073Batch data is missing or invalid
20075Transaction limit for merchant exceeded
20076Transaction required data are missing or invalid


CodeDescription
30000
The bank has requested that you retrieve the card from the cardholder - validate with the bank.
30001
The bank has requested that you retrieve the card from the cardholder - it may be a lost or stolen card.

30002

Invalid card: Luhn algorithm failed (MOD - 10)

30003
Expired Card - Pick Up
30004
Suspected Fraud - Pick Up
30006
Restricted Card - Pick Up
30008
The bank has requested that you retrieve the card from the cardholder - it may be a lost card.
30009
The bank has requested that you retrieve the card from the cardholder - it may be a stolen card.
30010
The void request failed.
30011
Invalid transaction
30012
Invalid card number
30013
The reversal request failed.
30015
The external gateway has reported that you have submitted an invalid amount with your request.
30016
Error / Invalid parameters in the request
30017Format Error
30019Not a credit account
30024Not a cheque account
30025Not a savings account
30026Expired card
30029Transaction not permitted to that cardholder
30031Suspected fraud
30034Restricted card
30044Duplicate transaction
30049Decline for CVV2 failure
30051Limit exceeded. Enter a lesser value.
30052Invalid transaction date
30053Card not supported
30055Invalid expiry date format
30058You submitted an unsupported card type with your request.
30059Gateway declined - Invalid transaction
30061The external gateway has reported that you have submitted an invalid currency with your request.
30062Billing address is missing
30064Authorisation already reversed (voided) or capture is larger than initial authorised value.
30065Authorization is completed.
30066Transaction already reversed
30071Invalid API version
30074Invalid customer/user
30077This processor does not accept partial reversals.
30078Original transaction for reversal not found.
30079This transaction has already been captured.
30080DO NOT RETRY - You need to refer to the Card Issuer
30081DO NOT RETRY - Invalid or inactive merchant
30082DO NOT RETRY - Do not honour
30083DO NOT RETRY -  Re-enter transaction or transaction has been expired
30084DO NOT RETRY -  Invalid response
30085DO NOT RETRY -  Completed partially
30086DO NOT RETRY -  Bank decline
30087DO NOT RETRY -  The card has been declined due to insufficient funds
30088DO NOT RETRY -  Response timeout
30089DO NOT RETRY -  Transaction cannot be completed
30090DO NOT RETRY -  System error
30091DO NOT RETRY -  Other / Unidentified responses
30092DO NOT RETRY -  Over daily limit
30093DO NOT RETRY - Customer token/Id is incorrect or invalid
30094DO NOT RETRY - Customer token/Id is incorrect or invalid
30095DO NOT RETRY - Your merchant account authentication failed
30096DO NOT RETRY - Invalid API access token
30097DO NOT RETRY - Batch data is missing or Invalid
30098DO NOT RETRY - Transaction limit for merchant exceeded
30099DO NOT RETRY - Transaction required data are missing or invalid
30100DO NOT RETRY - Retry limit reached


CodeDescription
40000Risk Blocked Transaction refused due to risk model
40002Gateway declined - Blacklist transaction cannot be processed
40003Gateway declined - CVV is missing or incorrect. The merchant’s configuration requires a CVV to be entered, but no CVV was provided with this transaction or CVV is incorrect.
40004Gateway declined - Postal code failed The card’s postal code failed validation.
40005
Gateway declined - Missing required data. Please make sure all required data is sent, such as: CVV, Expiry date, Cardholder name, Billing address, Postalcode etc.
40006Gateway declined - Missing required data. Please make sure all required data is sent, such as: CVV, Expiry date, Cardholder name, Billing address, Postalcode etc.
40007Mismatch - Shipping to billing shipping country does not match billing country.
40008Mismatch - Shipping to BIN shipping country does not match bin country.
40009Mismatch - Shipping to IP shipping country does not match IP country.
40010Mismatch - Billing to BIN billing country does not match bin country.
40011
Mismatch - Billing to IP billing country does not match IP country.
40012Mismatch - BIN to IP BIN country does not match IP country.
40030Gateway declined - Card number is blacklisted
40031Gateway declined - IP address is blacklisted
40032Gateway declined - Email is blacklisted
40033Gateway declined - Phone number is Blacklisted


CODE
DESCRIPTION
50000
Validation error
50002
An error was experienced while parsing the payload. Please ensure that the structure is correct.
50003
No parameters were found
50005
Authorization has been denied for this request.
50014
Invalid 'CustomerToken' length
50015
Invalid 'Email' length
50020
Invalid 'PhoneNumber' length    
50028
Invalid 'FullName' length
50029
Invalid 'ProvinceStateCode' length
50037
Invalid 'CustomerIp' length    
50039
Invalid value for 'CountryCode'
50045
Field 'CurrencyCode' is required
50048
Field 'CustomerToken' or 'email' are required
50055
Field 'Month' is required
50056
Invalid value for 'Month'
50057
Field 'Year' is required
50058
Invalid value for 'Year'
50059
Field 'CreditCardNumber' is required
50060
Invalid 'CreditCardNumber' Length
50068
Invalid 'MerchantDescriptor' length    
50073
Invalid 'CurrencyCode' length
50088
Field 'FirstName' is required
50089
Field 'LastName' is required
50090
Fields 'FullName' or 'FirstName' and 'LastName' are required
50091
Invalid 'FirstName' length
50092
Invalid 'LastName' length
50093
Field 'CountryCode' is required
50094
Field 'PostalCode' is required
50095
Invalid 'PostalCode' length
50096
Field 'ProvinceStateCode' is required
50097
Field 'City' is required
50098
Invalid 'City' length
50099
Field 'Address1' is required
50100
Invalid 'Address1' length
50103
Field 'MerchantTransactionReferenceId' is required
50104
Invalid 'MerchantTransactionReferenceId' length
50105
Invalid 'TransactionType'
50106
Invalid 'CustomField1' length
50107
Invalid 'CustomField2' length
50108
Invalid 'CustomField3' length
50109
Invalid 'CustomField4' length
50110
Invalid 'CustomField5' length
50111
Invalid 'ReferenceData' length
50112
Invalid 'ShippingPhoneNumber' length
50113
Invalid 'ShippingCountryCode' length
50114
Invalid 'ShippingPostalCode' length
50115
Invalid 'ShippingProvinceStateCode' length
50116
Invalid 'ShippingCity' length
50117
Invalid 'ShippingAddress2' length
50118
Invalid 'ShippingAddress1' length
50119
Invalid 'Address2' length
50120
Invalid 'BillingPlanCode' length
50121
Invalid 'ProductCategoryName' length
50122
Invalid 'ProductSku' length
50123
Invalid 'MerchantLocation' length
50124
Invalid 'Description' length
50125
invalid 'GatewayTransactionToken' length
50126
Field 'OrderId' is required
50127
Invalid 'OrderId' length
50128
Invalid 'GatewayToken' length
50129
Field 'MerchantTransactionReferenceId' must be unique
50130
No gateways are configured to process the submitted card type.
50131
Original transaction not found using the field ‘TransactionReferenceId’.

Did you find it helpful? Yes No

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