> ## 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_HQVlm3bnPmccC0/products/payment_gateway/payment_methods \
-u rzp_live_partner_[CLIENT_ID]:[CLIENT_SECRET]
```

Fetching always returns a collection, even for one payment method. Every payment method holds its instruments in one list, `instruments`. This response shows all 6 payment methods, with a few instruments each:

```json Response theme={null}
{
  "entity": "collection",
  "count": 6,
  "items": [
    {
      "entity": "payment_method",
      "method": "card",
      "name": "Cards",
      "instruments": [
        {
          "instrument": "card/international",
          "name": "International cards",
          "logo_url": null,
          "status": "eligible",
          "status_reason": null,
          "enabled": false,
          "requirements": [],
          "updated_at": null
        },
        {
          "instrument": "card/networks/amex",
          "name": "American Express",
          "logo_url": "https://cdn.razorpay.com/app/amex.svg",
          "status": "under_review",
          "status_reason": null,
          "enabled": false,
          "requirements": [],
          "updated_at": 1794474862
        },
        {
          "instrument": "card/networks/diners",
          "name": "Diners Club",
          "logo_url": "https://cdn.razorpay.com/app/diners.svg",
          "status": "ineligible",
          "status_reason": {
            "code": "eligibility_no_history",
            "description": "Eligibility will be calculated after your first transactions."
          },
          "enabled": false,
          "requirements": [],
          "updated_at": null
        }
      ]
    },
    {
      "entity": "payment_method",
      "method": "netbanking",
      "name": "Netbanking",
      "instruments": [
        {
          "instrument": "netbanking/banks/hdfc",
          "name": "HDFC Bank",
          "logo_url": "https://cdn.razorpay.com/app/hdfc.svg",
          "status": "activated",
          "status_reason": null,
          "enabled": true,
          "requirements": [],
          "updated_at": 1794566462
        },
        {
          "instrument": "netbanking/banks/kkbk",
          "name": "Kotak Mahindra Bank",
          "logo_url": "https://cdn.razorpay.com/app/kkbk.svg",
          "status": "eligible",
          "status_reason": null,
          "enabled": false,
          "requirements": [
            {
              "id": "req_Qd3Kp8Lm2Vx7Tn",
              "code": "gstin",
              "description": "The GSTIN of the business.",
              "reason": "Kotak Mahindra Bank needs it to onboard the account.",
              "level": "mandatory",
              "field_path": "business_profile.identity_numbers.gstin",
              "value_type": "text"
            },
            {
              "id": "req_Rf6Hs1Zb9Yc4Wg",
              "code": "shop_establishment",
              "description": "The shop and establishment certificate of the business.",
              "reason": "Kotak Mahindra Bank needs it to onboard the account.",
              "level": "mandatory",
              "field_path": "business_profile.documents.shop_establishment",
              "value_type": "document",
              "metadata": {
                "constraints": {
                  "accept": [
                    "application/pdf",
                    "image/jpeg",
                    "image/png"
                  ],
                  "max_size_mb": 20
                }
              }
            }
          ],
          "updated_at": null
        }
      ]
    },
    {
      "entity": "payment_method",
      "method": "upi",
      "name": "UPI",
      "instruments": [
        {
          "instrument": "upi/payer_account_types/bank_account",
          "name": "UPI from a bank account",
          "logo_url": null,
          "status": "activated",
          "status_reason": null,
          "enabled": false,
          "requirements": [],
          "updated_at": 1794567010
        }
      ]
    },
    {
      "entity": "payment_method",
      "method": "wallet",
      "name": "Wallets",
      "instruments": [
        {
          "instrument": "wallet/wallets/amazonpay",
          "name": "Amazon Pay",
          "logo_url": "https://cdn.razorpay.com/app/amazonpay.svg",
          "status": "rejected",
          "status_reason": {
            "code": "not_allowed_for_business",
            "description": "This instrument is not allowed for your business."
          },
          "enabled": false,
          "requirements": [],
          "updated_at": 1793794833
        }
      ]
    },
    {
      "entity": "payment_method",
      "method": "emi",
      "name": "EMI",
      "instruments": [
        {
          "instrument": "emi/credit_card",
          "name": "Credit-card EMI (13 banks)",
          "logo_url": null,
          "status": "activated",
          "status_reason": null,
          "enabled": true,
          "requirements": [],
          "updated_at": 1793120000
        },
        {
          "instrument": "emi/credit_card/banks/sbin",
          "name": "SBI credit-card EMI",
          "logo_url": "https://cdn.razorpay.com/app/sbin.svg",
          "status": "eligible",
          "status_reason": null,
          "enabled": false,
          "requirements": [],
          "updated_at": null
        },
        {
          "instrument": "emi/debit_card",
          "name": "Debit-card EMI",
          "logo_url": null,
          "status": "under_review",
          "status_reason": null,
          "enabled": false,
          "requirements": [],
          "updated_at": 1794391617
        },
        {
          "instrument": "emi/debit_card/banks/hdfc",
          "name": "HDFC Bank debit-card EMI",
          "logo_url": "https://cdn.razorpay.com/app/hdfc.svg",
          "status": "needs_clarification",
          "status_reason": null,
          "enabled": false,
          "requirements": [
            {
              "id": "req_Tm5Jc8Nq2Lr7Xa",
              "code": "website",
              "description": "Add the page, share a website that has it, or reply with how customers ask for a refund.",
              "reason": "HDFC Bank needs a refund and cancellation policy page on the website.",
              "level": "mandatory",
              "fulfillment_criteria": "one_of",
              "sub_requirements": [
                {
                  "id": "req_Vp9Ge4Kd6Ms1Bh",
                  "code": "website_url",
                  "description": "Your website's address.",
                  "reason": null,
                  "level": "conditional",
                  "field_path": "products.payment_gateway.payment_channels.website.primary",
                  "value_type": "text"
                },
                {
                  "id": "req_Wn2Lf7Qj5Tz8Cy",
                  "code": "clarify_website",
                  "description": "Or reply with a comment about your website.",
                  "reason": null,
                  "level": "conditional",
                  "field_path": "products.payment_gateway.requirements.requirement_response",
                  "value_type": "text",
                  "metadata": {
                    "constraints": {
                      "minLength": 50,
                      "maxLength": 300
                    }
                  }
                }
              ]
            }
          ],
          "updated_at": 1794391617
        }
      ]
    },
    {
      "entity": "payment_method",
      "method": "cod",
      "name": "Cash on Delivery",
      "instruments": [
        {
          "instrument": "cod/full",
          "name": "Cash on Delivery",
          "logo_url": null,
          "status": "activated",
          "status_reason": null,
          "enabled": true,
          "requirements": [],
          "updated_at": 1794567120
        },
        {
          "instrument": "cod/partial",
          "name": "Partial Cash on Delivery",
          "logo_url": null,
          "status": "activated",
          "status_reason": null,
          "enabled": true,
          "requirements": [],
          "updated_at": 1794567120
        }
      ]
    }
  ]
}
```

To fetch one payment method, add `method`, such as `?method=cod`. The response has the same shape, with one item.

### Instrument Object

| Field | Type | Description |
| - | - | - |
| `instrument` | string | The instrument id, unique across all payment methods, such as `netbanking/banks/hdfc`. Send it unchanged when you enable, disable or answer requirements. |
| `name` | string | Name to show, in the language of `Accept-Language`. |
| `logo_url` | string or null | An https link to the logo. `null` when the instrument has none, as on a group instrument. |
| `status` | string | `eligible`, `ineligible`, `in_progress`, `under_review`, `needs_clarification`, `activated`, `rejected` or `suspended`. Know more about [instrument statuses](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/activated-vs-enabled.md). |
| `status_reason` | object or null | Why the instrument is `ineligible`, `rejected` or `suspended`, as `code` and `description`. `null` in every other status. |
| `enabled` | boolean | `true` when customers can pay with it now: it is activated and switched on. |
| `requirements` | array | What Razorpay still needs before it can activate the instrument. An answered requirement drops out of the list. `[]` when it needs nothing. Know more about [requirements](https://razorpay.com/docs/partners/aggregators/onboarding-api/payment-methods/supply-requirements.md). |
| `updated_at` | integer or null | Time of the last change of `status` or `enabled`, as a Unix timestamp in seconds. `null` if neither has changed. |

> [!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`, `status_reason.description`, `requirements[].description` and `requirements[].reason`, follow the `Accept-Language` header. Codes are never translated.
> * Allow a timeout of at least 5 seconds. A fetch typically takes 1 to 2 seconds.
> * Instruments can change without any call from you, as banks, providers and Razorpay move onboarding along.

## 1.2 Instrument Ids

Every instrument has one id, unique across all payment methods. The same bank code can sit in several methods (`hdfc` is in netbanking and in both EMI groups), so the id always starts with the payment method. Read it from the fetch response and send it unchanged as `instrument`.

| Method | Instrument id | Instrument |
| - | - | - |
| `card` | `card/networks/amex` | American Express cards |
| `card` | `card/international` | International cards |
| `netbanking` | `netbanking/banks/hdfc` | HDFC Bank netbanking |
| `upi` | `upi/payer_account_types/bank_account` | UPI from a bank account |
| `upi` | `upi/autopay` | UPI Autopay |
| `wallet` | `wallet/wallets/phonepe` | PhonePe wallet |
| `emi` | `emi/debit_card/banks/hdfc` | HDFC Bank debit-card EMI |
| `emi` | `emi/credit_card/banks/sbin` | SBI credit-card EMI, one bank in a group |
| `cod` | `cod/partial` | Partial cash on delivery |

Do not use `name` as an id. It follows `Accept-Language` and can be reworded.

## 1.3 Enable an Instrument

Call `PATCH …/payment_methods` with 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_HQVlm3bnPmccC0/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 '{
  "instrument": "upi/payer_account_types/bank_account",
  "enabled": true
}'
```

The response says what the call did to the instrument. The name, logo and other details are in the fetch response, so they are not repeated:

```json Response theme={null}
{
  "instrument": "upi/payer_account_types/bank_account",
  "status": "activated",
  "enabled": true,
  "updated_at": 1794630120
}
```

Enabling or disabling returns the one resulting instrument as a bare object, not a collection. `requirements` is included only when the status is `in_progress` or `needs_clarification`, so you can answer it at once. Read the `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. | [Subscribe to webhooks](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). |

If the instrument first needs onboarding and Razorpay needs something, the status is `in_progress` and the response lists the requirements. For example, Kotak Mahindra Bank netbanking:

```bash Curl theme={null}
curl -X PATCH https://api.razorpay.com/v3/accounts/acc_HQVlm3bnPmccC0/products/payment_gateway/payment_methods \
-u rzp_live_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: 6d2e8a14-0c7b-4f3e-a1d9-52b7c3e9f018" \
-H "Content-Type: application/json" \
-d '{
  "instrument": "netbanking/banks/kkbk",
  "enabled": true
}'
```

```json Response theme={null}
{
  "instrument": "netbanking/banks/kkbk",
  "status": "in_progress",
  "enabled": false,
  "updated_at": 1794630245,
  "requirements": [
    {
      "id": "req_Qd3Kp8Lm2Vx7Tn",
      "code": "gstin",
      "description": "The GSTIN of the business.",
      "reason": "Kotak Mahindra Bank needs it to onboard the account.",
      "level": "mandatory",
      "field_path": "business_profile.identity_numbers.gstin",
      "value_type": "text"
    },
    {
      "id": "req_Rf6Hs1Zb9Yc4Wg",
      "code": "shop_establishment",
      "description": "The shop and establishment certificate of the business.",
      "reason": "Kotak Mahindra Bank needs it to onboard the account.",
      "level": "mandatory",
      "field_path": "business_profile.documents.shop_establishment",
      "value_type": "document",
      "metadata": {
        "constraints": {
          "accept": [
            "application/pdf",
            "image/jpeg",
            "image/png"
          ],
          "max_size_mb": 20
        }
      }
    }
  ]
}
```

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 `emi/debit_card` applies the call to each member. Members that are ineligible or rejected stay as they are.
> * `emi/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.
> * Send only the fields in this guide. A field that is not part of the contract returns `400` with `extra_field_sent`.

## 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 and returns it to `eligible`.

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`. Never build logic on `error.description`, which can change. The ones you are most likely to meet when enabling:

| HTTP code | `reason` | When |
| - | - | - |
| 400 | `invalid_request` | `instrument` or `enabled` is missing or null. `field` names it. |
| 400 | `invalid_format` | `enabled` is not `true` or `false`, or `X-Idempotency-Key` is not 16 to 64 printable ASCII characters. |
| 400 | `missing_header` | No `X-Idempotency-Key` header. |
| 404 | `not_found` | `instrument` is not an instrument id of the account. |
| 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. |
| 400 | `product_not_requested` | The `payment_gateway` product is not requested on the account. Request it through the Onboarding APIs first. |
| 403 | `insufficient_scope` | Your key has `account_read` only. Use a key with `account_read_write`. |
| 403 | `category_not_supported` | The account is not in an e-commerce business category. |
| 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, a `409 idempotency_in_progress` 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)
