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
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.
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.
POST /virtual-accounts/{account_id}/settlement-rule
The settlement rule creation request includes the following parameter:
- Payer account
- Payee details
- Amount type (fixed or percentage)
- Value
- Effective dates
- Interval
Upon the settlement rule being created successfully, a settlement rule ID will be provided in the API response.
Example Request:
{
"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"
}Example Response:
{
"settlementRuleId": "123e4567-e89b-12d3-a456-426614174000"
}GET /virtual-accounts/{account_id}/settlement-rule
Returns the current settlement rule for the specified account. The response will also highlight if the rule is "ACTIVE" or "INACTIVE".
Example Response:
{
"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 /virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id}
Removes the specified settlement rule. If successful, a HTTP 200 response code will be received with an empty body.
GET /virtual-accounts/{account_id}/settlement-rules/{settlement_rule_id}/payouts
Retrieves a list of payments initiated under a specific settlement rule.
Example Request:
{
"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"
]
}Example Response:
{
"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"
}
]
}The following outlines the process of setting up a Settlement Rule within the Dashboard.
- Access the Virtual Account view in the Dashboard.
- View the Account Details, then navigate to "View Transactions" in the top right.
- 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.
- Confirm the Rule creation - the rule details will appear. If previous rules exist, they will also be visible.
- Delete or update the rule from the top right corner and set up a new one if needed.
Comprehensive documentation is provided for all endpoints, including full API specifications:
🔗 Token Open Banking API - Settlement Accounts
If you have any feedback about the developer documentation, please contact devdocs@token.io