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

# 1. Fetch and Enable Instruments

> Fetch a sub-merchant's payment methods and enable or disable an instrument using the Razorpay Method Management API.

Available in
🇮🇳 India

## 1.1 Fetch the Payment Methods

Call `GET …/payment_methods` to get one item per payment method, with its instruments inside. Add `method` to fetch one payment method:

| Query parameter | Returns |
| - | - |
| None | Every payment method, each with its instruments. |
| `?method=cod` | One payment method, with all its instruments. |

To refresh one instrument later, fetch its payment method. You cannot fetch a single instrument.

```bash Curl theme={null}
curl -X GET "https://api.razorpay.com/v3/accounts/acc_TcdGEzmfKQzEl1/products/payment_gateway/payment_methods?method=upi" \
-u rzp_live_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

Fetching always returns a collection, even for one payment method:

```json Response theme={null}
{
  "entity": "collection",
  "count": 1,
  "items": [
    {
      "method": "upi",
      "name": "UPI",
      "upi": {
        "payer_account_types": [
          {
            "payer_account_type": "bank_account",
            "name": "UPI from a bank account",
            "logo_url": null,
            "status": "activated",
            "status_reason": null,
            "enabled": false,
            "requirements": [],
            "estimated_activation_days": 14,
            "updated_at": 1794567010
          }
        ]
      }
    }
  ]
}
```

> [!NOTE]
>
> **Handy Tips**
>
> * Never hard-code the list of instruments. Fetch it, because Razorpay may add payment methods, instruments, statuses and reason codes. Ignore what you do not know.
> * The list is not paginated. An empty `items` array means Razorpay could not load the account. Retry.
> * Texts meant for people, such as `name` and `status_reason.description`, follow the `Accept-Language` header. Codes are never translated.

## 1.2 Name an Instrument

An instrument has no id of its own. To enable or disable it, name it in the request body by its place in the payment method's object: the list and the value a payment carries, or its own key.

| Method | Instrument | Example |
| - | - | - |
| `card` | Card network | `networks/visa` |
| `card` | Recurring or international cards | `recurring`, `international` |
| `netbanking` | Bank code | `banks/hdfc` |
| `upi` | Payer account type | `payer_account_types/bank_account` |
| `upi` | UPI Autopay | `autopay` |
| `wallet` | Wallet name | `wallets/amazonpay` |
| `emi` | Group, or a member of it | `debit_card`, `credit_card/banks/hdfc`, `cardless_emi/providers/flexmoney` |
| `cod` | Full or partial COD | `full`, `partial` |

## 1.3 Enable an Instrument

Call `PATCH …/payment_methods` with the method, the instrument and `"enabled": true`. Send a new `X-Idempotency-Key` for each intended change.

```bash Curl theme={null}
curl -X PATCH https://api.razorpay.com/v3/accounts/acc_TcdGEzmfKQzEl1/products/payment_gateway/payment_methods \
-u rzp_live_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: b1f0c6de-5a4e-4c1b-9d2a-3e8f7a6b5c41" \
-H "Content-Type: application/json" \
-d '{
  "method": "upi",
  "instrument": "payer_account_types/bank_account",
  "enabled": true
}'
```

```json Response theme={null}
{
  "payer_account_type": "bank_account",
  "name": "UPI from a bank account",
  "logo_url": null,
  "status": "activated",
  "status_reason": null,
  "enabled": true,
  "requirements": [],
  "estimated_activation_days": 14,
  "updated_at": 1794630120
}
```

Enabling or disabling returns the one resulting instrument as a bare object, not a collection. Read its `status`:

| Status | What it means | What to do |
| - | - | - |
| `activated` with `enabled: true` | Customers can pay with it now. | Nothing. |
| `under_review` | Onboarding has started and nothing is due. | [Follow onboarding](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/follow-onboarding.md). |
| `in_progress` | Razorpay needs something first. `requirements` lists it. | [Supply the requirements](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/supply-requirements.md). |

Enabling an instrument that is already on, or already being onboarded, changes nothing and returns it as it is.

> [!WARNING]
>
> **Watch Out!**
>
> * Enable one instrument per call. A group such as `debit_card` applies the call to each member. Members that are ineligible or rejected stay as they are.
> * `credit_card` switches only its 13 default issuers. Enable HDFC Bank, SBI and American Express credit-card EMI one at a time.
> * A write without an `X-Idempotency-Key` of 16 to 64 printable ASCII characters returns `400`. Do not put personal data in the key.

## 1.4 Disable and Re-enable

Send `"enabled": false` to switch an instrument off, or `"enabled": true` to switch it back on. Disabling an instrument that is still being onboarded stops the onboarding.

An activated instrument switches back on at once, with no new onboarding. There is no switch for a whole payment method. To turn a method off, switch off each of its instruments.

## 1.5 Handle Errors

Handle errors by HTTP status, then by `error.reason`. The ones you are most likely to meet when enabling:

| HTTP code | `reason` | When |
| - | - | - |
| 400 | `instrument_ineligible` | The instrument cannot be enabled now. `metadata.status_reason` says why. |
| 400 | `instrument_rejected` | Razorpay rejected the instrument for this account. The sub-merchant can ask Razorpay support to review it. |
| 400 | `pricing_missing` | The account's plan has no pricing for this method yet. Contact Razorpay support. |
| 403 | `insufficient_scope` | Your key has `account_read` only. Use a key with `account_read_write`. |
| 409 | `idempotency_key_mismatch` | You reused a key within 24 hours with a different body. |
| 409 | `idempotency_in_progress` | The first request with this key is still running. Retry after the `Retry-After` header, with the same key. |

After a timeout or a `5xx`, send the same request again with the same `X-Idempotency-Key`. After a `429`, wait for the `Retry-After` header.

## Next Step

[Activated vs Enabled](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/activated-vs-enabled.md)
