openapi: 3.0.1
info:
  title: 3DS 3DS actions Get payouts by Payout Request ID API
  description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n  ```\n    Authorization: {your_credentials}\n  ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n  ```\n  Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n  Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n  ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__  \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
  version: '3'
  x-metadata:
    category:
    - 3DS
    - SCA Exemptions
    business:
    - Enterprise
    catalog-list: true
    generated: false
servers:
- url: https://try.access.worldpay.com
  description: Test (Try)
- url: https://access.worldpay.com
  description: Live
security:
- BasicAuth: []
tags:
- name: Get payouts by Payout Request ID
  description: Search for payout details by using a Payout Request ID.
paths:
  /accountPayouts/{payoutRequestId}:
    get:
      tags:
      - Get payouts by Payout Request ID
      summary: Retrieve payout details
      operationId: GetByPayoutRequestId
      parameters:
      - name: payoutRequestId
        in: path
        required: true
        schema:
          type: string
          description: Unique payout request ID associated with the original payout. We have returned this in the payout response. PN/PZ/PO prefix plus 6 characters.
          example: PZ000N65
      - 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.OriginalItem'
              example:
                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: ABCHK26
                payoutRequestId: PO000N65
                narrative: XYZ102025
                transactionReference: XYZ102025
                accountNumber: '45533882'
                swiftBic: BUKBGB22
                entity: default
                countryCode: AR
        '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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwBodyErrorModel'
              example:
                errorName: notFound
                message: Payment not found
        '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.PayoutItemSearch.V3.Models.OriginalItem:
      required:
      - payoutRequestId
      type: object
      properties:
        paymentId:
          type: string
          description: Unique identifier associated with the payment. GUID.
          nullable: true
        paymentDatetime:
          type: string
          description: Date and time of the payment submission. DateTime ISO 8601.
          format: date-time
          nullable: true
        payeeName:
          maximum: 140
          type: string
          description: "Complete payee name for the payout. This will be one of (depending on the beneficiary type):\r\nfullName- concatenated value from title + firstName + middleName + lastName\r\ncompanyName."
          nullable: true
        sourceCurrency:
          maximum: 3
          type: string
          description: <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency code</a> for the remitter account.
          nullable: true
        sourceAmount:
          type: number
          description: Source amount. 18 digit precision including 2 decimal places.
          format: double
        targetCurrency:
          maximum: 3
          minimum: 3
          type: string
          description: Target <a href="/products/reference/supported-countries-currencies#currency-codes">ISO 4217 alpha-3 currency codes</a> for the payout.
          nullable: true
        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
          description: State of the payout.
          nullable: true
          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
          description: Name of the payee (beneficiary) bank which the payout is being made to.
          nullable: true
        bankCode:
          type: string
          description: Beneficiary bank account bank code.
          nullable: true
        iban:
          type: string
          description: Beneficiary IBAN.
          nullable: true
        estimatedDeliveryDate:
          type: string
          nullable: true
        outcomeReason:
          type: string
          nullable: true
        channel:
          type: string
          description: List of the channels that were sent in the request for this payout.
          nullable: true
        routedChannel:
          type: string
          description: The channel that was used to process this payout.
          nullable: true
        bankReference:
          type: string
          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.
          nullable: true
        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
          description: Reference that may appear on beneficiary statements.
          nullable: true
        transactionReference:
          maximum: 50
          minimum: 0
          type: string
          description: Unique reference provided by you.
          nullable: true
        accountNumber:
          maximum: 50
          minimum: 0
          type: string
          description: Bank Account number.
          nullable: true
        swiftBic:
          maximum: 50
          type: string
          description: Beneficiary bank account SWIFT/BIC.
          nullable: true
        countryCode:
          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.
          nullable: true
      additionalProperties: false
    WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwBodyErrorModel:
      type: object
      properties:
        errorName:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwJsonPathErrorModel'
          nullable: true
      additionalProperties: false
    WP.FXT.SinglePayoutApi.Domain.Shared.ErrorModels.AwJsonPathErrorModel:
      type: object
      properties:
        errorName:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        jsonPath:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic