# Get payment runs

Retrieve the list of payment runs belonging to the buyer that the logged-in user belongs to.

Required user roles: CONTROLLER OR CREATOR

Endpoint: GET /v1/payment_runs
Version: v1
Security: apiKey, authToken

## Query parameters:

  - `limit` (integer)
    The limit of the results for paging, starting at the offset. Limit is always capped at 100.

  - `offset` (integer)
    The offset value for paging, indicating the initial item number to be returned from the data set satisfying the given criteria. Leave out to fetch the first page of results.

  - `tag` (array)
    Filter by tag. The exact tag must be provided, as wildcards are not supported. Leave out to fetch all entries.

  - `status` (string)
    The status of the payment run.
    Enum: "QUEUED", "CANCELLED", "COMPLETED", "COMPLETED_WITH_ERRORS", "EXECUTING", "INVALID", "PENDING_CHALLENGE", "PENDING_CONFIRMATION", "PENDING_FUNDING", "SCA_FAILED"

  - `reference` (string)
    The unique paymentRunRef of the payment run.

  - `min_amount` (integer)
    The minimum total amount of the payment run.

  - `max_amount` (integer)
    The maximum total amount of the payment run.

## Response 200 fields (application/json):

  - `count` (integer, required)
    The total number of records (excluding the paging limit)
    Example: 10

  - `responseCount` (integer, required)
    The total number of records returned in this response (always capped at 100).
    Example: 100

  - `paymentRuns` (array, required)

  - `paymentRuns.id` (string, required)

  - `paymentRuns.paymentRunRef` (string)
    A unique identifier by which you identify the payment run with on your system.
    Example: "94fddfb2-297d-423d-9157-4200b7beb834"

  - `paymentRuns.tag` (string)
    The tag field is a custom field that can be used to search and filter.

  - `paymentRuns.description` (string)
    The long form description of the payment run
    Example: "September payment run 01"

  - `paymentRuns.createdBy` (string, required)
    Example: "110747174434373672"

  - `paymentRuns.status` (string, required)
    The current status of the payment run.

- QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validated
- CANCELLED: Payment run was manually cancelled
- COMPLETED: All payments have been executed successfully
- COMPLETED_WITH_ERRORS: All payments have been executed and some failed
- EXECUTING: Funds received, executing payments
- INVALID: Payment run is invalid
- PENDING_CHALLENGE: Waiting for the payment run to complete the SCA challenge
- PENDING_CONFIRMATION: Payment run is pending confirmation by a CONTROLLER user
- PENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the /payment_runs/{id}/fund endpoint
- SCA_FAILED: Payment run failed due to SCA either expiring or max attempts reached. You can restart the payment run by calling the /payment_runs/{id}/restart endpoint
    Enum: "QUEUED", "CANCELLED", "COMPLETED", "COMPLETED_WITH_ERRORS", "EXECUTING", "INVALID", "PENDING_CHALLENGE", "PENDING_CONFIRMATION", "PENDING_FUNDING", "SCA_FAILED"

  - `paymentRuns.statusReason` (string)

  - `paymentRuns.payments` (array, required)

  - `paymentRuns.payments.id` (string, required)
    The unique identifier of the payment line

  - `paymentRuns.payments.status` (string, required)
    The status of the payment

- QUEUED: The payment run creation is an asynchronous process. This status indicates that the payment run is currently being validated
- PENDING_CHALLENGE: Waiting for the payment run to complete the SCA challenge
- PENDING_FUNDING: Pending until the necessary funds are initiated. Initiate the funding process via the /payment_runs/{id}/fund endpoint
- AWAITING_FUNDS: Waiting for the required funds to be available to execute payment
- EXECUTING: Payment is being executed and awaiting final status confirmation
- COMPLETED: Payment executed successfully
- FAILED: Payment executed, but failed
- CANCELLED: Payment cancelled, because payment run was cancelled
- PENDING_CONFIRMATION: Payment run is pending confirmation by a CONTROLLER user
- RETURNED: Payment sent, but was returned back
- SCA_FAILED: Payment run failed due to SCA either expiring or max attempts reached. You can restart the payment run by calling the /payment_runs/{id}/restart endpoint
    Enum: "QUEUED", "CANCELLED", "COMPLETED", "FAILED", "PENDING_CHALLENGE", "PENDING_CONFIRMATION", "PENDING_FUNDING", "RETURNED", "AWAITING_FUNDS", "EXECUTING", "SCA_FAILED"

  - `paymentRuns.payments.externalRef` (string)
    The unique identifier by which you identify the associated payable on your system.
    Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"

  - `paymentRuns.payments.paymentRef` (string)
    The unique identifier by which you identify this payment on your system.
    Example: "c99cd66c-82fc-4a01-977b-61a2f5a247a1"

  - `paymentRuns.payments.paymentAmount` (object, required)
    The currency and amount to be paid to the supplier.

  - `paymentRuns.payments.paymentAmount.currency` (string, required)
    The currency expressed in ISO-4217 code.
    Enum: "GBP", "EUR"

  - `paymentRuns.payments.paymentAmount.amount` (integer, required)
    The monetary amount, scaled to the lowest denomination of the currency.

Example, an amount of 1000 for a GBP currency is actually 1000 pennies or GBP 10.00.
    Example: 454321

  - `paymentRuns.payments.reference` (string, required)
    The long form description of the payment. This information is also shared with the supplier. The allowed length is dependent on the payment type:
SEPA and SWIFT <= 35 characters
Faster Payments <= 18 characters

  - `paymentRuns.payments.supplier` (object, required)
    Represent the supplier bank account typically used in Outgoing Wire Transfer transactions.

  - `paymentRuns.payments.supplier.name` (string, required)
    The supplier name. The allowed length and pattern is dependent on the bankAccountDetails type:
 with SepaBankDetails: >= 1 character and = 1 character and ;{@\r\n]$
(please note that the ’` symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

  - `paymentRuns.payments.supplier.address` (string)
    The supplier's address.

  - `paymentRuns.payments.supplier.bankName` (string)
    The supplier's bank name.

  - `paymentRuns.payments.supplier.bankAddress` (string)
    The supplier's bank address.

  - `paymentRuns.payments.supplier.bankCountry` (string)
    The supplier's bank country in ISO 3166 alpha-2 format.

  - `paymentRuns.payments.supplier.type` (string)
    The type of supplier account. Required only when FasterPaymentsBankDetails are specified.
    Enum: "PERSONAL", "BUSINESS"

  - `paymentRuns.payments.supplier.bankAccountDetails` (any, required)
    Details of the supplier bank account, depending on the type of transfer chosen.

  - `paymentRuns.payments.validationOutcomes` (array)

  - `paymentRuns.payments.validationOutcomes.category` (string)
    Enum: "UK_CONFIRMATION_OF_PAYEE"

  - `paymentRuns.payments.validationOutcomes.categoryResult` (object)

  - `paymentRuns.payments.validationOutcomes.categoryResult.match` (string)
    The result of matching performed by the UK Confirmation of Payee responder
    Enum: "EXACT_MATCH", "CLOSE_MATCH", "NO_MATCH"

  - `paymentRuns.payments.validationOutcomes.categoryResult.reasonCode` (string)
    The reason why the matching failed at the UK Confirmation of Payee responder:

  - ANNM: The CoP responder confirms that the account name provided does not match;
  - MBAM: The CoP responder indicates that the account name provided closely matches the actual account in its records, the actual account name is returned in the accountName field;
  - BANM: The account type that the user specified is 'PERSONAL', but the CoP responder indicates that the actual account matching the name provided is actually BUSINESS;
  - PANM: The account type that the user specified is 'BUSINESS', but the CoP responder indicates that the actual account matching the name provided is actually PERSONAL;
  - BAMM: The account type that the user specified is 'PERSONAL', but the CoP responder indicates that an account closely matching the name provided is BUSINESS;
  - PAMM: The account type that the user specified is 'BUSINESS', but the CoP responder indicates that an account closely matching the name provided is PERSONAL;
  - AC01: The account does not exist in the CoP responders books, the accountNumber specified is likely incorrect; 
  - IVCR: The CoP responder was unable to locate an account based on the secondaryReference field;
  - ACNS: The account is not supported for CoP by the CoP responder;
  - OPTO: The owner of the account has opted out of CoP service by the CoP responder;
  - CASS: The account has been switched using the Current Account Switch Service;
  - SCNS: The sortCode provided is not supported at endpoint;
    Enum: "ANNM", "MBAM", "BANM", "PANM", "BAMM", "PAMM", "AC01", "IVCR", "ACNS", "OPTO", "CASS", "SCNS"

  - `paymentRuns.payments.validationOutcomes.categoryResult.accountName` (string)
    Returned when there is match is a CLOSE_MATCH and the reasonCode is MBAM, BAMM or PAMM

  - `paymentRuns.createdAt` (string, required)

## Response 400 fields (application/json):

  - `message` (string)
    When present helps to identify and fix the problem.

  - `syntaxErrors` (object)
    Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.

  - `syntaxErrors.invalidFields` (array)

  - `syntaxErrors.invalidFields.params` (array)

  - `syntaxErrors.invalidFields.fieldName` (string)

  - `syntaxErrors.invalidFields.error` (string)
    Enum: "REQUIRED", "HAS_TEXT", "REQUIRES", "SIZE", "RANGE", "IN", "NOT_IN", "REGEX", "EXACTLY", "AT_LEAST", "AT_MOST", "ALL_OR_NONE"

## Response 403 fields (application/json):

  - `errorCode` (string)
    Enum: "INSUFFICIENT_PERMISSIONS"

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)


## Response 401 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields