> ## Documentation Index
> Fetch the complete documentation index at: https://fastflowpe.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Subscription

> Use this POST endpoint to initialize a recurring subscription and create the customer mandate authorization flow.

Use the API key in the `x-api-key` header. Do not send it in the `Authorization` header, and cookies are not required.

<Tip>
  **Quick Reference**

  **Required:** Customer information, plan details, and first charge time

  **Returns:** `subscription_id`, `merchant_ref_id`, `auth_data`

  **Payment Mode:** `UPI_RECURRING`
</Tip>

## Endpoint Details

| Field | Value |
| - | - |
| Method | `POST` |
| Payload | `JSON` |
| URL | `https://api.fastflowpe.com/merchant/recurring/subscription/initialize` |

## Request Headers

<ParamField header="x-api-key" type="string" required>
  Your secret API key issued by FastFlowPe.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="Accept" type="string" required>
  Must be `application/json`.
</ParamField>

## Request Body

### Customer Information

<ParamField body="customer_info.merchant_ref_id" type="string" required>
  Your unique reference ID for the subscription. This value must not have been used previously.
</ParamField>

<ParamField body="customer_info.name" type="string" required>
  Customer's full name.
</ParamField>

<ParamField body="customer_info.email" type="string" required>
  Customer's email address.
</ParamField>

<ParamField body="customer_info.phone" type="string" required>
  Customer's phone number.
</ParamField>

<ParamField body="customer_info.payment_mode" type="string" required>
  Payment mode used for the subscription. For recurring UPI mandates, use `UPI_RECURRING`.
</ParamField>

<ParamField body="customer_info.upi_id" type="string">
  Customer's UPI ID or VPA.

  This field is not mandatory.
</ParamField>

<ParamField body="customer_info.authorization_amount" type="float" required>
  Amount authorized while setting up the mandate. It cannot exceed `plan_amount`.
</ParamField>

### Plan Details

<ParamField body="plan_details.plan_name" type="string" required>
  Display name of the subscription plan.
</ParamField>

<ParamField body="plan_details.plan_type" type="string" required>
  Type of subscription plan.

  Supported values:

  * `PERIODIC` — charges are scheduled automatically based on the configured interval.
  * `ON_DEMAND` — charges can be initiated when required.
</ParamField>

<ParamField body="plan_details.plan_amount" type="float" required>
  Amount charged during each billing cycle.
</ParamField>

<ParamField body="plan_details.plan_max_amount" type="float" required>
  Maximum amount permitted for a charge under this subscription. It must be greater than or equal to `plan_amount`.
</ParamField>

<ParamField body="plan_details.plan_max_cycles" type="integer" required>
  Maximum number of billing cycles allowed for the subscription.
</ParamField>

<ParamField body="plan_details.plan_intervals" type="integer" required>
  Number of interval units between recurring charges.
</ParamField>

<ParamField body="plan_details.plan_interval_type" type="string" required>
  Interval unit used for recurring charges.

  Supported values:

  * `DAILY`
  * `WEEKLY`
  * `MONTHLY`
  * `YEARLY`

  For example, `plan_intervals: 1` with `plan_interval_type: DAILY` means the subscription is charged once every day.
</ParamField>

### Subscription Metadata

<ParamField body="subscription_meta.subscription_first_charge_time" type="string" required>
  First scheduled charge time in ISO 8601 format.

  Example: `2026-10-07T00:00:00+05:30`
</ParamField>

<Note>
  `subscription_expiry_time` is calculated automatically by FastFlowPe.

  Authorization details are also created internally using `customer_info.authorization_amount`.
</Note>

## Request Example

<RequestExample>
  ```bash cURL theme={"dark"}
  curl --location 'https://api.fastflowpe.com/merchant/recurring/subscription/initialize' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'x-api-key: YOUR_MERCHANT_X_API_KEY' \
    --data-raw '{
      "customer_info": {
        "merchant_ref_id": "SUB-JONSNOW-001",
        "name": "Jon Snow",
        "email": "jonsnow@example.com",
        "phone": "9876543210",
        "payment_mode": "UPI_RECURRING",
        "upi_id": "9876543210@ptsbi",
        "authorization_amount": 2
      },
      "plan_details": {
        "plan_name": "test-plan",
        "plan_type": "PERIODIC",
        "plan_amount": 100,
        "plan_max_amount": 100,
        "plan_max_cycles": 6,
        "plan_intervals": 1,
        "plan_interval_type": "DAILY"
      },
      "subscription_meta": {
        "subscription_first_charge_time": "2026-10-07T00:00:00+05:30"
      }
    }'
  ```
</RequestExample>

## Response

A successful request returns a `200` status with the FastFlowPe subscription ID, merchant reference ID, and authorization information required to complete the mandate.

<ResponseExample>
  ```json Success theme={"dark"}
  {
    "status": "success",
    "status_code": 200,
    "message": "Subscription created. Redirect customer to complete mandate authorization.",
    "detail": null,
    "data": {
      "subscription_id": "YOUR_INTERNAL_SUBSCRIPTION_UUID",
      "merchant_ref_id": "SUB-JONSNOW-001",
      "auth_data": {
        "url": "https://payments.cashfree.com/subscriptions/checkout/timer",
        "method": "post",
        "payload": {
          "paymentType": "UPI",
          "upiIntentData": {
            "iosAuthAppLinks": {
              "BHIM": "bhim://...",
              "GPAY": "tez://...",
              "PHONEPE": "phonepe://..."
            },
            "androidAuthAppLinks": {
              "BHIM": "bhim://...",
              "GPAY": "gpay://...",
              "PHONEPE": "phonepe://...",
              "DEFAULT": "upi://..."
            }
          }
        },
        "content_type": "application/json"
      }
    },
    "meta": null
  }
  ```

  ```json Failure theme={"dark"}
  {
    "status": "failure",
    "status_code": 400,
    "message": "Subscription creation failed",
    "detail": null,
    "data": {
      "subscription_id": "INTERNAL_SUBSCRIPTION_ID",
      "error_message": "Error returned by PSP",
      "raw_response": {}
    },
    "meta": null
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="subscription_id" type="string">
  Unique FastFlowPe subscription ID created for this subscription.

  Save this value for future subscription operations.
</ResponseField>

<ResponseField name="merchant_ref_id" type="string">
  Merchant reference ID originally provided in `customer_info.merchant_ref_id`.

  Use this value to map the FastFlowPe subscription to your internal subscription record.
</ResponseField>

<ResponseField name="auth_data" type="object">
  Authorization information required for the customer to complete the recurring mandate setup.
</ResponseField>

<ResponseField name="auth_data.url" type="string">
  URL used as part of the mandate authorization flow.
</ResponseField>

<ResponseField name="auth_data.method" type="string">
  HTTP method associated with the authorization request.
</ResponseField>

<ResponseField name="auth_data.payload" type="object">
  Payment authorization payload containing UPI authorization information.
</ResponseField>

<ResponseField name="auth_data.payload.paymentType" type="string">
  Payment type used for mandate authorization. For UPI recurring subscriptions, this is `UPI`.
</ResponseField>

<ResponseField name="auth_data.payload.upiIntentData" type="object">
  Contains platform-specific UPI application links that can be used to complete mandate authorization.
</ResponseField>

<ResponseField name="auth_data.payload.upiIntentData.iosAuthAppLinks" type="object">
  UPI application deep links returned for supported iOS apps such as BHIM, Google Pay, and PhonePe.
</ResponseField>

<ResponseField name="auth_data.payload.upiIntentData.androidAuthAppLinks" type="object">
  UPI application deep links returned for supported Android apps.

  A generic `DEFAULT` UPI link may also be returned.
</ResponseField>

<ResponseField name="auth_data.content_type" type="string">
  Content type of the authorization payload. Typically `application/json`.
</ResponseField>

<ResponseField name="error_message" type="string">
  Error message returned when the subscription could not be created.

  This field is present in failure responses.
</ResponseField>

<ResponseField name="raw_response" type="object">
  Raw response returned by the PSP when subscription creation fails.
</ResponseField>

<Note>
  Creating the subscription does not mean that the mandate has been authorized.

  The customer must complete the mandate authorization using the information returned in `auth_data`.
</Note>

<Tip>
  Save both `subscription_id` and `merchant_ref_id`. Use `subscription_id` for FastFlowPe subscription operations and `merchant_ref_id` to correlate the subscription with your own records.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.