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