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

{
  "externalUserId": "1dda592e-5b1d-47d2-b1de-e772fca15327",
  "returnUrl": "https://tenant.tld/return-url"
}

{
  "id": "4479b65d-a33b-43e4-9d3b-3b3f159cbf52",
  "url": "https://payouts.tenant.tld/sessions/4479b65d-a33b-43e4-9d3b-3b3f159cbf52#ZXlKaGJHY2lPaUpTVXpJMU5pSXNJblI1Y0NJ..."
}

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

Request

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

Get Started

Payment Preparation

Beneficiary Hub

Webhooks

Create a session

Session options

​Create a session

​Session options

Create a session

Session options