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

# Management sessions

A management session is a short‑lived object that allows a beneficiary to manage payout methods in a PaySway-hosted UI.

## Create a session

You can create a new management session by sending the following request:

[**POST** /beneficiaries/organizations/sessions](/api-reference/beneficiary-hub/create-management-session)

<CodeGroup>
  ```json Request theme={null}
  {
    "externalUserId": "1dda592e-5b1d-47d2-b1de-e772fca15327",
    "returnUrl": "https://tenant.tld/return-url"
  }
  ```

  ```json Response theme={null}
  {
    "id": "4479b65d-a33b-43e4-9d3b-3b3f159cbf52",
    "url": "https://payouts.tenant.tld/sessions/4479b65d-a33b-43e4-9d3b-3b3f159cbf52#ZXlKaGJHY2lPaUpTVXpJMU5pSXNJblI1Y0NJ..."
  }
  ```
</CodeGroup>

## Session options

You can customize the beneficiary management session by providing the `options` field in your request.
This allows you to restrict what a beneficiary can input.

The available options are:

| Field                   | Type       | Description                                                                                                                      |
| :---------------------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------- |
| `allowedRecipientTypes` | `string[]` | Limit the session to `INDIVIDUAL` or `BUSINESS` recipients. If omitted the user may pick either type.                            |
| `allowedCountries`      | `string[]` | List of ISO 3166 alpha‑2 country codes (e.g., `GB`, `US`). If omitted the user may add payout methods for any supported country. |

**Example with options**

[**POST** /beneficiaries/organizations/sessions](/api-reference/beneficiary-hub/create-management-session)

```json Request theme={null}
{
  "externalUserId": "1dda592e-5b1d-47d2-b1de-e772fca15327",
  "returnUrl": "https://tenant.tld/return-url",
  "options": {
    "allowedRecipientTypes": ["INDIVIDUAL"],
    "allowedCountries": ["GB", "DE"]
  }
}
```