Payment Modes Version:V1 VS Version V2

This page documents the version:V1 schema for paymentModeConfig. Version:V1 is the original payment mode configuration schema and remains supported for merchants who integrated before version:V2 was introduced.

If you are starting a new integration, use version:V2. It provides finer control over card networks, variants, geography, UPI apps, instruments, and bank-level filtering. See Configure Payment Modes for the version:V2 reference.

Use Version:V1 config

You can use version:v1 in one of two ways.

• Omit the version field from paymentModeConfig entirely, or
• Set "version": "V1" explicitly

Both produce identical behaviour. Version:V1 and version:V2 schemas are mutually exclusive and once you set "version": "V2", all constraint objects must follow the version:V2 schema.

Request Body Structure

paymentModeConfig is nested inside paymentFlow. It is not a top-level field.

{
  "merchantOrderId": "ORDER_123",
  "amount": 1000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "enabledPaymentModes": [
        { "type": "UPI_INTENT" },
        { "type": "UPI_QR" },
        { "type": "CARD", "cardTypes": ["CREDIT_CARD", "DEBIT_CARD"] }
      ]
    }
  }
}

Note: The version field is omitted above. You may also set "version": "V1" explicitly, both are equivalent.

paymentModeConfig Fields

Payment Mode Constraint Object (version:V1)

Each element in enabledPaymentModes or disabledPaymentModes is a constraint object identified by its type field.

Important: version:V1 type values are different from version:V2. UPI is split into three separate types (UPI_INTENT, UPI_QR, UPI_COLLECT) rather than a single UPI type with a flows field. Using version:V2 type values (such as "UPI") in a version:V1 request will not work.

UPI_INTENT

Controls UPI intent flow, the flow where the customer is redirected to a UPI app on their device.

Note: version:V1 does not support filtering by UPI app or instrument. To restrict by app or instrument, migrate to version:V2 and use type: "UPI" with apps and instruments fields.

Example

{
  "merchantOrderId": "ORDER_123",
  "amount": 50000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "enabledPaymentModes": [
        { "type": "UPI_INTENT" }
      ]
    }
  }
}

UPI_QR

Controls UPI QR code flow, the flow where a QR code is shown on screen for the customer to scan with any UPI app.

Example

{
  "merchantOrderId": "ORDER_123",
  "amount": 50000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "enabledPaymentModes": [
        { "type": "UPI_QR" }
      ]
    }
  }
}

UPI_COLLECT

Controls UPI collect flow, the flow where the customer enters their UPI ID (VPA) and receives a collect request in their UPI app.

Example

{
  "merchantOrderId": "ORDER_123",
  "amount": 50000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "enabledPaymentModes": [
        { "type": "UPI_COLLECT" }
      ]
    }
  }
}

CARD

Controls card payments. Version:V1 supports filtering by card type (credit or debit) using the cardTypes field.

Note: Version:V1 does not support filtering by card network, variant, or geography. To filter by network (Visa, Mastercard, RuPay…), variant (consumer, corporate…), or geography (domestic, international), migrate to version:V2 and use type: "CARD" with networks, variants, and geoScopes fields.

Example: Allow credit cards only

{
  "merchantOrderId": "ORDER_123",
  "amount": 50000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "enabledPaymentModes": [
        {
          "type": "CARD",
          "cardTypes": ["CREDIT_CARD"]
        }
      ]
    }
  }
}

Example: Allow all card types

{
  "merchantOrderId": "ORDER_123",
  "amount": 50000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "enabledPaymentModes": [
        {
          "type": "CARD"
        }
      ]
    }
  }
}

NET_BANKING

Controls retail net banking payments. Version:V1 does not support bank-level filtering, you can only enable or disable net banking as a whole.

Note: Version:V1 does not support filtering by specific banks. To restrict net banking to a list of banks (for example, HDFC and ICICI only), migrate to version:V2 and use type: "NET_BANKING" with the banks field.

Example: Enable net banking

{
  "merchantOrderId": "ORDER_123",
  "amount": 50000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "enabledPaymentModes": [
        { "type": "NET_BANKING" }
      ]
    }
  }
}

Example: Disable net banking

{
  "merchantOrderId": "ORDER_123",
  "amount": 50000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "disabledPaymentModes": [
        { "type": "NET_BANKING" }
      ]
    }
  }
}

version:V1 Limitations

Version:V1 provides coarse-grained, method-level control only. The following capabilities are not available in version:V1:

Migrating to Version:V2

To migrate from version:V1 to version:V2:

1. Add "version": "V2" inside your paymentModeConfig object.
2. Replace version:V1 type values with their version:V2 equivalents:

3. Remove the cardTypes field and replace with types for the CARD constraint.
4. Test your integration to confirm behavior is as expected.

Important: Do not mix version:V1 and version:V2 type values in the same request. Once "version": "V2" is set, type values such as UPI_INTENT, UPI_QR, and UPI_COLLECT are not recognized.

What’s Next?

Head over to the next section to understand the complete reference of all accepted values for payment mode configuration fields.