FlexPay HomeTrust CenterStatus
Documentation
Contact Support

Engaged Recovery

Suggest Edits

Introduction

The purpose of this document is to provide the technical details required to support the FlexPay's Engaged Recovery process. Engaged Recovery is a payment recovery solution that uses behavioral science to enhance automated customer outreach. Learn more about this feature here: https://flexpay.io/products/engaged-recovery/

Requirements

To integrate into the Engaged Recovery process using FlexPay’s API, 3 elements need to be supported:

  • Updates to the existing Invisible Recovery integration (new fields & requirements).
  • A new transaction type to let FlexPay know about successful payments that haven't been processed through FlexPay.
  • A new Engaged Recovery API that lets you Update customer information or complete the campaign.

Process Flow

  1. When Invisible Recovery determines a payment is unrecoverable, the Engaged Recovery (ER) campaign is triggered. A retry date, typically 40 days later (depending on configuration), is provided to the CRM along with the response.
  2. The ER campaign initiates with automated email and SMS outreach to the customer.
  3. The customer follows the instructions in the outreach messages to update their payment information in the CRM.
  4. The CRM processes the payment directly through the gateway and updates the subscription status.
  5. The CRM notifies FlexPay of the successful recovery.
  6. FlexPay updates the transaction record and closes the outreach campaign.
  7. A final message is sent to the customer, thanking them for their payment.
  8. If the payment information is not updated throughout the campaign, the CRM retries the payment according to the schedule provided in Step 1.
  9. FlexPay's response confirms that the recovery campaign was unsuccessful.

Integration Outcomes

An integration to support Engaged Recovery will allow you to perform the following:

  • Send transactions that will qualify for Engaged Recovery.
  • Update customer information.
  • Complete the Engaged Recovery process for a specific customer.
  • Inform FlexPay of customers recovered due to the Engaged Recovery process.

Invisible Recovery API

The Invisible Recovery API has been enhanced to support Engaged Recovery. The enhancements apply to the Charge, Authorize, Capture and Successful Payment endpoints.

Charge Request

The following existing fields are now required for Engaged Recovery:

  • firstName
  • lastName
  • email (if sending email outreaches)
  • phoneNumber (if sending SMS outreaches)
  • firstSixDigits
  • lastFourDigits
  • dateFirstAttempt

The following are new fields that have been added to the Charge call and must be provided for ER:

  • customerAccountNumber: The value for this field will be displayed in the customer outreach. It should be something that your customers will recognize.
  • disableSmsNotification: Customer needs to opt-in for at least one contact method (sms and/or email) for Engaged Recovery to work. They are considered to be opt-in by default (if phone number/email provided) unless specified otherwise.
  • disableEmailNotification Customer needs to opt-in for at least one contact method (sms and/or email) for Engaged Recovery to work. They are considered to be opt-in by default (if phone number/email provided) unless specified otherwise.
  • customerPastDueBalance: This field is used to provide FlexPay with the total outstanding balance owed by a customer. For example, this could be the total of several failed payments for a single

All fields are described in detail in the API reference section. You can find them here.

Here's an example of a Charge request that will a qualify a payment for Engaged Recovery.

{
    "transaction": {
        "merchantTransactionId": "ER-Test-0089",
        "orderId": "order-0089",
        "customerId": "CID-487297",
        "currencyCode": "USD",
        "amount": 1000,
        "paymentMethod": {
            "creditCardNumber": "4000000000000069",
            "expiryMonth": "04",
            "expiryYear": "2026",
            "cvv": "",
            "firstSixDigits": "400000",
            "lastFourDigits": "0069",
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "",
            "address1": "111 Cool Avenue",
            "address2": "",
            "postalCode": "H5R8Y5",
            "city": "Montreal",
            "state": "QC",
            "country": "CA",
            "email": "[email protected]",
            "phoneNumber": "5145555555",
            "merchantAccountReferenceId": "3699852"
        },
        "customerIp": "127.0.0.1",
        "retryCount": 1,
        "dateFirstAttempt": "2023-07-01T00:00:00",
        "referenceData": null,
        "customerAccountNumber": "CID-487297",
        "disableSmsNotification":"false",
        "disableEmailNotification": "false",
        "customerPastDueBalance": 1000
    }
}

{
    "transaction": {
        "response": {
            "avsCode": null,
            "avsMessage": null,
            "cvvCode": null,
            "cvvMessage": null,
            "errorCode": "expired_card",
            "errorDetail": "Your card has expired."
        },
        "engagedRecoveryState": 1,
        "paymentMethod": {
            "paymentMethodId": "QYPYZYF42QPUDCKSAGIVH2RL7E",
            "creditCardNumber": "400000******0069",
            "expiryMonth": "04",
            "expiryYear": "2026",
            "cvv": "",
            "firstName": "John",
            "lastName": "Doe",
            "fullName": "John Doe",
            "customerId": "CID-487297",
            "address1": "111 Cool Avenue",
            "address2": "",
            "postalCode": "H5R8Y5",
            "city": "Montreal",
            "state": "QC",
            "country": "CA",
            "email": "[email protected]",
            "phoneNumber": "5145555555",
            "paymentMethodType": "CreditCard",
            "fingerprint": null,
            "lastFourDigits": "0069",
            "firstSixDigits": "400000",
            "cardType": "VISA",
            "dateCreated": "2024-08-15T02:42:21.305Z",
            "storageState": "Cached",
            "merchantAccountReferenceId": "3699852"
        },
        "transactionId": "068N7THBHG0000E000224KH390EKY",
        "transactionDate": "2024-08-15T02:42:21.196Z",
        "transactionStatus": 2,
        "message": "RETRY - Expired card.",
        "responseCode": "20080",
        "transactionType": "Charge",
        "merchantTransactionId": "ER-Test-0089",
        "customerId": "CID-487297",
        "currencyCode": "USD",
        "amount": 1000,
        "gatewayToken": "XIRREJG3GQCENOT5AGDVFLX5OU",
        "gatewayType": "stripe_connect",
        "gatewayTransactionId": "ch_3PntdqKL6olVrTWK1TiFrmib",
        "merchantAccountReferenceId": "3699852",
        "assignedGatewayToken": "XIRREJG3GQCENOT5AGDVFLX5OU",
        "orderId": "order-0089",
        "retryDate": "2024-08-17T18:00:00Z",
        "retryCount": 1,
        "dateFirstAttempt": "2023-07-01T00:00:00Z",
        "description": null,
        "productSku": null,
        "subscriptionId": null,
        "productCategory": null,
        "billingPlan": null,
        "customerIp": "127.0.0.1",
        "billingCycle": 1,
        "shippingAddress": {
            "address1": null,
            "address2": null,
            "postalCode": null,
            "city": null,
            "state": null,
            "country": null
        },
        "referenceData": "AAABAADA/hzGedsIAAAAAAAAAAAAAAAAAAAAACJOI0gdP8ABAAABkVPqK4w=",
        "disableCustomerRecovery": false,
        "customVariable1": null,
        "customVariable2": null,
        "customVariable3": null,
        "customVariable4": null,
        "customVariable5": null
    }
}

Successful Payment

Successful Payment is a new transaction type that can be sent via the Invisible Recovery API to notify FlexPay regarding the successful payment from the customer in engaged recovery and to stop the engaged recovery outreach.

Transactions sent to this endpoint can contain the same fields that are sent in the Charge endpoint with the exception that Payment Method information can be blank.

Method: POST

URL: https://api.flexpay.io/v1/gateways/successfulpayment

All details about the Successful Payment Endpoint can be found here

Engaged Recovery API

The Engaged Recovery API will allow our integration partners to update the customer details (e.g. phone, email, opt-in/opt-out) as well as request to complete the campaign following a subscription cancellation. Authentication is handled using the same API key that is used for the Transaction API.

Upsert Customer

It allows for customer details to be updated (e.g. phone, email, disable sms notifications)

Method: POST

URL: https://er.flexpay.io/v1/customers

All details about the upset customer endpoint can be found here.

Example request:

{
  "customerId": "UAT_7000025",
  "disableSmsNotification": true,
  "disableEmailNotification": false,
  "contactInformation": {
    "fullName": "John Doe",
    "cellPhone": null,
    "email": "[email protected]"
  }
}

Complete campaign

Alows to complete a campaign following a subscription cancellation.

Method: POST

URL: https://er.flexpay.io/v1/customers/complete-campaign/

All details about the complete campaign Endpoint can be found here.

Example request:

{
  "customerId": "54298799-04",
  "exitReason": "SubscriptionCancelled"
}

Updated about 1 month ago