TABLE OF CONTENTS
Introduction
The purpose of this document is to guide you through the necessary steps for integrating your CRM with FlexPay's failed payment recovery technology. With the Enterprise Integration, FlexPay serves as an intermediary layer between your system of record and the payment gateway, enhancing your retry attempts and providing real-time analysis to optimize transaction recovery.
Recognizing the complexity of integrations, we want to highlight two key adjustments to your CRM that will be essential for making this process successful.
- A scheduler: FlexPay will provide a retry date and time for recoverable transactions in our response. Your system needs to schedule and send the transaction at the recommended time.
- A modified routing logic: Direct retries through FlexPay rather than the gateway from your system of record. This change shouldn't impact rebills, only retries on failed payments.
Requirements
To benefit from FlexPay’s Enterprise API, you will need the following:
- FlexPay Production account
- At least one Company is configured in the account (There is a default company) Learn more
- Payment gateways are configured for each Company Learn more
- Production API keys for each Company Learn more
- Ability to POST a request to the Charge endpoint Learn more
- Ability to POST a request to the Refund endpoint Learn more
- Ability to POST a request to the Void endpoint Learn more
Process Flow
- A subscription rebill is sent directly to the gateway. It declines.
- It is then rerouted & scheduled to be sent through FlexPay.
- 24 hours after the initial rebill failure, a Charge is sent to FlexPay
- FlexPay reviews the transaction details and performs any data cleanup if it determines it will increase the likelihood of success. The transaction is sent directly from FlexPay to the Gateway.
- FlexPay analyses the response from the gateway and responds to the System or Record.
- The System of Record schedules the transaction and reattempts on the date and time provided by FlexPay.
The retry loop continues until one of the following events takes place:
- The transaction approves.
- The transaction hard declines.
- A configuration limit is reached. Maximum 15 retries or 30 days, whichever is reached first.
How-To
Before sending a transaction to FlexPay, a payment gateway must be configured under a Company. It must include the merchant account’s credentials so FlexPay can connect on your behalf. Depending on the complexity of your payment ecosystem, you could leverage the Gateway Management API. Learn more here.
Gateways can also be created manually in the FlexPay client portal. If you only have a small number of merchant accounts, this may be the easiest way to create the payment gateways in FlexPay. Learn more here.
The most common way of interacting with FlexPay's Enterprise API is through the Charge endpoint, this is how you provide details about a failed payment and kickstart the recovery process. FlexPay's AI-powered engine utilises this information to recommend the optimal timing for retrying the failed payment. This not only enhances the chances of approval but also assists in preserving a healthy merchant account. Refund and VOID endpoints are also available to you. Let's explore these items in more detail:
Charge
API reference: Charge Request
When the FlexPay API receives a Charge request, the transaction is processed directly at the gateway. The response code and message we receive, along with the the details you provided for the failed payment are analyzed, and a response is provided back to your CRM. You can expect this to take only a few hundred milliseconds more than your usual gateway transaction time. If we return a retry date, we expect you to schedule it on your CRM and send a new attempt at the provided date and time. If there is no retry date, the response dode and message will indicate the result.
Example:
POST https://api.flexpay.io/v1/gateways/charge
{
"transaction": {
"merchantTransactionId": "Trx-31649094",
"orderId": "ORD-0009452",
"description": "",
"customerId": "46209790216",
"currencyCode": "USD",
"amount": 1995,
"retainOnSuccess": false,
"paymentMethod": {
"creditCardNumber": "4111111111111111",
"lastFourDigits": "1111",
"firstSixDigits": "411111",
"expiryMonth": "05",
"expiryYear": "2025",
"firstName": "Carl",
"lastName": "johnson",
"fullName": "Carl Johson",
"address1": "560 Rue Peel",
"address2": "",
"postalCode": "J7Y3U9",
"city": "Montreal",
"state": "QC",
"country": "CA",
"email": "[email protected]",
"phoneNumber": "",
"merchantAccountReferenceId": "SUPCybersourceSandbox"
},
"customerIp": "10.10.10.10",
"dateFirstAttempt": "2024-02-15T19:20:30Z",
"referenceData": null,
"retryCount": 1,
"paymentPlan": {
"billingCycle": 7,
"subscriptionId": "sub_njcnm549dk8"
},
"references": {
"previousTransaction": {
"merchantAccountReferenceId": "Chase",
"gatewayCode": "89",
"gatewayMessage": "Credit Floor",
"avsCode": null,
"avsMessage": null,
"cvvCode": null,
"cvvMessage": null,
"transactionDate": "2024-02-15T19:20:30Z",
"transactionStatus": 2
}
}
}
}Refund
API reference: Refund
It can process partial and full refunds. You need to specify the amount in the body of the request. If there are time limitations imposed by a particular gateway (i.e. refunds only available for 120 days), they need to be accounted for by the CRM. Any refund request received by FlexPay will be sent directly to the your payment gateway.
Example:
POST https://api.flexpay.io/v1/transactions/066TAFW3A00000F10829KM8QVSPDM/refund
{
"transaction": {
"merchantTransactionId": "Ref-4592798278",
"disableCustomerRecovery": false,
"amount": 1995
}
}Void
API Reference: Void
It cancels an authorized transaction before it settles with the cardholder's bank.
Example:
POST https://api.flexpay.io/v1/transactions/066T7STFGW0000F1082ESKR7A0BJ4/void
{
"transaction": {
"merchantTransactionId": "V-56417687",
"disableCustomerRecovery": false
}
}Sandbox Testing
The FlexPay enablement team will typically create a “Sandbox” account for testing. This account has all the same functionality as a production account, so caution must be exercised when configuring the account. Within the test account, FlexPay has a Sandbox environment where you can test different scenarios and use cases.
The sandbox environment applies to Payment Gateways and API keys. Companies can have both Production and Sandbox API keys associated with them. When you create a Sandbox API Key, you will only be able to create & send requests to payment gateways in the Sandbox environment. Not all gateways are supported in the Sandbox. In the Sandbox Environment, there is a gateway called “FlexPay Sandbox”. This gateway must be used for the testing scenarios described below.
Please refer to the Sandbox User Guide for the amounts, test cards, and transaction types you need to trigger specific responses.
Requirements
The requirements for Sandbox testing are similar to those outlined previously in this guide, with two main differences. Instead of a regular FlexPay account, you need a FlexPay Test account, and instead of a regular payment gateway, you need a FlexPay Sandbox gateway. Please work closely with your integration manager to get these provisioned for you.
Use Cases
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.
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.
Enterprise API scenarios
Use Case 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).
Use Case 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.
Use Case 3: Recover a Transaction
Use the appropriate test cards & amount to send an approved charge with a retryCount equal or higher than 1.
Use Case 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
Use Case 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