Weavr

Weavr Payment runs API

A Payment run contains a list of supplier payments. A Payment run can be - created by a user with a `CREATOR` role - confirmed by a user with a `CONTROLLER` role - funded by a user with a `CONTROLLER` role Note that the Controller user must have their mobile device enrolled to SCA. Before a payment run can be executed, it must be funded. Users with the `CONTROLLER` role must link their company's bank account(s) that are represented as Linked Accounts, which than can be used as the funding source for a payment run. Depending on the bank's constraints it may not be possible to deposit the total amount of funds required for a payment run, in which case the payment run will be automatically split into funding groups. All funding groups must be funded and executed for the payment run to be marked as completed. Note that even if the payment is created successfully, you still need to check its status in order to determine if it is `completed` or`failed`.

GitHub OpenAPI

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/weavr/refs/heads/main/openapi/weavr-payment-runs-api-openapi.yml

OpenAPI Specification

weavr-payment-runs-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  version: v3
  title: Weavr Multi Product BackOffice Access Token Payment runs API
  x-logo:
    url: https://storage.googleapis.com/weavr-cdn/weavr_logo-new.png
    backgroundColor: '#FFFFFF'
    altText: Weavr
  description: 'Weavr Multi Back Office API allows you, as an innovator, to perform various back office operations concerning

    identities and their instruments, without requiring the users to be logged in.


    A token is to be obtained through the `access_token` method, and this will allow relevant operations

    to be performed on behalf of this same identity.

    '
  contact:
    name: Weavr
    url: https://weavr.io
servers:
- description: Weavr Sandbox Environment
  url: https://sandbox.weavr.io/multi/backoffice
tags:
- name: Payment runs
  description: "A Payment run contains a list of supplier payments. A Payment run can be \n- created by a user with a `CREATOR` role \n- confirmed by a user with a `CONTROLLER` role\n- funded by a user with a `CONTROLLER` role\n\nNote that the Controller user must have their mobile device enrolled to SCA. \n\nBefore a payment run can be executed, it must be funded. Users with the `CONTROLLER` role must link their company's bank account(s) that are represented as Linked Accounts, which than can be used as the funding source for a payment run.\n\nDepending on the bank's constraints it may not be possible to deposit the total amount of funds required for a payment run, in which case the payment run will be automatically split into funding groups. All funding groups must be funded and executed for the payment run to be marked as completed. \n\nNote that even if the payment is created successfully, you still need to check its status in order to determine if it is `completed` or`failed`.\n"
paths:
  /v1/payment_runs:
    post:
      description: '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`'
      operationId: postPaymentRun
      summary: Create a payment run
      tags:
      - Payment runs
      parameters:
      - in: header
        name: idempotency-ref
        description: 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.
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: PaymentRunCreate
              required:
              - payments
              properties:
                paymentRunRef:
                  type: string
                  description: A unique identifier by which you identify the payment run with on your system.
                  example: 94fddfb2-297d-423d-9157-4200b7beb834
                tag:
                  type: string
                  description: The tag field is a custom field that can be used to search and filter.
                  maxLength: 50
                  pattern: ^[a-zA-Z0-9_-]+$
                description:
                  type: string
                  description: The long form description of the payment run
                  example: September payment run 01
                payments:
                  description: The list of payments associated with the payment run
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    type: object
                    title: Payment
                    required:
                    - amount
                    - currency
                    - reference
                    - payee
                    - paymentAmount
                    - supplier
                    properties:
                      externalRef:
                        type: string
                        example: c99cd66c-82fc-4a01-977b-61a2f5a247a1
                        description: The unique identifier by which you identify the associated payable on your system.
                      paymentRef:
                        type: string
                        example: c99cd66c-82fc-4a01-977b-61a2f5a247a1
                        description: The unique identifier by which you identify this payment on your system.
                      paymentAmount:
                        description: The currency and amount to be paid to the supplier.
                        allOf:
                        - description: The object representing a monetary amount in a particular currency
                          required:
                          - currency
                          - amount
                          type: object
                          properties:
                            currency:
                              type: string
                              description: The currency expressed in ISO-4217 code.
                              maxLength: 3
                              minLength: 3
                              enum:
                              - GBP
                              - EUR
                            amount:
                              type: integer
                              format: int64
                              example: 454321
                              description: '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.

                                '
                        - type: object
                          properties:
                            amount:
                              type: integer
                              minimum: 1
                      reference:
                        type: string
                        maxLength: 18
                        minLength: 1
                        pattern: ^[0-9a-zA-Z.-]{1,18}$
                        description: '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

                          '
                      supplier:
                        required:
                        - bankAccountDetails
                        - name
                        type: object
                        description: Represent the supplier bank account typically used in Outgoing Wire Transfer transactions.
                        properties:
                          name:
                            type: string
                            minLength: 1
                            maxLength: 140
                            pattern: ^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;{@\r\n]*$
                            description: 'The supplier name. The allowed length and pattern is dependent on the `bankAccountDetails` type:

                              * with `SepaBankDetails`: >= `1` character and <= `150` characters

                              * with `FasterPaymentsBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;{@\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))

                              '
                          address:
                            maxLength: 150
                            minLength: 1
                            type: string
                            description: The supplier's address.
                          bankName:
                            type: string
                            description: The supplier's bank name.
                          bankAddress:
                            maxLength: 150
                            minLength: 1
                            type: string
                            description: The supplier's bank address.
                          bankCountry:
                            type: string
                            description: The supplier's bank country in ISO 3166 alpha-2 format.
                            maxLength: 2
                            minLength: 2
                            pattern: ^[A-Z]{2}$
                          type:
                            type: string
                            description: The type of supplier account. Required only when FasterPaymentsBankDetails are specified.
                            enum:
                            - PERSONAL
                            - BUSINESS
                          bankAccountDetails:
                            description: Details of the supplier bank account, depending on the type of transfer chosen.
                            oneOf:
                            - title: FasterPaymentsBankDetails
                              required:
                              - accountNumber
                              - sortCode
                              type: object
                              description: Bank details used in case the wire transfer is executed over Faster Payments.
                              properties:
                                accountNumber:
                                  type: string
                                  minLength: 8
                                  maxLength: 8
                                  pattern: ^[0-9]{8}$
                                  description: Account number, required for wire transfer over Faster Payments.
                                sortCode:
                                  type: string
                                  minLength: 6
                                  maxLength: 6
                                  pattern: ^[0-9]{6}$
                                  description: Sort code, required for wire transfer over Faster Payments.
                                secondaryReference:
                                  type: string
                                  description: Secondary reference data if applicable.
                            - title: SepaBankDetails
                              required:
                              - iban
                              type: object
                              description: Bank details used in case the wire transfer is executed over SEPA.
                              properties:
                                iban:
                                  type: string
                                  minLength: 15
                                  maxLength: 34
                                  pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$
                                  description: International Bank Account Number, required for wire transfer over SEPA.
                                bankIdentifierCode:
                                  type: string
                                  minLength: 8
                                  maxLength: 11
                                  pattern: ^[a-zA-Z0-9]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}[a-zA-Z0-9]{0,3}$
                                  description: BIC, for wire transfer over SEPA.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - payments
                - id
                - status
                - createdAt
                - buyerId
                - createdBy
                title: PaymentRun
                properties:
                  id:
                    type: string
                    pattern: ^[0-9a-fA-F]{24}$
                    readOnly: true
                  paymentRunRef:
                    type: string
                    description: A unique identifier by which you identify the payment run with on your system.
                    example: 94fddfb2-297d-423d-9157-4200b7beb834
                  tag:
                    type: string
                    description: The tag field is a custom field that can be used to search and filter.
                    maxLength: 50
                    pattern: ^[a-zA-Z0-9_-]+$
                  description:
                    type: string
                    description: The long form description of the payment run
                    example: September payment run 01
                  createdBy:
                    type: string
                    pattern: ^[0-9]+$
                    example: '110747174434373672'
                    readOnly: true
                  status:
                    type: string
                    enum:
                    - QUEUED
                    example: PENDING_CONFIRMATION
                    description: '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

                      '
                    readOnly: true
                  statusReason:
                    type: string
                  payments:
                    type: array
                    items:
                      type: object
                      title: Payment
                      required:
                      - id
                      - status
                      allOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            description: The unique identifier of the payment line
                            readOnly: true
                          status:
                            type: string
                            enum:
                            - QUEUED
                            - CANCELLED
                            - COMPLETED
                            - FAILED
                            - PENDING_CHALLENGE
                            - PENDING_CONFIRMATION
                            - PENDING_FUNDING
                            - RETURNED
                            - AWAITING_FUNDS
                            - EXECUTING
                            - SCA_FAILED
                            description: '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

                              '
                            readOnly: true
                      - type: object
                        title: Payment
                        required:
                        - amount
                        - currency
                        - reference
                        - payee
                        - paymentAmount
                        - supplier
                        properties:
                          externalRef:
                            type: string
                            example: c99cd66c-82fc-4a01-977b-61a2f5a247a1
                            description: The unique identifier by which you identify the associated payable on your system.
                          paymentRef:
                            type: string
                            example: c99cd66c-82fc-4a01-977b-61a2f5a247a1
                            description: The unique identifier by which you identify this payment on your system.
                          paymentAmount:
                            description: The currency and amount to be paid to the supplier.
                            allOf:
                            - description: The object representing a monetary amount in a particular currency
                              required:
                              - currency
                              - amount
                              type: object
                              properties:
                                currency:
                                  type: string
                                  description: The currency expressed in ISO-4217 code.
                                  maxLength: 3
                                  minLength: 3
                                  enum:
                                  - GBP
                                  - EUR
                                amount:
                                  type: integer
                                  format: int64
                                  example: 454321
                                  description: '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.

                                    '
                            - type: object
                              properties:
                                amount:
                                  type: integer
                                  minimum: 1
                          reference:
                            type: string
                            maxLength: 18
                            minLength: 1
                            pattern: ^[0-9a-zA-Z.-]{1,18}$
                            description: '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

                              '
                          supplier:
                            required:
                            - bankAccountDetails
                            - name
                            type: object
                            description: Represent the supplier bank account typically used in Outgoing Wire Transfer transactions.
                            properties:
                              name:
                                type: string
                                minLength: 1
                                maxLength: 140
                                pattern: ^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;{@\r\n]*$
                                description: 'The supplier name. The allowed length and pattern is dependent on the `bankAccountDetails` type:

                                  * with `SepaBankDetails`: >= `1` character and <= `150` characters

                                  * with `FasterPaymentsBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;{@\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))

                                  '
                              address:
                                maxLength: 150
                                minLength: 1
                                type: string
                                description: The supplier's address.
                              bankName:
                                type: string
                                description: The supplier's bank name.
                              bankAddress:
                                maxLength: 150
                                minLength: 1
                                type: string
                                description: The supplier's bank address.
                              bankCountry:
                                type: string
                                description: The supplier's bank country in ISO 3166 alpha-2 format.
                                maxLength: 2
                                minLength: 2
                                pattern: ^[A-Z]{2}$
                              type:
                                type: string
                                description: The type of supplier account. Required only when FasterPaymentsBankDetails are specified.
                                enum:
                                - PERSONAL
                                - BUSINESS
                              bankAccountDetails:
                                description: Details of the supplier bank account, depending on the type of transfer chosen.
                                oneOf:
                                - title: FasterPaymentsBankDetails
                                  required:
                                  - accountNumber
                                  - sortCode
                                  type: object
                                  description: Bank details used in case the wire transfer is executed over Faster Payments.
                                  properties:
                                    accountNumber:
                                      type: string
                                      minLength: 8
                                      maxLength: 8
                                      pattern: ^[0-9]{8}$
                                      description: Account number, required for wire transfer over Faster Payments.
                                    sortCode:
                                      type: string
                                      minLength: 6
                                      maxLength: 6
                                      pattern: ^[0-9]{6}$
                                      description: Sort code, required for wire transfer over Faster Payments.
                                    secondaryReference:
                                      type: string
                                      description: Secondary reference data if applicable.
                                - title: SepaBankDetails
                                  required:
                                  - iban
                                  type: object
                                  description: Bank details used in case the wire transfer is executed over SEPA.
                                  properties:
                                    iban:
                                      type: string
                                      minLength: 15
                                      maxLength: 34
                                      pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$
                                      description: International Bank Account Number, required for wire transfer over SEPA.
                                    bankIdentifierCode:
                                      type: string
                                      minLength: 8
                                      maxLength: 11
                                      pattern: ^[a-zA-Z0-9]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}[a-zA-Z0-9]{0,3}$
                                      description: BIC, for wire transfer over SEPA.
                          validationOutcomes:
                            type: array
                            items:
                              type: object
                              properties:
                                category:
                                  type: string
                                  enum:
                                  - UK_CONFIRMATION_OF_PAYEE
                                categoryResult:
                                  type: object
                                  properties:
                                    match:
                                      type: string
                                      description: The result of matching performed by the UK Confirmation of Payee responder
                                      enum:
                                      - EXACT_MATCH
                                      - CLOSE_MATCH
                                      - NO_MATCH
                                    reasonCode:
                                      type: string
                                      description: "The reason why the matching failed at the UK Confirmation of Payee responder:\n\n  - ANNM: The CoP responder confirms that the account `name` provided does not match;\n  - 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;\n  - 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;\n  - 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;\n  - 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;\n  - 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;\n  - AC01: The account does not exist in the CoP responders books, the `accountNumber` specified is likely incorrect; \n  - IVCR: The CoP responder was unable to locate an account based on the `secondaryReference` field;\n  - ACNS: The account is not supported for CoP by the CoP responder;\n  - OPTO: The owner of the account has opted out of CoP service by the CoP responder;\n  - CASS: The account has been switched using the Current Account Switch Service;\n  - SCNS: The `sortCode` provided is not supported at endpoint;\n"
                                      enum:
                                      - ANNM
                                      - MBAM
                                      - BANM
                                      - PANM
                                      - BAMM
                                      - PAMM
                                      - AC01
                                      - IVCR
                                      - ACNS
                                      - OPTO
                                      - CASS
                                      - SCNS
                                    accountName:
                                      type: string
                                      description: Returned when there is `match` is a `CLOSE_MATCH` and the `reasonCode` is MBAM, BAMM or PAMM
                  createdAt:
                    type: string
                    format: date-time
                    readOnly: true
        '400':
          description: Bad Request Error - Your request is invalid.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    maxLength: 255
                    type: string
                    description: When present helps to identify and fix the problem.
                  syntaxErrors:
                    type: object
                    description: 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.
                    properties:
                      invalidFields:
                        type: array
                        items:
                          type: object
                          properties:
                            params:
                              type: array
                              items:
                                type: string
                            fieldName:
                              type: string
                            error:
                              type: string
                              enum:
                              - REQUIRED
                              - HAS_TEXT
                              - REQUIRES
                              - SIZE
                              - RANGE
                              - IN
                              - NOT_IN
                              - REGEX
                              - EXACTLY
                              - AT_LEAST
                              - AT_MOST
                              - ALL_OR_NONE
        '401':
          description: Unauthorized - Your credentials or access token are invalid.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '403':
          description: Forbidden - Access to the requested resource or action is forbidden.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                    enum:
                    - INSUFFICIENT_PERMISSIONS
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: 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
        '413':
          description: Content Too Large
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '422':
          description: Unprocessable Entity
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '429':
          description: Too many requests.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
            x-ratelimit-limit:
              description: 'Example: `20, 10;w=60, 20;w=3600

# --- truncated at 32 KB (180 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/weavr/refs/heads/main/openapi/weavr-payment-runs-api-openapi.yml