Configure Payment Modes

Payment mode configuration allows you to control which payment methods, instruments, and flows are available to customers during checkout. These preferences are passed directly within the Create Payment API request body, with no need for any dashboard-level configuration. Since the configuration is applied at a transaction level, it provides granular, per-order control over the checkout experience.

Note: This page documents the V2 schema. If your integration was built prior to the introduction of V2 and your requests either omit the version field or specify it as V1, please refer to the V1 documentation. V2 offers enhanced flexibility and finer control, and is recommended for all new integrations.

Request

paymentModeConfig is nested inside paymentFlow.

{
  "merchantOrderId": "ORDER_123",
  "amount": 1000,
  "paymentFlow": {
    "type": "PG_CHECKOUT",
    "merchantUrls": {
      "redirectUrl": "https://www.yoursite.com/callback"
    },
    "paymentModeConfig": {
      "version": "V2",
      "enabledPaymentModes": [
        { "type": "UPI", "flows": ["INTENT"], "apps": ["phonepe", "gpay"] },
        { "type": "CARD", "types": ["CREDIT_CARD"], "networks": ["VISA", "MASTER_CARD"] },
        { "type": "NET_BANKING", "banks": ["HDFC", "ICIC", "SBIN"] }
      ]
    }
  }
}

Payment Mode Constraint Object

Each element in enabledPaymentModes or disabledPaymentModes is a constraint object. The type field identifies the payment mode; additional fields are dimension filters specific to that type.

UPI

CARD

NetBanking

Corporate NetBanking

EMI

Wallet

See the Payment Mode Reference for per-mode behavioral details and examples.

When to use this Configuration

V1 vs V2 Schema Comparison

V1 and V2 schemas are mutually exclusive. Once you set "version": "V2", all constraints must follow the V2 schema. V1 type values (like UPI_INTENT or UPI_QR) are completely ignored in V2.

How it works

enabledPaymentModes vs disabledPaymentModes

enabledPaymentModes: Only the methods and instruments matching your constraints will be shown to customers. All other payment options are suppressed.

disabledPaymentModes: The specified methods and instruments are hidden, and everything else remains available.

Important: You cannot use both enabledPaymentModes and disabledPaymentModes in the same request. Choose one approach per transaction.

Wildcard Behavior

Omitting a field from a constraint means “match all values for that dimension.” You only need to specify the dimensions you want to restrict.

{
  "type": "CARD",
  "types": ["CREDIT_CARD"]
}

This allows all credit cards regardless of network, variant, or geography, because networks, variants, and geoScopes are all omitted (wildcard).

Per-Transaction Scope

Payment mode configuration applies only to the specific Create Payment call in which it is passed. There is no persistent merchant-level configuration. Each order can have a different configuration.

Note: Only the first constraint for each type value is processed. If you include two objects with “type“: “UPI“, only the first one takes effect.

Example Payload

This example enables only GPay UPI intent payments and domestic Visa or Mastercard credit cards:

curl -X POST https://api.phonepe.com/apis/pg/checkout/v2/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: O-Bearer <token>" \
  -d '{
    "merchantOrderId": "ORDER_123",
    "amount": 50000,
    "paymentFlow": {
      "type": "PG_CHECKOUT",
      "merchantUrls": {
        "redirectUrl": "https://www.yoursite.com/callback"
      },
      "paymentModeConfig": {
        "version": "V2",
        "enabledPaymentModes": [
          {
            "type": "UPI",
            "flows": ["INTENT"],
            "apps": ["phonepe"]
          },
          {
            "type": "CARD",
            "types": ["CREDIT_CARD"],
            "networks": ["VISA", "MASTER_CARD"],
            "geoScopes": ["DOMESTIC"]
          }
        ]
      }
    }
  }'

Payload Breakdown:

• UPI: Shows only the PhonePe intent flow. Collect, QR, other apps, and UPI instruments like RuPay CC or Credit Line are hidden.
• Card: Shows only domestic Visa and Mastercard credit cards. Debit cards, international cards, other networks, and EMI are hidden.
• NetBanking: Not included in enabledPaymentModes, so it is hidden entirely.

What’s Next?

Head over to the next section to understand how to configure individual payment modes. Allow or block specific options by adding a constraint object inside paymentModeConfig.