Settlement Accounts

Create a settlement rule

Changed on

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

post/virtual-accounts/{accountId}/settlement-rule

Request

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

Path parameters

accountIdstring required

The system-generated, unique id which specifies the settlement account.

Request body

accountIdstring required

The system-generated, unique id which specifies the settlement account.

amountType'FIXED_VALUE' | 'PERCENTAGE' | 'BALANCE_TO_RETAIN' | 'PREVIOUS_DAY_TOTAL' required

The type of the amount.

amountValuestring required

The value of the amount.

timeInterval'INTRADAY' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY' required

The time interval.

effectiveFromstring

The start date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.

effectiveTostring

The end date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.

intradayIntervalHoursinteger required

The intraday interval hours.

intradayIntervalMinutesinteger

The intraday interval minutes.

onBehalfOfIdstring

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.

descriptionstring

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.

enableDynamicRefboolean

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)

Example request

{
  "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
  "payeeAccountDetails": {
    "name": "Customer Inc.",
    "ultimateCreditorName": "Customer Inc.",
    "accountNumber": "12345678",
    "bic": "HBUKGB7F261",
    "iban": "GB29NWBK60161331926819"
  },
  "effectiveFrom": "2024-01-01T12:34:56Z",
  "effectiveTo": "2024-12-01T12:34:56Z",
  "intradayIntervalHours": 2,
  "intradayIntervalMinutes": 10,
  "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
  "description": "Auto Payout",
  "enableDynamicRef": true
}

Response

Successful response

settlementRuleIdstring uuid

The id of the settlement rule.

Example response

{
  "settlementRuleId": "123e4567-e89b-12d3-a456-426614174000"
}

Changes

  • 4e8c473aff5cRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new PREVIOUS_DAY_TOTAL enum value to the request property