> ## 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.

# Take an Action on a Sub-Merchant

> Disable or enable payments, put settlement on hold or release it, and suspend or unsuspend a sub-merchant's payment_gateway product with one POST call per action.

Available in🇮🇳 India

Use this endpoint to take one action on a sub-merchant's `payment_gateway` product: disable or enable payments, put settlement on hold or release it, or suspend or unsuspend the product. Know more about [what each action does and who can reverse it](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions.md).

> [!NOTE]
>
> **Handy Tips**
>
> * `action` in the path names the action. Send `status_reason` in the body for `suspend`, `disable_payments` and `disable_settlement`.
> * Repeating the current state returns `200` and changes nothing. An action Razorpay already took keeps Razorpay's `status_reason`.
> * Each change sends its webhook, as a change by Razorpay would. Know more about [actions webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions-webhooks.md).
> * This endpoint needs the `onboarding_accounts_write` scope.

> [!WARNING]
>
> **Watch Out!**
>
> * You can reverse only what you did. An action with `initiated_by: razorpay` returns `400` when you try to reverse it.
> * While the product is `suspended`, every action other than `unsuspend` returns `400` with `product_suspended`.
> * `suspend`, `disable_payments` and `disable_settlement` need partner actions switched on for your platform. Otherwise, the call returns `403` with `partner_actions_not_enabled`. Reversing your own action always works.

```bash Disable Settlement theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/products/payment_gateway/actions/disable_settlement \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "status_reason": {
    "code": "partner_fraud_review",
    "description": "You're reviewing the merchant for fraud."
  }
}'
```

```bash Enable Settlement theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/products/payment_gateway/actions/enable_settlement \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: [UNIQUE_KEY]"
```

```bash Disable Payments theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/products/payment_gateway/actions/disable_payments \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "status_reason": {
    "code": "partner_policy",
    "description": "The merchant broke your policy."
  }
}'
```

```bash Enable Payments theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/products/payment_gateway/actions/enable_payments \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: [UNIQUE_KEY]"
```

```bash Suspend theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/products/payment_gateway/actions/suspend \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: [UNIQUE_KEY]" \
-d '{
  "status_reason": {
    "code": "partner_fraud_review",
    "description": "You're reviewing the merchant for fraud."
  }
}'
```

```bash Unsuspend theme={null}
curl -X POST https://api.razorpay.com/v1/accounts/acc_Rk9Xm2Qp7Zt4Nb/products/payment_gateway/actions/unsuspend \
-u rzp_test_partner_[CLIENT_ID]:[CLIENT_SECRET] \
-H "X-Idempotency-Key: [UNIQUE_KEY]"
```

```json Disable Settlement theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "activated",
      "payment_acceptance": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1786000000
      },
      "settlement": {
        "status": "on_hold",
        "status_reason": {
          "code": "partner_fraud_review",
          "description": "You're reviewing the merchant for fraud.",
          "requirement_id": null
        },
        "initiated_by": "partner",
        "updated_at": 1795710000
      },
      "requirements": []
    }
  }
}
```

```json Enable Settlement theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "activated",
      "payment_acceptance": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1786000000
      },
      "settlement": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1795783800
      },
      "requirements": []
    }
  }
}
```

```json Disable Payments theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "activated",
      "payment_acceptance": {
        "status": "disabled",
        "status_reason": {
          "code": "partner_policy",
          "description": "The merchant broke your policy.",
          "requirement_id": null
        },
        "initiated_by": "partner",
        "updated_at": 1795710000
      },
      "settlement": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1786000000
      },
      "requirements": []
    }
  }
}
```

```json Enable Payments theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "activated",
      "payment_acceptance": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1795783800
      },
      "settlement": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1786000000
      },
      "requirements": []
    }
  }
}
```

```json Suspend theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "suspended",
      "payment_acceptance": {
        "status": "disabled",
        "status_reason": {
          "code": "partner_fraud_review",
          "description": "You're reviewing the merchant for fraud.",
          "requirement_id": null
        },
        "initiated_by": "partner",
        "updated_at": 1795870800
      },
      "settlement": {
        "status": "on_hold",
        "status_reason": {
          "code": "partner_fraud_review",
          "description": "You're reviewing the merchant for fraud.",
          "requirement_id": null
        },
        "initiated_by": "partner",
        "updated_at": 1795870800
      },
      "requirements": []
    }
  }
}
```

```json Unsuspend theme={null}
{
  "id": "acc_Rk9Xm2Qp7Zt4Nb",
  "entity": "account",
  "risk_profile": {
    "rating": {
      "band": "medium",
      "updated_at": 1786000000
    }
  },
  "products": {
    "payment_gateway": {
      "status": "activated",
      "payment_acceptance": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1796414400
      },
      "settlement": {
        "status": "enabled",
        "status_reason": null,
        "initiated_by": null,
        "updated_at": 1796414400
      },
      "requirements": []
    }
  }
}
```

```json Failure theme={null}
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "Razorpay put settlement on hold. Only Razorpay can release it.",
    "source": "business",
    "step": "state",
    "reason": "settlement_disable_not_reversible",
    "field": "action",
    "metadata": {
      "initiated_by": "razorpay",
      "requirement_id": "req_UYTBV02QSYTRVK"
    }
  }
}
```

## Path Parameters

**id** `string` *required*

The unique identifier of the account, `acc_` followed by 14 letters or digits. For example, `acc_Rk9Xm2Qp7Zt4Nb`.

**action** `string` *required*

The action to take. Possible values:

* `suspend`: Suspends the product. Both objects stop with your `status_reason`.
* `unsuspend`: Reverses a suspension you set. Both objects return to `enabled`.
* `disable_payments`: Sets `payment_acceptance` to `disabled`.
* `enable_payments`: Reverses a `disable_payments` you did.
* `disable_settlement`: Sets `settlement` to `on_hold`.
* `enable_settlement`: Reverses a `disable_settlement` you did.

## Request Parameters

**X-Idempotency-Key** `string` *required*

A unique key you generate for this operation, 16-64 printable ASCII characters long. The same key with the same request returns the first `200` again for 1 hour, with the response header `Idempotent-Replayed: true`. A refused or failed request holds no key, so a retry with the same key runs again.

**status\_reason** `object`

Why you take the action. Required for `suspend`, `disable_payments` and `disable_settlement`. Do not send it for `unsuspend`, `enable_payments` or `enable_settlement`. On `suspend`, Razorpay copies it onto `payment_acceptance.status_reason` and `settlement.status_reason`.

**properties**

**code** `string` *required*

One of your codes: `partner_fraud_review`, `partner_policy` or `partner_other`. Know more about [reason codes](https://razorpay.com/docs/api/partners/accounts/merchant-risk/reason-codes.md).

**description** `string`

A sentence the sub-merchant sees. Say what the reason is when you use `partner_other`.

`status_reason.requirement_id` is read-only. Sending it returns `400` with `field_read_only`.

The table below lists the request body of each action:

| Action | Request Body |
| - | - |
| `disable_settlement` | `{"status_reason": {"code": "partner_fraud_review", "description": "You're reviewing the merchant for fraud."}}` |
| `enable_settlement` | None |
| `disable_payments` | `{"status_reason": {"code": "partner_policy", "description": "The merchant broke your policy."}}` |
| `enable_payments` | None |
| `suspend` | `{"status_reason": {"code": "partner_fraud_review", "description": "You're reviewing the merchant for fraud."}}` |
| `unsuspend` | None |

## Response Parameters

The response is the account, as [Fetch an Account](https://razorpay.com/docs/api/partners/accounts/merchant-risk/risk-profile.md) returns it. The fields an action changes are on `products.payment_gateway`:

**products.payment\_gateway.status** `string`

The product's status. After activation, the values are:

* `activated`: The product is live. Check `payment_acceptance` and `settlement` for stops.
* `suspended`: Razorpay or you suspended the product. Both objects are stopped with the same `status_reason` and `initiated_by`.

**products.payment\_gateway.payment\_acceptance** `object`

Whether the sub-merchant can take new payments.

**properties**

**status** `string`

The effective state. Possible values:

* `enabled`: The sub-merchant can take payments.
* `disabled`: New payments are refused.

**status\_reason** `object`

Why it is stopped. `null` while it is `enabled`.

**properties**

**code** `string`

A stable code for the reason. Branch on it. Know more about [reason codes](https://razorpay.com/docs/api/partners/accounts/merchant-risk/reason-codes.md).

**description** `string`

A sentence to show the sub-merchant. The wording can change.

**requirement\_id** `string`

The `id` of the requirement to answer to get this action reviewed, `req_`-prefixed. `null` when there is nothing to answer. Read-only.

**initiated\_by** `string`

Who took the action: `razorpay` or `partner`. Only this side can reverse it. `null` while it is `enabled`. Read-only.

**updated\_at** `integer`

Unix timestamp at which the current state took effect. Read-only.

**products.payment\_gateway.settlement** `object`

Whether Razorpay settles the sub-merchant's payments.

**properties**

**status** `string`

The effective state. Possible values:

* `enabled`: Razorpay settles payments on the usual schedule.
* `on_hold`: Razorpay holds settlement. The sub-merchant can still take payments if `payment_acceptance` is `enabled`.

**status\_reason** `object`

Why it is stopped. `null` while it is `enabled`.

**properties**

**code** `string`

A stable code for the reason. Branch on it. Know more about [reason codes](https://razorpay.com/docs/api/partners/accounts/merchant-risk/reason-codes.md).

**description** `string`

A sentence to show the sub-merchant. The wording can change.

**requirement\_id** `string`

The `id` of the requirement to answer to get this action reviewed, `req_`-prefixed. `null` when there is nothing to answer. Read-only.

**initiated\_by** `string`

Who took the action: `razorpay` or `partner`. Only this side can reverse it. `null` while it is `enabled`. Read-only.

**updated\_at** `integer`

Unix timestamp at which the current state took effect. Read-only.

## Errors

Every error returns the Accounts API error envelope, `{"error": {...}}` with `code`, `description`, `source`, `step`, `reason`, `field` and `metadata`. Know more about the [error object](https://razorpay.com/docs/api/partners/accounts/merchant-risk/errors.md#error-object).

### Action Errors

> [accordion] This field can't be changed.
>
> **Code:** `400`
>
> **Reason:** `field_read_only`
>
> The body sets a field that only Razorpay sets, such as `status_reason.requirement_id`. `initiated_by` and `updated_at` are also read-only.
>
> **Solution:** Send only `status_reason.code` and `status_reason.description`. `error.field` names the read-only field.

> [accordion] Razorpay disabled payment acceptance. Only Razorpay can enable it.
>
> **Code:** `400`
>
> **Reason:** `payments_disable_not_reversible`
>
> You called `enable_payments` while `payment_acceptance.initiated_by` is `razorpay`.
>
> **Solution:** Show the sub-merchant `status_reason.description`. If `status_reason.requirement_id` is set, answer that requirement. `metadata.requirement_id` repeats it.

> [accordion] Razorpay put settlement on hold. Only Razorpay can release it.
>
> **Code:** `400`
>
> **Reason:** `settlement_disable_not_reversible`
>
> You called `enable_settlement` while `settlement.initiated_by` is `razorpay`.
>
> **Solution:** Show the sub-merchant `status_reason.description`. If `status_reason.requirement_id` is set, answer that requirement. `metadata.requirement_id` repeats it.

> [accordion] Razorpay suspended the product. Only Razorpay can unsuspend it.
>
> **Code:** `400`
>
> **Reason:** `suspension_not_reversible`
>
> You called `unsuspend` on a product that Razorpay suspended.
>
> **Solution:** Show the sub-merchant `status_reason.description` from either object. Answer the requirement in `status_reason.requirement_id`, if any.

> [accordion] The product is suspended. Reverse the suspension first.
>
> **Code:** `400`
>
> **Reason:** `product_suspended`
>
> You called `disable_payments`, `enable_payments`, `disable_settlement` or `enable_settlement` while the product's `status` is `suspended`.
>
> **Solution:** Reverse the suspension first if you set it, with `unsuspend`. A suspension by Razorpay can only be reversed by Razorpay.

> [accordion] Partner actions aren't enabled for this platform.
>
> **Code:** `403`
>
> **Reason:** `partner_actions_not_enabled`
>
> You called `suspend`, `disable_payments` or `disable_settlement`, and Razorpay has not switched on partner actions for your platform. Reversing your own action (`unsuspend`, `enable_payments`, `enable_settlement`) is never refused for this reason.
>
> **Solution:** Contact Razorpay to switch on partner actions for your platform.

### Request Errors

> [accordion] The account ID isn't valid.
>
> **Code:** `400`
>
> **Reason:** `invalid_account_id`
>
> The account ID in the path is not `acc_` followed by 14 letters or digits.
>
> **Solution:** Send the account ID as `acc_` followed by 14 letters or digits, such as `acc_Rk9Xm2Qp7Zt4Nb`.

> [accordion] The idempotency key isn't valid.
>
> **Code:** `400`
>
> **Reason:** `invalid_format`
>
> `X-Idempotency-Key` is not 16-64 printable ASCII characters.
>
> **Solution:** Send `X-Idempotency-Key` with 16-64 printable ASCII characters.

> [accordion] Choose one of the allowed values (action).
>
> **Code:** `400`
>
> **Reason:** `invalid_option`
>
> `action` is not one of the supported actions. `metadata.allowed_values` lists the values.
>
> **Solution:** Send an `action` from `metadata.allowed_values`.

> [accordion] This idempotency key was already used with a different request.
>
> **Code:** `400`
>
> **Reason:** `idempotency_key_reused`
>
> You sent this `X-Idempotency-Key` before with a different action or different inputs.
>
> **Solution:** Send a new `X-Idempotency-Key` for a different request. Reuse a key only to retry the same request.

> [accordion] The earlier request is still being processed.
>
> **Code:** `409`
>
> **Reason:** `idempotency_in_progress`
>
> A request with this `X-Idempotency-Key` is still running. Razorpay stores its result only when it finishes.
>
> **Solution:** Wait for the time in the `Retry-After` header, then retry with the same key.

### Write Errors

> [accordion] A required header is missing.
>
> **Code:** `400`
>
> **Reason:** `missing_header`
>
> `X-Idempotency-Key` is missing. On answers and uploads, a key that is not 16-64 printable ASCII characters also returns this. On partner actions, such a key returns `invalid_format`.
>
> **Solution:** Send `X-Idempotency-Key` with 16-64 printable ASCII characters.

### Common Errors

| Code | Reason | Description |
| - | - | - |
| `401` | `invalid_credentials` | The credentials aren't valid. |
| `403` | `onboarding_not_enabled` | Onboarding isn't enabled for this platform. |
| `403` | `ip_not_allowed` | Requests from this address aren't allowed. |
| `403` | `insufficient_scope` | These credentials can't perform this operation. |
| `403` | `consent_withdrawn` | The business has withdrawn this platform's access to its Razorpay account. |
| `404` | `not_found` | The requested resource doesn't exist. |
| `429` | `rate_limited` | Too many requests. Try again shortly. |
| `500` | `internal_error` | Something went wrong on our side. Try again. |
