---
title: "Create a settlement rule"
method: POST
path: "/virtual-accounts/{accountId}/settlement-rule"
tags: ["Settlement Accounts"]
---

# Create a settlement rule

`POST /virtual-accounts/{accountId}/settlement-rule`

## Request

- Base URL: `https://api.token.io`
- URL: `https://api.token.io/virtual-accounts/{accountId}/settlement-rule`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

The `POST /virtual-accounts/{accountId}/settlement-rule` endpoint creates a settlement rule, for a given settlement account.

## Path parameters

- `accountId` string, required

## Request body

- CreateVirtualAccountSettlementRuleRequest: Contains the request payload to create a settlement rule.
  - `accountId` string, required: The system-generated, unique id which specifies the settlement account.
  - `payeeAccountDetails` Creditor, required
    - `name` string: The owner name for the creditor account.
    - `ultimateCreditorName` string: The ultimate creditor name.
    - `bankName` string: The creditor's bank name.
    - `accountNumber` string: The unique identifier for the bank account in the UK or Ireland.
    - `bic` string: The Business Identifier Code (BIC), <a href="https://www.iso.org/standard/84108.html" target="_blank">ISO 9362</a>, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long."
    - `iban` string: The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters.
    - `sortCode` string: The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland.
  - `amountType` 'FIXED_VALUE' | 'PERCENTAGE' | 'BALANCE_TO_RETAIN' | 'PREVIOUS_DAY_TOTAL', required: The type of the amount.
  - `amountValue` string, required: The value of the amount.
  - `timeInterval` 'INTRADAY' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY', required: The time interval.
  - `effectiveFrom` string: The start date of the settlement rule is formatted as `YYYY-MM-DDTHH:MM:SSZ`.
  - `effectiveTo` string: The end date of the settlement rule is formatted as `YYYY-MM-DDTHH:MM:SSZ`.
  - `intradayIntervalHours` integer, required: The intraday interval hours.
  - `intradayIntervalMinutes` integer: The intraday interval minutes.
  - `onBehalfOfId` string: The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field will contain the sub-TPP `referenceId`. This field is mandatory for unregulated TPPs.
  - `description` string: The description used for payouts created due to this rule. The maximum length is 18 characters and allowed characters are alphanumeric, space, hyphen (-), period (.), ampersand (&), and forward slash (/). The minimum length is 6 characters. **NOTE**: When enableDynamicRef is true the maximum length is 9 characters.
  - `enableDynamicRef` boolean: Controls how the reference is generated for a payout created as the result of a triggered settlement rule. When set to true, the payment reference is automatically generated by combining "description" with the current date, separated by a hyphen, in the format "{description}-{DDMMYYYY}," where DDMMYYYY is the zero-padded date the payout was created (e.g. 01082026 for 1 August 2026)

## Response `200`

Successful response

- CreateVirtualAccountSettlementRuleResponse: Contains the response of the create a settlement rule request.
  - `settlementRuleId` string, uuid: The id of the settlement rule.

## Other responses

- `400`: The client specified an invalid argument
- `401`: The authorization information is missing or invalid
- `403`: Permission to access this endpoint is denied
- `404`: The requested entity, such as an account, was not found
- `429`: Too many requests
- `500`: An unexpected or internal server error
- `501`: The operation was not implemented
- `503`: Service is unavailable
- `504`: Gateway has timed out

## Changes

- **2026-09-17** `4e8c473aff5c`: 3 info
  - added the new optional request property `enableDynamicRef`
  - added the new optional request property `onBehalfOfId`
  - added the new `PREVIOUS_DAY_TOTAL` enum value to the request property `amountType`

[Operation history](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps/changes/virtual-accounts/:accountId/settlement-rule/post.md)

---

[API](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps.md) - [All operations](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps/llms.txt) - [OpenAPI document](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps/revisions/f705d3537678?raw)