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

# Actions on a Sub-Merchant's Payments and Settlement

> What disabling payments, putting settlement on hold and suspending a sub-merchant do, who can take and reverse each action, and how status_reason explains it.

Available in🇮🇳 India

An action changes what a sub-merchant can do on its `payment_gateway` product. Razorpay takes actions after its risk reviews. You can take the same actions for your own reasons, and reverse the ones you took.

## The Three Things an Action Changes

The `payment_gateway` product carries its `status` and 2 objects, `payment_acceptance` and `settlement`:

```json Payment Gateway Product theme={null}
{
  "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": "prohibited_business",
          "description": "Razorpay can't support this business model.",
          "requirement_id": "req_UYTBV02QSYTRVK"
        },
        "initiated_by": "razorpay",
        "updated_at": 1794481600
      }
    }
  }
}
```

The table below lists what each one controls:

| Field | Values | What It Controls |
| - | - | - |
| `products.payment_gateway.status` | `activated`, `suspended` | Whether the product is live. A suspension stops both objects below. |
| `products.payment_gateway.payment_acceptance.status` | `enabled`, `disabled` | Whether the sub-merchant can take new payments. |
| `products.payment_gateway.settlement.status` | `enabled`, `on_hold` | Whether Razorpay settles the sub-merchant's payments. While on hold, the sub-merchant can still take payments if `payment_acceptance` is `enabled`. |

Each of `payment_acceptance` and `settlement` carries these fields:

| Field | Description |
| - | - |
| `status` | The effective state. It answers "can this sub-merchant take payments, or be settled, right now?" without other flags. |
| `status_reason` | Why it is stopped: `code`, `description` and `requirement_id`. `null` while it is `enabled`. |
| `status_reason.code` | A stable code from the [reason codes](https://razorpay.com/docs/api/partners/accounts/merchant-risk/reason-codes.md). Branch on it. |
| `status_reason.description` | Text to show the sub-merchant. The wording can change. |
| `status_reason.requirement_id` | The `id` of the [requirement](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications.md) to answer to get this action reviewed. `null` when there is nothing to answer, and Razorpay reverses the action after its own review. |
| `initiated_by` | Who took the action: `razorpay` or `partner`. `null` while it is `enabled`. |
| `updated_at` | Unix timestamp at which the current state took effect. |

There is no history of earlier states. Each object shows only its current state.

## The Six Partner Actions

You take an action with one call, `POST /v1/accounts/{id}/products/payment_gateway/actions/{action}`. Know more about the [Partner Actions API](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md).

| Action | What It Does | Needs `status_reason` | Needs Partner Actions Switched On |
| - | - | - | - |
| `disable_payments` | Sets `payment_acceptance` to `disabled`. New payments are refused. | Yes | Yes |
| `enable_payments` | Sets `payment_acceptance` back to `enabled`, if you disabled it. | No | No |
| `disable_settlement` | Sets `settlement` to `on_hold`. Razorpay holds settlement. | Yes | Yes |
| `enable_settlement` | Sets `settlement` back to `enabled`, if you put it on hold. | No | No |
| `suspend` | Sets the product to `suspended`, `payment_acceptance` to `disabled` and `settlement` to `on_hold`. | Yes | Yes |
| `unsuspend` | Sets the product back to `activated` and both objects back to `enabled`, if you suspended it. | No | No |

Razorpay takes the same actions from its side, with its own reason codes.

## Who Can Reverse an Action

Each side reverses only what it did. The table below lists what you can do:

| Current State | Taken By | You Can |
| - | - | - |
| Object `enabled` | Not applicable | Disable it with `disable_payments` or `disable_settlement`, with a `partner_*` reason. |
| Object stopped | `partner` | Reverse it with `enable_payments` or `enable_settlement`. |
| Object stopped | `razorpay` | Nothing. Answer the requirement in `status_reason.requirement_id`, if any. Reversing returns `400 payments_disable_not_reversible` or `400 settlement_disable_not_reversible`. |
| Product `activated` | Not applicable | Suspend it with `suspend`, with a `partner_*` reason. |
| Product `suspended` | `partner` | Reverse it with `unsuspend`. |
| Product `suspended` | `razorpay` | Nothing. `unsuspend` returns `400 suspension_not_reversible`. |

Repeating the current state returns `200` and changes nothing. If Razorpay has already stopped an object, your action does not replace Razorpay's `status_reason`.

The diagrams below show who moves each state:

> [tab] Payment Acceptance
>
> ```mermaid theme={null}
> stateDiagram-v2
> enabled --> disabled : Razorpay or you
> disabled --> enabled : only the side that disabled it
> ```

> [tab] Settlement
>
> ```mermaid theme={null}
> stateDiagram-v2
> enabled --> on_hold : Razorpay or you
> on_hold --> enabled : only the side that held it
> ```

> [tab] Product
>
> ```mermaid theme={null}
> stateDiagram-v2
> activated --> suspended : Razorpay or you
> suspended --> activated : only the side that suspended
> ```

## Suspension

A suspension stops everything on the `payment_gateway` product at once. Razorpay or you can suspend. A suspension:

* Sets the product's `status` to `suspended`.
* Sets `payment_acceptance` to `disabled` and `settlement` to `on_hold`, both with the same `status_reason` and `initiated_by`.
* Blocks every other action on either object until it is reversed. An action returns `400 product_suspended`.

Reversing a suspension sets the product back to `activated` and both objects back to `enabled`. An action that was in place before the suspension does not come back.

## Status Reason and Reason Codes

Every stopped object carries a `status_reason`. When you act, send `status_reason.code` as one of your 3 codes, `partner_fraud_review`, `partner_policy` or `partner_other`, and a `description` the sub-merchant sees. `status_reason.requirement_id` is read-only. Know more about the [reason codes](https://razorpay.com/docs/api/partners/accounts/merchant-risk/reason-codes.md).

> [!NOTE]
>
> **Handy Tips**
>
> Razorpay switches on partner actions (`suspend`, `disable_payments`, `disable_settlement`) for each platform. Until then, these return `403 partner_actions_not_enabled`. Reversing your own action always works.

## Flows

> [tab] Razorpay Acts and Asks
>
> **1. Razorpay Raises a Requirement**
>
> `account.product.payment_gateway.requirement.needs_clarification` arrives. Know more about [clarifications](https://razorpay.com/docs/partners/aggregators/merchant-risk/clarifications.md).
>
> **2. Razorpay Puts Settlement on Hold**
>
> `account.product.payment_gateway.settlement.on_hold` arrives with `status: on_hold` and `status_reason.requirement_id` set to the requirement's `id`.
>
> **3. You Show Both to the Sub-Merchant**
>
> Show `status_reason.description` and the requirement it points to. Send the responses.
>
> **4. Razorpay Reverses or Escalates**
>
> On a good outcome, the requirement is resolved and settlement returns to `enabled`, each with its own event. Otherwise, Razorpay can keep the hold or suspend the product.

> [tab] Razorpay Acts Only
>
> **1. Razorpay Stops an Object**
>
> The object's event arrives with `initiated_by: razorpay` and `status_reason.requirement_id: null`.
>
> **2. You Show the Reason**
>
> Show `status_reason.description`. You cannot reverse it, and there is nothing to answer.
>
> **3. Razorpay Reverses It After Its Review**
>
> The object returns to `enabled` with its own `.enabled` event.

> [tab] Your Own Action
>
> **1. You Act**
>
> Call `disable_payments`, `disable_settlement` or `suspend` with a `partner_*` reason. The response shows `initiated_by: partner`.
>
> **2. Razorpay Sends the Event**
>
> The object's event, or `account.product.payment_gateway.suspended`, arrives like any other change.
>
> **3. You Reverse It**
>
> Call `enable_payments`, `enable_settlement` or `unsuspend`. Only you can reverse it.

## Next Steps

* [Partner Actions API](https://razorpay.com/docs/api/partners/accounts/merchant-risk/actions.md): request and response for each of the 6 actions, and their errors.
* [Actions webhooks](https://razorpay.com/docs/partners/aggregators/merchant-risk/actions-webhooks.md): the 6 events actions send.
* [Reason codes](https://razorpay.com/docs/api/partners/accounts/merchant-risk/reason-codes.md) and [errors](https://razorpay.com/docs/api/partners/accounts/merchant-risk/errors.md).
