# Get settlement account payouts

The GET /virtual-accounts/{accountId}/settlement-rule-payouts endpoint retrieves information about payouts created by a settlement rule, for a given settlement account.

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

## Path parameters:

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

## Request fields (application/json):

  - `accountId` (string)
    The settlement account id.
    Example: "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"

  - `limit` (integer)
    The maximum number of items to return in the response.
    Example: 10

  - `offset` (string)
    The offset of the first item to return in the response.
    Example: "LerV6Jmex"

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

  - `startDate` (string)
    The start date of the settlement rule payout.
    Example: "2024-01-01"

  - `endDate` (string)
    The end date of the settlement rule payout.
    Example: "2024-12-01"

  - `ids` (array)
    The list of payout ids.
    Example: ["123e4567-e89b-12d3-a456-426614174000"]

  - `invertIds` (boolean)
    If true, the response will contain all settlement rule payouts except those specified in the ids field.

  - `statuses` (array)
    The list of payout statuses.
    Example: ["INITIATION_PENDING","INITIATION_PROCESSING"]

  - `invertStatuses` (boolean)
    If true, the response will contain all settlement rule payouts except those specified in the statuses field.

  - `refIds` (array)
    The list of settlement payout reference ids.
    Example: ["ShBdcTeqFabqJJhUF"]

## Response 200 fields (application/json):

  - `pageInfo` (object)
    The information about the current page, which also indicates whether the next page exists.

  - `pageInfo.limit` (integer, required)
    The limit (maximum number of objects to return) applied to this page. The default and maximum allowed limit is 200. If this limit is exceeded, was not set or was set to 0, it will be set to 200.
    Example: 20

  - `pageInfo.offset` (string)
    The offset for the current page. If the offset has been provided in the request, this offset will be equal to the provided one. But if no offset is provided in the request (i.e. this is the first page) and the page is not empty, this field will be populated with a non-empty string. This may be helpful for loading the same page again, which might not always be possible with an empty offset due to the dynamic nature of the data. The offset is opaque to a user and should not be parsed and/or understood in any way.
    Example: "LerV6Jmex"

  - `pageInfo.nextOffset` (string)
    The offset for the next page. If the page is empty, it is equal to this page offset. If the page is not empty, but there are no more objects to load (haveMore = false), it will be empty.The offset is opaque to a user and should not be parsed and/or understood in any way.
    Example: "KgwG8Qkat"

  - `pageInfo.haveMore` (boolean)
    This field indicates whether there are more objects to load, i.e. whether the next page exists.

  - `payouts` (array)

  - `payouts.id` (string)
    The Token.io generated payout id.
    Example: "py:12345abcd:abcd"

  - `payouts.bankTransactionId` (string)
    The transaction id from the bank side. This can be empty if it is not available from the bank.
    Example: "2UhwCZ3BMaEcAUK8bZdukor7NL4tH6TBuu6aJMp5KKfX:5zKcENpV"

  - `payouts.memberId` (string)
    The Token.io-assigned member id of the TPP.
    Example: "m:123456abcd:abcd"

  - `payouts.createdDateTime` (string)
    The date and time this payout object was created The time this payment object was created (in ISO 8601 format).
    Example: "2024-04-05T00:00:00.000+00:00"

  - `payouts.updatedDateTime` (string)
    The date and time the current status, sub status, status reason information and authentication were last updated (in ISO 8601 format).
    Example: "2024-04-05T00:00:00.000+00:00"

  - `payouts.status` (string)
    The Token.io Payout Initiation Status.  INITIATION_PENDING - Token.io has received the payout initiation and the initiation passed Token.io validation.  INITIATION_PROCESSING - the payout is processing on the bank side. Status can be updated to one of INITIATION_COMPLETED, INITIATION_REJECTED or INITIATION_FAILED.If the status is never updated by the bank within certain period of time, the status will stay INITIATION_PROCESSING forever and the corresponding status reason information field will reflect this fact. INITIATION_COMPLETED - the payout initiation is successful. This does not guarantee the payout is settled. INITIATION_REJECTED - the payout is rejected by the bank. More details are shared in the corresponding status reason information.   INITIATION_FAILED - Token.io failed to create the initiation due to failures on the bank side, e.g. the bank is not available at the moment.
    Enum: "INITIATION_PENDING", "INITIATION_PROCESSING", "INITIATION_COMPLETED", "INITIATION_REJECTED", "INITIATION_FAILED"

  - `payouts.bankPaymentStatus` (string)
    The raw bank status. This can be the ISO 20022 payment status code. See ISO 20022 payment status codes for more information. This field can be empty if no payment status is available on bank side.
    Example: "ACPC"

  - `payouts.statusReasonInformation` (string)
    A human-readable description of the reason for the reported status, which may include a message from the bank. This value should not exceed 256 characters in length.
    Example: "The payment is settled on debtor side."

  - `payouts.initiation` (object)
    The initiation payload for the payout.

  - `payouts.initiation.description` (string, required)
    The payment reference, which must consist of at least 6 alphanumeric characters that are not all the same. Optional, uncounted characters include space, hyphen(-), full stop (.), ampersand(&), and forward slash (/). The total of all characters must be no greater than 18 for SCAN (Sort Code and Account Number) payments and 140 for iban payments.
    Example: "e49j-2145-sp17-k3h0"

  - `payouts.initiation.refId` (string, required)
    The TPP-generated reference identifier for the token. This is not to be confused with the requestId. The refId maps to the tppRefId in the bank's consentRequest. This is needed to match/verify the originating token request with the bank's consent request. We recommend that the refId should not contain special characters (the allowed characters are the 26-letter Latin alphabet, the numerical digits from 0-9 and the hyphen '-'). This field should not exceed 18 characters in length.
    Example: "9htio4a1sp2akdr1aa"

  - `payouts.initiation.onBehalfOfId` (string)
    The OnBehalfOfId is validated against the sub-TPP id of the member before initiating the payout. This field is mandatory for unregulated TPPs.
    Example: "c5a863bc-86f2-4418-a26f-25b24c7983c7"

  - `payouts.initiation.amount` (object, required)
    The transaction amount and currency.

  - `payouts.initiation.amount.value` (string, required)
    The transaction amount with up to four digits after the decimal point.
    Example: "10.23"

  - `payouts.initiation.amount.currency` (string, required)
    The ISO 4217 three letter currency code.
    Example: "EUR"

  - `payouts.initiation.debtor` (any, required)

  - `payouts.initiation.creditor` (object, required)
    The payout creditor object.

  - `payouts.initiation.creditor.name` (string)
    The owner's name for the creditor account.
    Example: "Customer Inc."

  - `payouts.initiation.creditor.ultimateCreditorName` (string)
    The ultimate creditor's name.
    Example: "Customer Inc."

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

  - `payouts.initiation.creditor.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"

  - `payouts.initiation.creditor.bic` (string)
    The Business Identifier Code (BIC), ISO 9362, is the 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 can be either 8 or 11 characters long.
    Example: "BOFIIE2D"

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

  - `payouts.initiation.creditor.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

  - `payouts.initiation.creditor.accountVerificationId` (string)
    The Id returned from the /account-verifications endpoint and used to identify the account verification relating to the beneficiary of the payment. Only required for EUR payments.

  - `payouts.reference` (string)
    The reference id of the payout.
    Example: "ShBdcTeqFabqJJhUF"

  - `payouts.description` (string)
    The description of the payout.
    Example: "Description of the payout"

  - `payouts.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 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"