Introduction

This guide is for existing Revaly (formerly FlexPay) merchants currently using API v1.0 who need to migrate to the new Revaly API v2.0.

Its purpose is to clearly define:

• What has changed between v1 and v2
• What remains compatible
• What Revaly expects from your system during the transition
• Which elements of the migration are required
• Which decisions depend on your architecture and rollout strategy

This guide does not prescribe how your CRM or billing system must be structured. Every merchant operates a unique platform, and you decide how to implement version selection, routing, or rollout controls.

Instead, this document describes the functional behaviors and data requirements Revaly relies on so the migration can be completed safely, predictably, and without interruption to ongoing payment flows.

👍

You will work directly with a Revaly Implementation Manager throughout your migration. They will help clarify requirements, review your payloads, support testing, and guide you through a smooth transition to the new API.

Why Migrate

Revaly API v2.0 is more than an update to the legacy v1 integration. It provides the foundation for the full capabilities of the Revaly Payment Performance Platform, enabling higher approval rates, more advanced optimization, and improved long-term maintainability. Migrating to v2 enables:

Initial Rebill Optimization: In v2, you can route the initial rebill attempt through Revaly, not just failed-payment recovery. This allows Revaly to optimize the payment before it reaches the gateway, improving approval outcomes from the very first attempt.

Enhanced Context and Treatments: The v2 model includes expanded fields and improved data structures that allow Revaly to apply more precise decisioning and optimization techniques.

A Modernized, Consistent API Model: Cleaner request/response structures reduce implementation complexity and make long-term maintenance easier.

Future Platform Capabilities: v2 establishes the baseline needed for upcoming enhancements to Revaly’s optimization engine and platform modules.

Migration Requirements and Expectations

The migration itself is straightforward: your system must send requests using the new v2 payload structure, include a v2 API key in the request headers, and call the v2 base URL and endpoints. That is the core of the migration.

Beyond that, your must decide how v2 should be introduced into your existing payment flows. Every merchant operates a unique CRM or billing system, and only you know how rebills, retries, and routing logic are structured internally.

As you plan your rollout, you will need to determine how v2 fits into your current workflows: for example, how to transition from v1 recovery flows, how to introduce v2 to portions of your traffic, and whether to adopt initial-attempt optimization from the start.

The following subsections outline:

• The required changes you must implement
• The rollout decisions you will need to make based on your system design and strategy

Required Changes

These items are required for a functional v2 integration:

• Use the v2 API specification: All requests must follow the v2 payload structure and field definitions. API Reference
• Use a Revaly v2 API key: Legacy (v1) API keys cannot be used with v2. How to create an API Key
• Use the v2 base URL and endpoints: All traffic handled by v2 must be sent to the new endpoints.

These are the only items that are strictly required to begin using API v2.

Rollout Decisions

These decisions depend entirely on how your system is structured and how you prefer to adopt v2. They determine how the migration behaves, not whether the migration works.

At a high level, you must choose:

• How to handle payments already in recovery
• Whether v2 is enabled globally or for a subset of traffic
• Whether to begin with failed-payment recovery only or also include the initial rebill attempt

📘

Note: For Enterprise with Scheduler integrations, recovery attempts are fully managed by Revaly. As a result, the decision to migrate payments already in recovery is not applicable.

With that distinction in mind, let’s explore each decision path.

1. Handling Payments Currently in Recovery

When adopting v2, you must decide how to handle payments that are already in recovery at the moment you switch. You have two options:

• Migrate payments currently being recovered and allow v2 to continue the remaining retry attempts, or
• Send only newly failed rebill payments to v2, allowing any existing v1 recovery sequences to finish where they started

Both approaches are fully supported. The decision depends on how you prefer to manage continuity during rollout.

2. Enabling v2 for a Subset of Traffic

Some merchants prefer to roll out v2 gradually instead of enabling it for all payments at once. If your platform allows you to route traffic by gateway, MID, product, or any other internal segment, you may choose to enable v2 only for a portion of your traffic during the initial rollout.

This approach lets you validate behavior on a controlled subset before expanding to the rest of your traffic. If your system does not support partial enablement and can only route payments globally, that is completely acceptable.

3. Recovery Only vs. Including the Initial Rebill Attempt

Revaly v2 can optimize both the initial rebill attempt and any subsequent failed-payment recovery, whereas v1 focused only recovery.

Because updating the initial payment flow can require deeper architectural work, many merchants prefer to adopt v2 in stages. The migration fully supports this.

Phase 1: Failed Payment Recovery Only (Matches Your v1 Behavior)

You can begin by sending only failed payments to v2. This keeps your existing initial-rebill flow unchanged while allowing you to validate the new API in a low-risk way.

• Initial rebills attempt continues to go directly to your gateway
• Only failed payments are routed to Revaly v2 for recovery
• This mirrors your current v1 integration

Phase 2: Initial Rebill Optimization + Failed Payment Recovery

Once you are confident in your v2 rollout, you can start sending the initial rebill attempt to Revaly as well. This enables Revaly to optimize the first attempt before the transaction reaches the gateway, unlocking the full approval improvements available in v2.

In this phase:

• The initial rebill attempt is optimized by Revaly
• All subsequent recovery attempts continue seamlessly
• You benefit from the full optimization engine, not just recovery workflows

Base URLs and Credentials

Before enabling API v2, you must update both the base URL you call and the credentials your system uses for authentication.

v1 and v2 run on separate endpoints and require different API keys, so your platform must store and send the correct version-specific configuration.

Endpoints

This table provides a quick reference of how the main v1 operations translate to v2. Use it to identify the new endpoints you will call once your integration begins sending requests to API v2.

Payload Examples (v1 -> v2)

The examples below show a simplified v1 MIT credit-card request next to its v2 equivalent. They illustrate some of the structural changes you will see during migration, including:

• The expanded paymentMethod model
• Consolidated billing and card details
• The explicit recovery object (retry fields)
• Renamed fields such as paymentReferenceData
• Additional clarity around initiatedBy and paymentMethodType

These samples do not represent the full payload; they highlight some of the key differences you should be aware of when adapting your implementation.

    {
      "transaction": {
        "paymentMethod": {
          "creditCardNumber": "4242424242424242",
          "expiryMonth": "12",
          "expiryYear": "2025",
          "fullName": "John Doe",
          "address1": "123 Main Street",
          "postalCode": "10001",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "merchantAccountReferenceId": "SUPStripe",
          "email": "[email protected]"
        },
        "merchantTransactionId": "charge_order_12345",
        "orderId": "order_67890",
        "amount": 100,
        "currencyCode": "USD",
        "retryCount": 1,
        "dateFirstAttempt": "2025-01-10T08:00:00Z",
        "customerId": "customer_123456",
        "customerIp": "192.168.1.100",
        "referenceData": null,
        "mitStoredTransactionId": "mit_txn_001"
      }
    }

API Field Mapping

Use the following tables to update your payload builder from the FlexPay v1.0 structure to the Revaly API v2.0 structure.