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.


Field

Description

Host URL

sftp.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. 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:

FIELD

TYPE

DESCRIPTION

merchantTransactionId

String (50)

This data is typically used to reference transactions on the host systems and must display on any receipt presented to the customer.
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)

Transaction Response Code

message

String (500)

Response description returned from issuing institution. This message should not display on any cardholder facing materials

transactionId

String (50)

This field is the gateway-generated number to identify a transaction and can be used to submit a modification of this transaction at a later time (such as voiding or crediting the transaction or capturing an Authorize transaction).

referenceTransactionId

String (50)

ID of a transaction previously authorized/capture by the gateway.

transactionDate

DateTime

Processing host date stamp.

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 error code

errorDetail

String (250)

Indicates the error details

currencyCode


String (3)

Three-digit currency code (e.g. USD, CAD).   ISO 4217 Currency Codes

amount

Integer

Amount in cents (e.g. 1957 is equivalent to 19.57)

gatewayToken

String (50)

This field is the gateway associated with a merchant account against which the request is made.

gatewayType

String (50)

Code to identify on witch gateway the transaction has been attempt (e.g. Vantiv)

gatewayTransactionId


String (50)

Gateway transaction ID -- Gateway return Transaction ID

merchantAccountReferenceId

String (50)

Reference 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



This field is the gateway 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 a transaction: AUTHORIZE, CAPTURE, REFUND or VOID.

creditCardNumber



String (22)

This field is the card number you are charging for this transaction.
451112**4259(will be blank if status is error)

referenceData



String (512)

Reference data received from the gateway when a payment failed.  Return this data on retry transaction for the same payment.

retryDate


DateTime

Indicates the date and time when the transaction should be retried.

retryCount



Integer

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.

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.
























































































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 failed API validation and was not successful due to the error




















Approved



CODE

Description

10000

Approved

10001

The reversal was processed successfully.








Soft Decline


CODE

DESCRIPTION

20000

You need to refer to the Card Issuer

20002

Invalid or inactive merchant

20003

Declined - do not honor

20012

Re-enter transaction or transaction has been expired

20013

Invalid response

20018

Completed Partially

20022

Bank decline

20023

The card has been declined due to insufficient funds.

20039

Response timeout

20043

Transaction cannot be completed

20046

System error

20047

Other / Unidentified responses

20048

Unable to authorize

20050

Over daily limit

20056

Customer token/Id is incorrect or invalid

20057

Your merchant account authentication failed

20068

Invalid API access token

20073

Batch data is missing or Invalid

20075

Transaction limit for merchant exceeded

20076

Transaction required data are missing or invalid











































Hard Decline

CODE

DESCRIPTION

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

30017

Format Error

30019

Not a credit account

30024

Not a cheque account

30025

Not a savings account

30026

Expired card

30029

Transaction not permitted to that cardholder

30031

Suspected fraud

30034

Restricted card

30044

Duplicate transaction

30049

Decline for CVV2 failure

30051

Limit exceeded. Enter a lesser value.

30052

Invalid transaction date

30053

Card not supported

30055

Invalid expiry date format

30058

You submitted an unsupported card type with your request.

30059

Gateway declined - Invalid transaction

30061

The external gateway has reported that you have submitted an invalid currency with your request.

30062

Billing address is missing

30064

Authorisation already reversed (voided) or capture is larger than initial authorised value.

30065

Authorization is completed.

30066

Transaction already reversed

30071

Invalid API version

30074

Invalid customer/user

30077

This processor does not accept partial reversals.

30078

Original transaction for reversal not found.

30079

This transaction has already been captured.

30080

DO NOT RETRY - You need to refer to the Card Issuer

30081

DO NOT RETRY - Invalid or inactive merchant

30082

DO NOT RETRY - Do not honour

30083

DO NOT RETRY -  Re-enter transaction or transaction has been expired

30084

DO NOT RETRY -  Invalid response

30085

DO NOT RETRY -  Completed partially

30086

DO NOT RETRY -  Bank decline

30087

DO NOT RETRY -  The card has been declined due to insufficient funds

30088

DO NOT RETRY -  Response timeout

30089

DO NOT RETRY -  Transaction cannot be completed

30090

DO NOT RETRY -  System error

30091

DO NOT RETRY -  Other / Unidentified responses

30092

DO NOT RETRY -  Over daily limit

30093

DO NOT RETRY - Customer token/Id is incorrect or invalid

30094

DO NOT RETRY - Customer token/Id is incorrect or invalid

30095

DO NOT RETRY - Your merchant account authentication failed

30096

DO NOT RETRY - Invalid API access token

30097

DO NOT RETRY - Batch data is missing or Invalid

30098

DO NOT RETRY - Transaction limit for merchant exceeded

30099

DO NOT RETRY - Transaction required data are missing or invalid

30100

DO NOT RETRY - Retry limit reached

























































































































Risk Responses


CODE

DESCRIPTION

40000

Risk Blocked Transaction refused due to risk model

40002

Gateway declined - Blacklist transaction cannot be processed

40003

Gateway 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.

40004

Gateway 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.

40006

Declined – AVS (Address) not matched the transaction payment method.

40007

Mismatch - Shipping to billing shipping country does not match billing country.

40008

Mismatch - Shipping to BIN shipping country does not match bin country.

40009

Mismatch - Shipping to IP shipping country does not match IP country.

40010

Mismatch - Billing to BIN billing country does not match bin country.

40011

Mismatch - Billing to IP billing country does not match IP country.

40012

Mismatch - BIN to IP BIN country does not match IP country.

40030

Gateway declined - Card number is blacklisted

40031

Gateway declined - IP address is blacklisted

40032

Gateway declined - Email is blacklisted

40033

Gateway declined - Phone number is Blacklisted







































API Validation

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’.