Introduction
The purpose of this guide is to provide the resources and test scenarios necessary for successful integration with the FlexPay API.
Documentation
FlexPay API reference can be found at https://docs.flexpay.io/
Refer to our Sandbox Guide for a list of test cards and methods to trigger the response codes required in the scenarios described below.
The FlexPay client portal is at https://client.flexpay.io/
The account credentials and Sandbox API key will be sent in another document by a member of the integrations team.
Authorization
By default, one API Key is generated for each account and must be configured on your side. FlexPay allows creating additional keys for an account in case a customer is running multiple companies in the same account and would like to group their payment gateway and have the ability to group reporting to a specific company as well.
Test Scenarios
Be sure to create at least one test transaction for each scenario outlined below. The transactions will be reviewed by the integrations team and are required for the approval of an integration. Please record the transaction tokens for each of the corresponding scenarios in the table in Appendix A.
Important Points
- There are 2 important fields required for the FlexPay payment logic to function as intended: retryCount and referenceData.
- When the initial transaction is processed directly on the gateway (i.e. not through FlexPay), the retryCount begins at 0. If it declines, the transaction is sent to FlexPay the next day with a retry count of 1. Another way of thinking about it is that the initial attempt is not a retry and retry 1 = the first retry. The retry count increases with each subsequent transaction until it is approved or receives a hard decline, at which point the count is reset.
- The reference data is provided in the response from FlexPay. Reference data is stored and then returned (daisy-chained) in the next transaction until it is approved or receives a hard decline, at which point the field is emptied (null). NOTE: Reference data is stored at the transaction level and not the customer level.
- The merchant Transaction ID is unique: This value is coming from the Integration Point and is used to reconcile each transaction.
- Multiple currencies are supported: If a Client is using different currencies, please test at least 2 of them.
- The Retry Date (for both soft & hard declines) must be handled properly: a transaction without a retry date should NOT be retried.
- Do not retry a transaction before the given date & time.
Transaction API Scenarios
Step 1: Schedule a Soft Decline
Sending a transaction with an expected response code in the 20K range will return a retry date & time as well as the reference data field. The retry date must be used to schedule the next transaction at the given Date and Time (UTC).
Step 2: Do Not Schedule Hard Decline
Sending a transaction with an expected response code in the 30K, 40K, and 50K range will not return a retry date. These transactions should not be scheduled to retry automatically later.
Step 3: Recover a Transaction
Use the appropriate test cards & amount to send an approved charge with a retryCount equal or higher than 1.
Step 4: Validate the Payment Logic Using Reference Data & Retry Count
Simulate a string of transactions attempting to salvage a customer’s order/invoice.
Transaction 1: Send a request that will produce a soft decline, where retryCount = 0, and referenceData is empty
Transaction 2: Send a request that will produce a soft decline, where retryCount = 1, and referenceData is equal to the output referenceData in the response from Transaction 1
Transaction 3: Send a request that will produce a soft decline, where retryCount = 2, and referenceData is equal to the output referenceData in the response from Transaction 2
Step 5: Refund a Recovered Transaction
If FlexPay recovers a transaction that is subsequently refunded, we will credit any fees related to that transaction on your FlexPay invoice. In order to properly track refunded recoveries, you will need to process those refunds through FlexPay.
Transaction 1: Send an approved charge with a retryCount equal or higher than 1
Transaction 2: Send an approved refund using the FlexPay transaction token from Transaction 1
Gateway Management API Scenarios
The Gateway Management API is an ideal solution when there is a large number of MIDs to be created and maintained. Using this API not only saves time but helps eliminate the possibility of human error and ensures that credentials are always up-to-date. The goal of the Gateway Management API is to make sure that anything done to a Gateway or MID at the Integration Point is automatically reflected in the accompanying MID at FlexPay. This should also apply when an Integration Point adds a new Gateway to their list of offerings.
Step 6: Validate Automatic Gateway Creation
Enabling a gateway at the Integration Point will create a new gateway at FlexPay
Updating the credentials at the Integration Point will update an existing gateway at FlexPay
Disabling a gateway at the Integration Point will update an existing gateway at FlexPay and set its status to RefundOnly
Step 7: Process Transactions with Specified Gateways
Create 2 gateways
Send transaction to gateway #1 using the appropriate assignedGatewayToken
Send transaction to gateway #2 using the appropriate assignedGatewayToken