Open navigation

Quick Start Recovery Integration Guide

Getting Started

FlexPay 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 in our SFTP: 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.
  • Your Client Success Manager will provide you with credentials for the SFTP server.
  • You will need to provide FlexPay with the IP address of the machine where you will be uploading the files from.

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 in FlexPay's Client Portal

Example:

Company Code: FP_01

File Name: FP_0120220115000000.txt

You can find the code by going to the Companies section under Account Settings.


Connection

System Requirements

  • You will require an SFTP client software that must use SSH2.

File Upload Steps

To utilize the Quick Start Recovery process and obtain credit card authorization or any of the other operation types, you must have obtained an account, username, and password from FlexPay.

  1. Establish a session with FlexPay's SFTP server host using your SFTP client software.
  2. Log in using your credentials.
  3. Upload the flat file. When uploading a file, it must be put in your Inputs folder.

Connection Details

To connect to the FlexPay Gateway SFTP server, you will require the following:

FieldDescription
Host URLftp.flexpay.io
ProtocolSFTP
Port22
Authentication TypeNormal

Input File Format

The file format is comma-delimited, with a txt extension, and no headers file. Attached to this document, you will find a sample with a handful of transactions to illustrate how the Input file should be formated.

  • Required: Fields that are mandatory for the recovery process to work. The file won't pass our initial validation if these fields are not provided:
    • orderId
    • transactionType
    • currencyCode
    • amount
    • postalCode
    • billingCity
    • billingState
    • PaymentMethodMerchantAccountReferenceId (this is the MID / Merchant ID)
  • Conditional: Fields that are conditional. You must provide one or the other. It's better if you can provide both.
    • referenceTransactionId (required only for REFUND or VOID)
    • customerID OR billingEmail
    • firstName & lastName OR fullName
    • creditCardNumber OR PaymentMethodGatewayPaymentMethodId (payment token stored at the gateway) OR PaymentMethodGatewayTransactionId

Fields listed as optional are"good to have" and can assist our machine learning models, but are not mandatory for the transaction to be processed.

Please make sure to always send ALL columns in the file. If you are not providing information for an optional field, you must leave the column intact to avoid changing the format of the file. 

► Click to view all fields
FieldTypeRequirementDescription
merchantTransactionIdString (50)OptionalThis field is your unique ID number associated with each transaction request. You create this value and submit it with the transaction. If you decide to provide this value, it will only be used in the first retry attempt. Subsequent attempts will have a value generated by FlexPay
orderIdString (50)RequiredMerchant-assigned order identification number.
descriptionString (255)OptionalDescribe the transaction to help reconciliation.
transactionTypeString (15)RequiredIndicates the type of transaction which must be either CHARGE, REFUND, VOID. If the value in the field does not match any of the values stated, the transaction will be rejected.
referenceTransactionIdString (50)ConditionalID of a transaction previously approved by the gateway. Required when sending REFUND or VOID transaction type
customerIdString (50)ConditionalMerchant-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 returned.
currencyCodeString (3)RequiredThree-digit currency code (e.g. USD, CAD).   ISO 4217 Currency Codes
amountIntegerRequiredAmount in cents (e.g. 1957 is equivalent to 19.57)
creditCardNumberString (22)ConditionalRequired if no PaymentMethodGatewayPaymentMethodId is passed. This field is the card number you are charging for this transaction.
expiryMonthString (2)RequiredCard expiry month expressed as MM (e.g. 06 for June)
expiryYear String (4)RequiredCard expiry year expressed as YYYY (e.g. 2029)
cvvString (4)Do not includeThis 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.
firstNameString (50)OptionalRecommended 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
lastNameString (50)OptionalRecommended 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
fullNameString (100)OptionalRecommended 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
billingAddress1String (255)OptionalContains the address line 1 of the customer associated with the billing address for the transaction. Suggested for Address Verification System (AVS).
billingAddress2String (255)OptionalContains the address line2 of the customer associated with the billing address for the transaction.
postalCodeString (100)OptionalContains 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.
billingCityString (100)OptionalThe field contains the city of the customer associated with the billing address for the transaction.
billingStateString (100)OptionalThe 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.
billingCountryString (3)OptionalThe field contains the country of the customer associated with the billing address for the transaction.  Three-letter country codes defined in ISO 3166-1.
billingEmailString (100)ConditionalCardholder's email address.
billingPhoneNumberString (100)OptionalCardholder's phone number.
customerIpString (15)OptionalIP address of the customer initiating the transaction. The required format is 255.255.255.255.
shippingAddress1String (255)OptionalContains the address line 1 of the customer associated with the shipping address for the transaction.
shippingAddress2String (255)OptionalContains the address line 2 of the customer associated with the shipping address for the transaction.
shippingPostalCodeString (100)OptionalContains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
shippingCityString (100)OptionalThe field contains the city of the customer associated with the shipping address for the transaction.
shippingStateString (100)OptionalThe 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.
shippingCountryString (3)OptionalThe field contains the country of the customer associated with the shipping address for the transaction.  Three-letter country codes defined in ISO 3166-1
assignedGatewayTokenString (50)OptionalThis field is the gateway associated with a merchant account against which the request will be made on a next attempt.
productSkuString (150)OptionalThe field contains the unique product identifier (SKU).
productCategoryString (150)OptionalContains the primary category code associated with the product.
billingPlanString (50)OptionalContains the code associated with the billing plan.
retryCountIntegerRequired
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.
billingCycleIntegerOptionalWhen the transaction is for a recurring payment, the field contains billing cycle number. Start at 1
dateFirstAttemptDateTimeOptionalThe 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)
referenceDataString (512)OptionalThis field is for internal use only. FlexPay will generate this value and use it to link a series of retry attempts.
customVariable1String (50)OptionalOptional user defined string value.          
customVariable2String (50)OptionalOptional user defined string value.
customVariable3String (50)OptionalOptional user defined string value.
customVariable4String (50)OptionalOptional user defined string value.
customVariable5String (50)OptionalOptional user defined string value.
PaymentMethodTokenString (22)OptionalThis field is needed when using tokens generated in FlexPay's vault. It will also be used for the RedactPaymentMethod transaction type when using credit cards. Please consult with your Client Success Manager for details.
PaymentMethodMerchantAccountReferenceIdString (512)ConditionalGateway identifier configured in a FlexPay Payment Gateway. Typically the Merchant Account Reference Id is the same value as a Merchant Account ID in order to facilitate reconciliation.
PaymentMethodGatewayPaymentMethodIdString (256)ConditionalThis is the payment token stored at the payment gateway.  This is required if the full credit card number is not provided.
PaymentMethodGatewayTransactionIdString (50)ConditionalCertain gateways use a transaction ID to represent a payment method (for example: NMI).
PaymentMethodFirstSixDigitsString (6)OptionalThe first six digits of the customers credit card.  This is used to determine strategies within our machine learning system.
PaymentMethodLastFourDigitsString (4)OptionalThe last four digits of the customers credit card.  This is used to determine strategies within our machine learning system.
DelayedDateDateTimeOptionalWhen this value is set, we will process the transaction at the given time
gatewaySpecificFieldsJSONOptionalJSON object containing the gateway specific fields. See our documentation for your particular gateway. If not providing any info, please add empty brackets in double quotes "{}"

Downloading Your Output File

If your file fails the validation stage, it will not be processed and our support team will contact you.

When it comes to the generation of the resulting output files, there are two different options available to you, please discuss with your CSM and they will configure it according to your needs. When a transaction is processed, the result of that transaction will only ever appear in one output file, so it's important you understand the process.

  • Option 1: Get up to two output files per day for every input file. If your file is processed successfully, FlexPay will create a corresponding output file and make it available every day at 15:00 UTC and 22:00 UTC for download from your designated Output folder. For example, if a transaction is scheduled to retry (and is processed) at 14:00 UTC, it will appear in the output file at 15:00 UTC but not 22:00 UTC. This means that you'll need to ingest both output files in order to get the full list of what was processed.
  • Option 2: Get one output file per day for all transactions processed the day before. It doesn't matter if the system processed transactions from 10 different input files, you will always have 1 output file a day containing the results of all of them. The file will be made available to you at 15:00 UTC.

Output File Format

The output file generated by FlexPay will contain the transaction results of all the transactions included in your input file. The file format is comma-delimited, with a txt extension, and no headers. The name format will depend on how many output files you're receiving per day (as described above). With Option 1, the name will match that of your input file with an underscore (_) and a time stamp. With Option 2, the name will stick to the following format <companycode>-3-yyyyMMdd.txt (date represents the day transactions were processed). See an output file template attached to this article.

► Click to view all fields
FieldTypeDescription
merchantTransactionId String (50)This data is typically used to reference transactions on the host systems. This information is to be stored by the merchant.
transactionStatusIntegerIndicates the result of the transaction: 1 = Approved, 2 = Declined, 3 = Error
responseCodeString (6) FlexPay's Transaction Response Code
messageString (500) FlexPay's Transaction Response Message
transactionIdString (50)FlexPay's transaction identifier
referenceTransactionIdString (50)FlexPay's identifier of a transaction previously charged/authorized/captured. 
transactionDateDateTimeTimestamp from the moment the transaction was processed. ISO 8601
avsCodeString (1) Indicates the address verification result code
avsMessageString (250) Indicates the address verification result message
cvvCodeString (15)Indicates the CVV verification result code
cvvMessageString (250) Indicates the CVV verification result message
errorCodeString (15)Indicates the gateway response code
errorDetailString (250)Indicates the gateway response message
currencyCodeString (3) Three-character currency code (e.g. USD, CAD). ISO 4217
amountIntegerAmount in cents (e.g. 1957 is equivalent to 19.57)
gatewayTokenString (50)This field is FlexPay's gateway identifier associated with a merchant account against which the request is made.
gatewayTypeString (50) Code to identify on which gateway the transaction has been attempted (e.g. worldpay_litle)
gatewayTransactionIdString (50) Transaction ID returned by the gateway
merchantAccountReferenceIdString (50) Reference ID tied to the merchant account used for the transaction
customerIdString (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.
assignedGatewayTokenString (50)This field is FlexPay's gateway identifier associated with a merchant account against which the request will be made on a next attempt.
orderIdString (50)Return the merchant-assigned order identification number from the request.
transactionTypeString (15) This field indicates the type of transaction: CHARGE, AUTHORIZE, CAPTURE, REFUND, VOID or REDACTPAYMENTMETHOD 
creditCardNumberString (22)This field is the masked card number you are charging for this transaction. (Example: 451112******4259). It will be blank if a different payment method was used or if transaction type is Capture, Refund or Void
referenceDataString (512) Reference data generated by FlexPay. This value is sent back in the next retry transaction for the same payment.
retryDateDateTimeIndicates the date and time when the transaction will be retried (UTC)
retryCountIntegerThe number of retries of the billing cycle. The initial attempt is 0 and all other retries will increase the count by 1.
dateFirstAttemptDateTimeThe field contains the date of the first transaction attempt for this billing cycle. Date Format Iso 8601 and is UTC
customVariable1String (50)Optional user defined string value.
customVariable2String (50)Optional user defined string value.
customVariable3String (50)Optional user defined string value.
customVariable4String (50)Optional user defined string value.
customVariable5String (50)Optional user defined string value.
PaymentMethodIdString (22)FlexPay vault token
PaymentMethodStorageStateString (50)Storage status of the payment method
PaymentMethodMerchantAccountReferenceIdString (512)Merchant account linked to the payment method
PaymentMethodTypeString (50)The type of payment method
gatewaySpecificResponseFieldsString (512)JSON payload containing the gateway specific response fields. NOTE: this is only included if the gateway supports it and if the JSON column was included in the Input file.

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.

D
Daniel is the author of this solution article.

Did you find it helpful? Yes No

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