# Create a settlement rule

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

Endpoint: POST /virtual-accounts/{accountId}/settlement-rule
Security: Bearer, BasicAuth

## Path parameters:

  - `accountId` (string, required)
    The system-generated, unique id which specifies the settlement account.

## Request fields (application/json):

  - `accountId` (string, required)
    The system-generated, unique id which specifies the settlement account.
    Example: "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"

  - `payeeAccountDetails` (object, required)

  - `payeeAccountDetails.name` (string)
    The owner name for the creditor account.
    Example: "Customer Inc."

  - `payeeAccountDetails.ultimateCreditorName` (string)
    The ultimate creditor name.
    Example: "Customer Inc."

  - `payeeAccountDetails.bankName` (string)
    The creditor's bank name.

  - `payeeAccountDetails.accountNumber` (string)
    The unique identifier for the bank account in the UK or Ireland.
    Example: "12345678"

  - `payeeAccountDetails.bic` (string)
    The Business Identifier Code (BIC), ISO 9362, 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."
    Example: "HBUKGB7F261"

  - `payeeAccountDetails.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.
    Example: "GB29NWBK60161331926819"

  - `payeeAccountDetails.sortCode` (string)
    The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland.
    Example: 123456

  - `amountType` (string, required)
    The type of the amount.
    Enum: "FIXED_VALUE", "PERCENTAGE", "BALANCE_TO_RETAIN"

  - `amountValue` (string, required)
    The value of the amount.
    Example: 10

  - `timeInterval` (string, required)
    The time interval.
    Enum: "INTRADAY", "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "HALF_YEARLY", "YEARLY"

  - `effectiveFrom` (string)
    The start date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.
    Example: "2024-01-01T12:34:56Z"

  - `effectiveTo` (string)
    The end date of the settlement rule is formatted as YYYY-MM-DDTHH:MM:SSZ.
    Example: "2024-12-01T12:34:56Z"

  - `intradayIntervalHours` (integer, required)
    The intraday interval hours.
    Example: 2

  - `intradayIntervalMinutes` (integer)
    The intraday interval minutes.
    Example: 10

  - `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 (/).
    Example: "Auto Payout"

## Response 200 fields (application/json):

  - `settlementRuleId` (string)
    The id of the settlement rule.
    Example: "123e4567-e89b-12d3-a456-426614174000"

## Response 400 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 401 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 403 fields (application/json):

  - `error` (object, required)
    The error returned when the member is not authorized to perform the given operation: PermissionDenied. This error message will be accompanied by the reason from the bank. Typically this means the access token has expired and the user must re-authenticate with the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 404 fields (application/json):

  - `error` (object, required)
    The error object returned when given payment cannot be found: ResourceNotFound.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The requested entity, the paymentID, was not found.
    Example: "pm2:12345abcd:abcde"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 429 fields (application/json):

  - `error` (object, required)
    Resource exhausted. Too many requests.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The maximum number of requests has been reached.
    Example: "Resource exhausted. Check quota."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 500 fields (application/json):

  - `error` (object)
    This could refer to either an error by the payment service provider or the bank. When the bank reports a 5xx error, "token-external-error": "true" is set as a header in the HTTP response, indicating that the "internal" error originates from the bank. When one of the payment service providers internal services fails or when the bank reports a 4xx error, this header is not populated. The absence of this response header should be interpreted as "token-external-error": "false".

  - `error.errorCode` (string, required)
    This is a textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 501 fields (application/json):

  - `error` (object, required)
    The operation was not implemented, supported or enabled by the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The operation was not implemented,supported or enabled by the bank.
    Example: "Not implemented."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 503 fields (application/json):

  - `error` (object, required)
    Service is unavailable, likely due to a transient condition; this is usually corrected with a retry.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The service is unavailable, likely due to a transient condition; this is usually corrected with a retry.
    Example: "Unavailable"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 504 fields (application/json):

  - `error` (object, required)
    The deadline expired before the operation could complete.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The deadline expired before the operation could complete.
    Example: "Deadline exceeded."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"