# Settlement Rules

### Introduction

The Settlement Rules feature enables **Third-Party Providers
(TPPs)** to automate the initiation of transfers from their settlement
accounts at defined intervals.
A settlement rule can be:

- A fixed amount
- A percentage of the remaining balance
- A float amount (a defined minimum balance is kept in a settlement account)


Rules can occur intraday , daily, weekly, monthly,
quarterly, every six months, or annually.

Settlement rules can be set up via the Dashboard or via API.

## Functional Overview

- **Single Rule per Account:**
Only one settlement rule can be set up per virtual account. Attempts
to create additional rules for the same account are rejected.
- **Rule Modification:**
Settlement rules can be updated. Changes take effect from the next
scheduled execution.
- **Rule Deletion:**
Settlement rules can be deleted at any time. Payments already
initiated will continue processing and are not cancelled.
- **Validation:**
All API requests are validated for required fields and business
rules.
- **Error Handling:**
The API provides meaningful error responses for invalid input or
business rule violations.
- **Rule Execution:**
Daily and other non-intraday rules run on a schedule and are executed based on their next execution date, triggered shortly after midnight.


## API Endpoints

### Create Settlement Rule

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

br
The settlement rule creation request includes the following parameter:

- Payer account
- Payee details
- Amount type (fixed, percentage or float)
- Value
- Effective dates
- Interval


Upon the settlement rule being created successfully, a **settlement rule ID** will be provided in the API response.

br
**Example Request:**


```json
{
  "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
  "payeeAccountDetails": {
    "name": "Customer Inc.",
    "ultimateCreditorName": "Customer Inc.",
    "bankName": "string",
    "accountNumber": "12345678",
    "bic": "HBUKGB7F261",
    "iban": "GB29NWBK60161331926819",
    "sortCode": 123456
  },
  "amountType": "FIXED_VALUE",
  "amountValue": 10,
  "timeInterval": "INTRADAY",
  "effectiveFrom": "2024-01-01T12:34:56Z",
  "effectiveTo": "2024-12-01T12:34:56Z",
  "intradayIntervalHours": 2,
  "intradayIntervalMinutes": 10,
  "description": "Auto Payout"
}
```

br
**Example Response:**


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

### Retrieve Settlement Rule

`GET /virtual-accounts/{account_id}/settlement-rule`

br
Returns the current settlement rule for the specified account. The response will also highlight if the rule is **"ACTIVE"** or **"INACTIVE"**.

br
**Example Response:**


```json
{
  "settlementRule": [
    {
      "settlementRuleId": "c65e5548-682b-4c4e-b000-f496e06d1082",
      "payerAccountId": "string",
      "payeeAccountDetails": {
        "name": "Customer Inc.",
        "ultimateCreditorName": "Customer Inc.",
        "bankName": "string",
        "accountNumber": "12345678",
        "bic": "HBUKGB7F261",
        "iban": "GB29NWBK60161331926819",
        "sortCode": 123456
      },
      "amountType": "FIXED_VALUE",
      "amountValue": "string",
      "effectiveFrom": "string",
      "effectiveTo": "string",
      "timeInterval": "INTRADAY",
      "description": "Auto Payout",
      "status": "ACTIVE"
    }
  ]
}
```

### Delete Settlement Rule

`DELETE /virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id}`

br
Removes the specified settlement rule. If successful, a **HTTP 200** response code will be received with an empty body.

### Retrieve Payments Initiated by a Settlement Rule

`GET /virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id}/payouts`

br
Retrieves a list of payments initiated under a specific settlement rule.

**Example Request:**


```json
{
  "accountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV",
  "limit": 10,
  "offset": "LerV6Jmex",
  "settlementRuleId": "123e4567-e89b-12d3-a456-426614174000",
  "startDate": "2024-01-01",
  "endDate": "2024-12-01",
  "ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "invertIds": false,
  "statuses": [
    "INITIATION_PENDING",
    "INITIATION_PROCESSING"
  ],
  "invertStatuses": false,
  "refIds": [
    "ShBdcTeqFabqJJhUF"
  ]
}
```

br
**Example Response:**

br

```json
{
  "pageInfo": {
    "limit": 20,
    "offset": "LerV6Jmex",
    "nextOffset": "KgwG8Qkat",
    "haveMore": false
  },
  "payouts": [
    {
      "id": "py:12345abcd:abcd",
      "bankTransactionId": "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV",
      "memberId": "m:123456abcd:abcd",
      "createdDateTime": "2024-04-05T00:00:00.000+00:00",
      "updatedDateTime": "2024-04-05T00:00:00.000+00:00",
      "status": "INITIATION_COMPLETED",
      "bankPaymentStatus": "ACPC",
      "statusReasonInformation": "The payment is settled on debtor side.",
      "initiation": {
        "description": "e49j-2145-sp17-k3h0",
        "refId": "9htio4a1sp2akdr1aa",
        "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
        "amount": {
          "value": "10.23",
          "currency": "EUR"
        },
        "debtor": {
          "accountId": "a12345"
        },
        "creditor": {
          "name": "Customer Inc.",
          "ultimateCreditorName": "Customer Inc.",
          "bankName": "string",
          "iban": "GB29NWBK60161331926819",
          "bic": "BOFIIE2D",
          "accountNumber": "12345678",
          "sortCode": 123456,
          "accountVerificationId": "string"
        }
      },
      "reference": "ShBdcTeqFabqJJhUF",
      "description": "Description of the payout",
      "settlementRuleId": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}
```

## Dashboard - User Interface in 5 Steps

The following outlines the process of setting up a Settlement Rule
within the Dashboard.

1. **Access the Virtual Account view** in the Dashboard.


1. **View the Account Details**, then navigate to **"View
Transactions"** in the top right.


1. **View the Transaction list** for the Virtual Account.
Select **"Set up new Settlement Rules"** in the top right.
You will be presented with fields as follows:
  - UK accounts: standard fields
  - EU accounts: IBAN / BIC fields
  - Confirm rule creation once the relevant information is added.


1. **Confirm the Rule creation** - the rule details will appear.
If previous rules exist, they will also be visible.


1. **Delete or update the rule** from the top right corner and set up a
new one if needed.


## Further Reading

Comprehensive documentation is provided for all endpoints, including
full API specifications:

🔗 [Token Open Banking API - Settlement
Accounts](https://reference.token.io/tag/Settlement-Accounts)

If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)