Worldpay Get payouts API

openapi: 3.2.0
info:
  title: Account Payouts Get payouts API
  description: Send funds to your customer's bank accounts and search for payouts using parameters.
  version: '2025-01-01'
  x-metadata:
    business:
    - Enterprise
    - Marketplaces
    catalog-list: true
    category:
    - Payouts
    generated: true
servers:
- url: https://try.access.worldpay.com
  description: Test (Try)
- url: https://access.worldpay.com
  description: Live
security:
- BasicAuth: []
tags:
- name: Get payouts
  description: Search for payout details by filtering parameters.
paths:
  /accountPayouts/events:
    get:
      tags:
      - Get payouts
      summary: Retrieve payout details
      operationId: GetByQuery
      parameters:
      - name: narrative
        in: query
        description: Reference that may appear on beneficiary statements.
        schema:
          maximum: 50
          minimum: 0
          type: string
          description: Reference that may appear on beneficiary statements.
      - name: transactionReference
        in: query
        description: Unique reference provided by you.
        schema:
          maximum: 50
          minimum: 0
          type: string
          description: Unique reference provided by you.
      - name: accountNumber
        in: query
        description: Beneficiary bank account number.
        schema:
          maximum: 64
          minimum: 0
          type: string
          description: Beneficiary bank account number.
      - name: payoutInstrumentId
        in: query
        description: A unique ID generated by us, holding the beneficiary bank details. You receive this in the response after successfully creating a payout instrument in our <a href="/products/parties/openapi/payout-instruments">Parties API</a>.
        schema:
          type: string
          description: A unique ID generated by us, holding the beneficiary bank details. You receive this in the response after successfully creating a payout instrument in our <a href="/products/parties/openapi/payout-instruments">Parties API</a>.
      - name: payoutInstrumentReference
        in: query
        description: A reference of the payoutInstrument created by you. This field holds the beneficiary bank details.
        schema:
          type: string
          description: A reference of the payoutInstrument created by you. This field holds the beneficiary bank details.
      - name: pageSize
        in: query
        description: Positive whole number indicating the number of payouts to return in each page.
        required: true
        schema:
          maximum: 499
          minimum: 1
          type: integer
          description: Positive whole number indicating the number of payouts to return in each page.
          format: int32
      - name: entity
        in: query
        description: Your entity reference created as part of on-boarding. Used to route the request in Access Worldpay.
        schema:
          maximum: 6
          minimum: 6
          type: string
          description: Your entity reference created as part of on-boarding. Used to route the request in Access Worldpay.
      - name: countryCode
        in: query
        description: <a href="/products/reference/supported-countries-currencies#iso-country-codes">ISO 3166-1 Alpha-2 country code</a> of the payout destination.
        schema:
          maximum: 2
          minimum: 2
          type: string
          description: <a href="/products/reference/supported-countries-currencies#iso-country-codes">ISO 3166-1 Alpha-2 country code</a> of the payout destination.
      - name: pageNumber
        in: query
        description: Positive whole number indicating which page of the statement to return.
        required: true
        schema:
          minimum: 1
          type: integer
          description: Positive whole number indicating which page of the statement to return.
          format: int32
      - name: paymentState
        in: query
        schema:
          maximum: 255
          enum:
          - AWAITING_EXECUTION
          - NEW
          - VALID
          - REJECTED
          - EXECUTED
          - IN_REVIEW
          - RFI_IN_PROGRESS
          - AWAITING_LIQUIDITY
          - COMPLETED
          - REVERSED
          - FAILED
          - INVALID
          type: string
          x-enumDescriptions:
            AWAITING_EXECUTION: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            NEW: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            VALID: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            REJECTED: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            EXECUTED: The API has accepted your payout request and it is now waiting in the queue for submission to our banking partner.
            IN_REVIEW: Payout is currently under review as part of our standard compliance procedures. No action is required from you at this time. We will notify you separately once the review is complete or if we require any further information from you.
            RFI_IN_PROGRESS: Payout is currently on hold pending the completion of our standard compliance review. We require additional information from you and will be in touch with the specific details needed. Please respond at your earliest convenience to help us resolve this as quickly as possible.
            AWAITING_LIQUIDITY: Payout is currently on hold due to insufficient funds. Please deposit funds into your Worldpay account in order to release the payout and ensure future payouts aren't also held in this state.
            COMPLETED: Our banking partner has accepted the payout request for processing. Final state or `REVERSED` in a return scenario.
            REVERSED: Our validation rules, banking partner or beneficiary bank has rejected the payout request. The funds have subsequently been returned to your account.  All rejected payouts include a description with reasoning (if available).
            FAILED: Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            INVALID: Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
      - name: startDate
        in: query
        description: "Posting start date for the payout. This is the start of a time window. This must be before the current date and before the end date, as well as being after the minimum date (0001-01-01). The difference between start and end dates should not exceed 31 days. \tMust be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD."
        schema:
          maximum: 10
          minimum: 10
          type: string
          description: "Posting start date for the payout. This is the start of a time window. This must be before the current date and before the end date, as well as being after the minimum date (0001-01-01). The difference between start and end dates should not exceed 31 days. \tMust be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD."
      - name: endDate
        in: query
        description: Posting end date for the payout. This is the end of a time window. This must be before the current date, as well as after the start date and the minimum date (0001-01-01).
        schema:
          maximum: 10
          minimum: 10
          type: string
          description: Posting end date for the payout. This is the end of a time window. This must be before the current date, as well as after the start date and the minimum date (0001-01-01).
      - name: payeeName
        in: query
        description: 'Complete payee name for the payout. This will be one of the following (depending on the beneficiary type): fullName - concatenated value from title + firstName + middleName + lastName; companyName'
        schema:
          maximum: 140
          minimum: 0
          type: string
          description: 'Complete payee name for the payout. This will be one of the following (depending on the beneficiary type): fullName - concatenated value from title + firstName + middleName + lastName; companyName'
      - name: sourceCurrency
        in: query
        description: Source <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency codes</a> for the payout.
        schema:
          maximum: 3
          minimum: 3
          type: string
          description: Source <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency codes</a> for the payout.
      - name: sourceAmount
        in: query
        description: Source amount. 18 digit precision including 2 decimal places
        schema:
          maximum: 19
          minimum: 1
          type: number
          description: Source amount. 18 digit precision including 2 decimal places
          format: double
      - name: targetCurrency
        in: query
        description: Target <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency codes</a> for the payout.
        schema:
          maximum: 35
          minimum: 1
          type: string
          description: Target <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency codes</a> for the payout.
      - name: targetAmount
        in: query
        description: 18 digit precision including 2 decimal places
        schema:
          maximum: 35
          minimum: 1
          type: number
          description: 18 digit precision including 2 decimal places
          format: double
      - name: WP-CorrelationId
        in: header
        description: A unique identifier used to trace and correlate a request across systems. Must be a GUID.
        schema:
          type: string
        example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      - name: WP-Timestamp
        in: header
        schema:
          type: string
          default: '1755681620'
      - name: WP-Api-Version
        in: header
        description: The version of the API you are using.
        schema:
          type: string
          default: '2025-01-01'
        example: '2025-01-01'
      - name: Idempotency-Key
        in: header
        description: A unique key to identify the request. This is used to prevent duplicate processing of the same request.
        schema:
          maximum: 35
          minimum: 1
          type: string
          default: mustBeUnique12345
        example: mustBeUnique12345
      - name: Accept
        in: header
        schema:
          type: string
          default: application/json
          example: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.PayoutItemSearch.V3.Models.GetOriginalItemResponse'
              example:
                items:
                - paymentId: 51a448e5-4430-ee11-b58a-005056b48b8e
                  paymentDatetime: '2023-08-01T08:24:44.443Z'
                  payeeName: John Smith
                  sourceCurrency: ARS
                  sourceAmount: 0
                  targetCurrency: ARS
                  targetAmount: 1.05
                  paymentState: EXECUTED
                  bankName: Test Bank
                  bankCode: 10 02 04
                  iban: GB29NWBK60161331926819
                  channel: WIRE,ACH SD
                  routedChannel: WIRE
                  bankReference: ABCHK24
                  payoutRequestId: PO000N65
                  narrative: XYZ102025
                  transactionReference: XYZ102025
                  accountNumber: '45533882'
                  swiftBic: BUKBGB22
                  entity: default
                  countryCode: AR
                - paymentId: c1b659f6-4c30-ee11-b58a-005056b48b8e
                  paymentDatetime: '2023-08-01T09:22:41.377Z'
                  payeeName: John Johno Johnson
                  sourceCurrency: GBP
                  sourceAmount: 0
                  targetCurrency: GBP
                  targetAmount: 10
                  paymentState: EXECUTED
                  bankName: Test Bank
                  bankCode: '404433'
                  iban: GB29NWBK60161331926819
                  channel: WIRE,ACH SD,DOM
                  routedChannel: ACH SD
                  bankReference: ABCHK25
                  payoutRequestId: PN00004N
                  narrative: 'Ref: 123456'
                  transactionReference: '123456'
                  accountNumber: '12345677'
                  swiftBic: BUKBGB22
                  entity: default
                  countryCode: GB
                pagination:
                  pageNumber: 1
                  pageSize: 2
                  pageCount: 5610
                  totalNumberOfRecords: 11220
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwBodyErrorModel'
              example:
                validationErrors:
                - jsonPath: $.payeeName
                  errorName: stringIsTooLong
                  message: The length of 'Payee Name' must be 140 characters or fewer. You entered 141 characters.
                errorName: bodyDoesNotMatchSchema
                message: There was an error in the request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwBodyErrorModel'
              example:
                errorName: unauthorized
                message: Invalid token
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwBodyErrorModel'
              example:
                errorName: Forbidden
                message: Forbidden. Unauthorized request
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwBodyErrorModel'
              example:
                errorName: null
                message: An unexpected error occurred.
components:
  schemas:
    WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwJsonPathErrorModel:
      type: object
      properties:
        errorName:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
        jsonPath:
          type:
          - string
          - 'null'
      additionalProperties: false
    WP.FXT.SinglePayoutApi.Domain.PayoutItemSearch.V3.Models.GetOriginalItemResponse:
      type: object
      properties:
        items:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.PayoutItemSearch.V3.Models.OriginalItem'
        pagination:
          $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.PayoutItemSearch.V2.Models.Pagination'
      additionalProperties: false
    WP.FXT.SinglePayoutApi.Domain.PayoutItemSearch.V2.Models.Pagination:
      required:
      - pageNumber
      - pageSize
      type: object
      properties:
        pageNumber:
          type: integer
          description: Positive whole number indicating which page of the statement to return. Greater than 0.
          format: int32
        pageSize:
          maximum: 499
          minimum: 1
          type: integer
          description: Number of items listed per page.
          format: int32
        pageCount:
          type: integer
          description: Total number of pages.
          format: int32
        totalNumberOfRecords:
          type: integer
          description: Total number of items listed across all pages.
          format: int32
      additionalProperties: false
    WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwBodyErrorModel:
      type: object
      properties:
        errorName:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
        validationErrors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwJsonPathErrorModel'
      additionalProperties: false
    WP.FXT.SinglePayoutApi.Domain.PayoutItemSearch.V3.Models.OriginalItem:
      required:
      - payoutRequestId
      type: object
      properties:
        paymentId:
          type:
          - string
          - 'null'
          description: Unique identifier associated with the payment. GUID.
        paymentDatetime:
          type:
          - string
          - 'null'
          description: Date and time of the payment submission. DateTime ISO 8601.
          format: date-time
        payeeName:
          maximum: 140
          type:
          - string
          - 'null'
          description: 'Complete payee name for the payout. This will be one of (depending on the beneficiary type):

            fullName- concatenated value from title + firstName + middleName + lastName

            companyName.'
        sourceCurrency:
          maximum: 3
          type:
          - string
          - 'null'
          description: <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency code</a> for the remitter account.
        sourceAmount:
          type: number
          description: Source amount. 18 digit precision including 2 decimal places.
          format: double
        targetCurrency:
          maximum: 3
          minimum: 3
          type:
          - string
          - 'null'
          description: Target <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency codes</a> for the payout.
        targetAmount:
          type: number
          description: Target amount.
          format: double
        paymentState:
          enum:
          - AWAITING_EXECUTION
          - NEW
          - VALID
          - REJECTED
          - EXECUTED
          - IN_REVIEW
          - RFI_IN_PROGRESS
          - AWAITING_LIQUIDITY
          - COMPLETED
          - REVERSED
          - FAILED
          - INVALID
          type:
          - string
          - 'null'
          description: State of the payout.
          x-enumDescriptions:
            AWAITING_EXECUTION: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            NEW: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            VALID: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            REJECTED: Interim state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            EXECUTED: The API has accepted your payout request and it is now waiting in the queue for submission to our banking partner.
            IN_REVIEW: Payout is currently under review as part of our standard compliance procedures. No action is required from you at this time. We will notify you separately once the review is complete or if we require any further information from you.
            RFI_IN_PROGRESS: "Payout is currently on hold pending the completion of our standard compliance review. We require additional information from you and will be in touch with the specific details needed. Please respond at your earliest convenience to help us resolve this as quickly as possible.\n\n  **Note:** Please contact your Worldpay Implementation Manager if you want to receive this."
            AWAITING_LIQUIDITY: "Payout is currently on hold due to insufficient funds. Please deposit funds into your Worldpay account in order to release the payout and ensure future payouts aren't also held in this state.\n\n  **Note:** Please contact your Worldpay Implementation Manager if you want to receive this."
            COMPLETED: Our banking partner has accepted the payout request for processing. Final state or `REVERSED` in a return scenario.
            REVERSED: Our validation rules, banking partner or beneficiary bank has rejected the payout request. The funds have subsequently been returned to your account.  All rejected payouts include a description with reasoning (if available).
            FAILED: Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
            INVALID: Final state in the asynchronous payout request. Please contact your Relationship Manager if this persists, as this might suggest integration issues.
        bankName:
          type:
          - string
          - 'null'
          description: Name of the payee (beneficiary) bank which the payout is being made to.
        bankCode:
          type:
          - string
          - 'null'
          description: Beneficiary bank account bank code.
        iban:
          type:
          - string
          - 'null'
          description: Beneficiary IBAN.
        estimatedDeliveryDate:
          type:
          - string
          - 'null'
        outcomeReason:
          type:
          - string
          - 'null'
        channel:
          type:
          - string
          - 'null'
          description: List of the channels that were sent in the request for this payout.
        routedChannel:
          type:
          - string
          - 'null'
          description: The channel that was used to process this payout.
        bankReference:
          type:
          - string
          - 'null'
          description: A bank-generated reference that enables your customers to track their payout within the payment network. This feature is only available for specific routes. For details on availability, please contact your Relationship Manager.
        payoutRequestId:
          maximum: 10
          minimum: 8
          pattern: AlphaNumericRegex = ^[0-9a-zA-Z]+$
          type: string
          description: Unique payout request ID associated with a payout submitted through our Account Payouts API. PN/PZ/PO prefix plus 6 characters.
        narrative:
          maximum: 50
          minimum: 0
          type:
          - string
          - 'null'
          description: Reference that may appear on beneficiary statements.
        transactionReference:
          maximum: 50
          minimum: 0
          type:
          - string
          - 'null'
          description: Unique reference provided by you.
        accountNumber:
          maximum: 50
          minimum: 0
          type:
          - string
          - 'null'
          description: Bank Account number.
        swiftBic:
          maximum: 50
          type:
          - string
          - 'null'
          description: Beneficiary bank account SWIFT/BIC.
        countryCode:
          maximum: 2
          minimum: 2
          type:
          - string
          - 'null'
          description: <a href="/products/reference/supported-countries-currencies#iso-country-codes">ISO 3166-1 Alpha-2 country code</a> of the payout destination.
      additionalProperties: false
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic