# Create a payment run

Create a new payment run containing a list of outstanding supplier payments.

Note that all the supplier payments in a payment run is limited to one currency. The currency of the payment run are enabled upon the Buyer’s registration.


Required user role: CREATOR

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

## Header parameters:

  - `idempotency-ref` (string)
    A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

## Request fields (application/json):

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

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

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

  - `payments` (array, required)
    The list of payments associated with the payment run

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

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

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

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

  - `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

  - `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

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

  - `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))

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

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

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

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

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

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

## Response 200 fields (application/json):

  - `id` (string, required)

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

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

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

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

  - `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
    Enum: "QUEUED"

  - `statusReason` (string)

  - `payments` (array, required)

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

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

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

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

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

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

  - `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

  - `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

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

  - `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))

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

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

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

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

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

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

  - `payments.validationOutcomes` (array)

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

  - `payments.validationOutcomes.categoryResult` (object)

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

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

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

  - `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 409 fields (application/json):

  - `errorCode` (string)
    Enum: "BANK_ACCOUNT_CANNOT_BE_LINKED_ACCOUNT", "LINKED_ACCOUNT_INVALID_STATE", "BANK_ACCOUNT_CANNOT_BE_ZERO_BALANCE_ACCOUNT", "UNSUPPORTED_CURRENCY", "INVALID_SUPPLIER_BANK_ACCOUNT_DETAILS", "ZERO_BALANCE_ACCOUNT_INVALID_STATE", "IDEMPOTENT_REQUEST_IN_PROGRESS", "MISSING_SUPPLIER_TYPE"

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)


## Response 401 fields

## Response 413 fields

## Response 422 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields