openapi: 3.0.1
info:
  title: Statements
  description: "Retrieve your account statement and see individual entries for all credits and debits. Specify a date range and other optional filter values. \r\n  \r\n    __Authentication Header__\r\n\r\n      ```\r\n        Authorization: {your_credentials}\r\n      ```\r\n      Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.\r\n      <br /> <br />\r\n      You **must** use the `Authorization` header for any request you send to our Statements API.\r\n      <br /><br />\r\n      __WP-Api-Version Header__\r\n      ```\r\n        WP-Api-Version: 2025-01-01\r\n      ```\r\n\r\n    We use the WP-Api-Version header to identify which version of our API you are using. You must use the WP-Api-Version header for any request you send to our Account APIs.\r\n    <br /><br />\r\n    __DNS Whitelisting__\r\n\r\n    Whitelist the following URLs:\r\n    * `https://try.access.worldpay.com/`\r\n    * `https://access.worldpay.com/`\r\n\r\n    Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned."
  license:
    name: Worldpay
    url: developers.worldpay.com/license
  version: '2025-01-01'
  x-metadata:
    business:
      - Enterprise
      - Marketplaces
    catalog-list: true
    category:
      - Accounts
    generated: true
servers:
  - url: https://try.access.worldpay.com
    description: Try
  - url: https://access.worldpay.com
    description: Live
paths:
  /accounts/statements:
    get:
      summary: Query account statement items
      operationId: GetStatements
      parameters:
        - name: startDate
          in: query
          description: >-
            An ISO 8601 date-time string. From date and time. Timespan between
            'startDate' and 'endDate' shouldn't exceed 30 days. This should not
            be a date in the future.
          required: true
          schema:
            type: string
            description: >-
              An ISO 8601 date-time string. From date and time. Timespan between
              'startDate' and 'endDate' shouldn't exceed 30 days. This should
              not be a date in the future.
            format: date-time
            example: '2022-05-01T15:16:30Z'
        - name: endDate
          in: query
          description: >-
            An ISO 8601 date-time string. To date and time. Timespan between
            'startDate' and 'endDate' shouldn't exceed 30 days. This should not
            be a date in the future.
          required: true
          schema:
            type: string
            description: >-
              An ISO 8601 date-time string. To date and time. Timespan between
              'startDate' and 'endDate' shouldn't exceed 30 days. This should
              not be a date in the future.
            format: date-time
            example: '2022-05-05T15:16:30Z'
        - name: accountNumber
          in: query
          description: >-
            The account number. You must use this if you are an Account Payout
            customer. You can use this for a Marketplaces flow.

            {% admonition type="warning" %}

            `accountNumber` or `partyReference` must be provided <br><br>

            {% /admonition %}

            <br>  
          schema:
            maxLength: 16
            minLength: 16
            type: string
            description: The account number.
            example: '0005553123712133'
        - name: partyReference
          in: query
          description: >-
            Your reference for this party, must be unique within an entity.
            Typically used for a Marketplaces flow and used to retrieve
            information about your onboarded party. Allowed values: a-z, A-Z,
            0-9, spaces and hyphens.

            {% admonition type="warning" %}

            `accountNumber` or `partyReference` must be provided <br><br>

            If `partyReference` is provided you must also include `entity` and
            `currency`

            {% /admonition %}

            <br>  
          schema:
            maxLength: 63
            minLength: 3
            type: string
            description: >-
              Your reference for this party, must be unique within an entity.
              Allowed values a-z, A-Z, 0-9, spaces and hyphens.
            example: Hosaka2738491
        - name: entity
          in: query
          description: >-
            Used to route the request in Access Worldpay, created as part of
            on-boarding.
          schema:
            maxLength: 36
            minLength: 1
            type: string
            description: >-
              Used to route the request in Access Worldpay, created as part of
              on-boarding.
            example: default
        - name: currency
          in: query
          description: >-
            The currency in [ISO 4217 currency
            format](/products/reference/supported-countries-currencies#iso-currency-codes)
            for the account associated with the party.
          schema:
            maxLength: 3
            minLength: 3
            type: string
            description: >-
              The currency in [ISO 4217 currency
              format](/products/reference/supported-countries-currencies#iso-currency-codes)
              for the account associated with the party
            example: GBP
        - name: pageNumber
          in: query
          description: >-
            The page number of the results. Default is 1 if no value is
            provided. This value specifies the exact page of each list of
            statements that you want to retrieve.
          schema:
            minLength: 1
            type: integer
            description: >-
              The page number of the results. Default is 1 if no value is
              provided. This value specifies the exact page of each list of
              statements that you want to retrieve.
            format: int32
        - name: pageSize
          in: query
          description: >-
            Exact number of records per page to be shown. Max 500 items/rows.
            Value must be between 1-500. Default is 1 if no value is provided.
          schema:
            maxLength: 500
            minLength: 1
            type: integer
            description: >-
              Exact number of records per page to be shown. Max 500 items/rows.
              Value must be between 1-500. Default is 1 if no value is provided.
            format: int32
        - name: fundingType
          in: query
          description: >-
            Credit or debit operation. Value can be credit or debit. If no value
            is passed, the statement includes both credits and debits.
          schema:
            enum:
              - credit
              - debit
            type: string
            description: >-
              Credit or debit operation. Value can be credit or debit. If no
              value is passed, the statement includes both credits and debits.
        - name: transferType
          in: query
          description: >-
            Type of the transaction used to filter out statement entries.
            Alphanumeric only. Special characters are restricted.
          schema:
            pattern: ^[a-zA-Z0-9 ._-]*$
            description: >-
              Type of the transaction used to filter out statement entries.
              Alphanumeric only. Special characters are restricted.
            enum:
              - ACQUIRING SETTLEMENT
              - BANKIN
              - BANKIN_REFUND
              - BANKOUT
              - BENEFICIARY PAYOUT
              - BENEFICIARY_FUNDING
              - CHARGEBACK
              - COMMISSION
              - CORRECTION
              - CREDIT
              - DEBIT
              - DEDUCTION
              - EFTIN
              - EFTIN_REFUND
              - FFX PAYOUT
              - FFX PAYOUT RETURNED
              - FFX PAYOUT REVERSAL
              - FX DEAL
              - INTERNAL LIQUIDITY
              - LIQUIDITY
              - PAYIN
              - PAYIN_REFUND
              - PAYIN REVERSAL
              - PAYOUT
              - PAYOUT RETURNED
              - PAYOUT REVERSAL
              - REFUND
              - SPLIT PAYMENT
              - SPLIT PAYOUT
              - STREAMLINE TRANSFER
            x-enumDescriptions:
              ACQUIRING SETTLEMENT: null
              BANKIN: Non-US customers only
              BANKIN_REFUND: Non-US customers only
              BANKOUT: Non-US customers only
              BENEFICIARY PAYOUT: Used in Marketplaces
              BENEFICIARY_FUNDING: Used in Marketplaces
              CHARGEBACK: Used in Marketplaces
              COMMISSION: Used in Marketplaces
              CORRECTION: null
              CREDIT: Used in Marketplaces
              DEBIT: Used in Marketplaces
              DEDUCTION: null
              EFTIN: null
              EFTIN_REFUND: null
              FFX PAYOUT: null
              FFX PAYOUT RETURNED: null
              FFX PAYOUT REVERSAL: null
              FX DEAL: null
              INTERNAL LIQUIDITY: null
              LIQUIDITY: null
              PAYIN: US-merchants only
              PAYIN_REFUND: US-merchants only
              PAYIN REVERSAL: null
              PAYOUT: US-merchants only
              PAYOUT RETURNED: null
              PAYOUT REVERSAL: null
              REFUND: null
              SPLIT PAYMENT: null
              SPLIT PAYOUT: null
              STREAMLINE TRANSFER: null
        - name: countryCode
          in: query
          description: >-
            The country code specified in [ISO 3166-1 Alpha-2 code
            format](/products/reference/supported-countries-currencies#iso-country-codes)
            of the transaction.
          schema:
            maxLength: 2
            minLength: 2
            pattern: ^[a-zA-Z0-9]*$
            type: string
            description: >-
              The country code specified in [ISO 3166-1 Alpha-2 code
              format](/products/reference/supported-countries-currencies#iso-country-codes)
              of the transaction.
        - name: amount
          in: query
          description: The transaction amount.
          schema:
            type: number
            description: The transaction amount.
            format: double
        - name: transactionReference
          in: query
          description: >-
            Your unique reference for the payment request. This can be a "like"
            search (exact or partial match). Special characters are allowed. For
            the list, please see our [formatting
            guide](/products/reference/formatting.md).
          schema:
            maxLength: 50
            minLength: 1
            type: string
            description: >-
              Your unique reference for the payment request. This can be a
              "like" search (exact or partial match). Special characters are
              allowed. For the list, please see our [formatting
              guide](/products/reference/formatting.md).
        - name: WP-Api-Version
          in: header
          description: Represents the version of the API.
          required: true
          schema:
            type: string
          example: '2025-01-01'
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
        - name: WP-CallerId
          in: header
          description: An ID used for logging purposes.
          schema:
            type: string
        - name: Accept
          in: header
          description: Accept header is optional and must be application/json if provided
          schema:
            type: string
          example: application/json
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalStatementResponseV2'
        '204':
          description: No content for valid request
        '400':
          description: BAD REQUEST response if the request is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedAccessErrorResponse'
              examples:
                InvalidUser:
                  summary: This example shows an invalid format error.
                  value:
                    errorName: urlContainsInvalidValue
                    message: The URL contains a value or values that are invalid.
                    validationErrors:
                      - errorName: numberIsTooLarge
                        message: AccountNumber is mandatory
                        queryParameter: accountNumber
                noFutureDates:
                  summary: noFutureDates
                  value:
                    errorName: urlContainsInvalidValue
                    message: The URL contains a value or values that are invalid.
                    validationErrors:
                      - errorName: fieldHasInvalidValue
                        message: Request date shouldn't be a future date
                        queryParameter: endDate
                DateLimitIntervalExceeded:
                  summary: DateLimitIntervalExceeded
                  value:
                    errorName: urlContainsInvalidValue
                    message: The URL contains a value or values that are invalid.
                    validationErrors:
                      - errorName: fieldHasInvalidValue
                        message: >-
                          Date interval limit exceeded in the request. Max
                          interval is 50 days
                        queryParameter: startDate
                ExceededMaxLimit:
                  summary: ExceededMaxLimit
                  value:
                    errorName: urlContainsInvalidValue
                    message: The URL contains a value or values that are invalid.
                    validationErrors:
                      - errorName: fieldHasInvalidValue
                        message: >-
                          pageSize limit exceeded in the request. Maximum number
                          of pageSize is 700
                        queryParameter: startDate
        '401':
          description: UNAUTHORIZED response if JWT is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAccessErrorResponse'
              example:
                errorName: accessDenied
                message: Access to the requested resource has been denied
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAccessErrorResponse'
              example:
                errorName: forbidden
                message: AccessWorldpayId value not available in context
        '404':
          description: NOT FOUND response if the AccountNumber or Page was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAccessErrorResponse'
              example:
                errorName: notFound
                message: >-
                  The requested page was not found. The page number requested is
                  outside the value of the total number of pages.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAccessErrorResponse'
              example:
                errorName: internalServerError
                message: An internal server error occurred
components:
  schemas:
    BaseAccessErrorResponse:
      type: object
      properties:
        errorName:
          type: string
          description: Unique response code for this endpoint
          nullable: true
        message:
          type: string
          description: Error message
          nullable: true
        headerName:
          type: string
          description: Error message
          nullable: true
      additionalProperties: false
    ExtendedAccessErrorResponse:
      type: object
      properties:
        errorName:
          type: string
          description: Unique response code for this endpoint
          nullable: true
        message:
          type: string
          description: Error message
          nullable: true
        headerName:
          type: string
          description: Error message
          nullable: true
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrors'
          description: >-
            Collection of error details. This field may be omitted from the
            response depending on the nature of the error.
          nullable: true
      additionalProperties: false
    ExternalAccountStatementItemsV2:
      type: object
      properties:
        transactionReference:
          type: string
          description: Your unique reference for the transaction.
          nullable: true
        transferType:
          type: string
          description: The transfer type.
          nullable: true
        amount:
          type: number
          description: The amount.
          format: double
        timestamp:
          type: string
          description: The posting date of the specific statement item.
          format: date-time
        fundingType:
          type: string
          description: A credit or debit operation. Value can be `credit` or `debit`.
          nullable: true
        rate:
          type: number
          description: The rate applied for FX conversion.
          format: double
          nullable: true
        cleared:
          type: string
          description: Cleared balance or uncleared balance. Value can be `yes` or `no`.
          nullable: true
        description:
          type: string
          description: The description of this statement item.
          nullable: true
        statementItemId:
          type: string
          description: The statement identifier.
          format: uuid
        balance:
          type: number
          description: The balance that resulted from this statement item's transaction.
          format: double
        statementNumber:
          type: integer
          description: The statement number.
          format: int64
        narrative:
          $ref: '#/components/schemas/ExternalNarrativeV2'
        countryCode:
          type: string
          description: The country code.
          nullable: true
        originalCurrency:
          type: string
          description: "For statement items (debits/credits) with no FX conversion involved, `originalCurrency` value will be null.\r\n\r\nIn case an FX conversion is involved, then:\r\n\r\n - For debit items, `originalCurrency` shows the target currency.\r\n - For credit items, `originalCurrency` shows the source currency."
          nullable: true
        originalAmount:
          type: number
          description: "For statement items (debits/credits) with no FX conversion involved, `originalAmount` value will be null.\r\n\r\nIn case an FX conversion is involved, then:\r\n\r\n - For debit items, `originalAmount` shows the target amount.\r\n - For credit items, `originalAmount` shows the source amount."
          format: double
          nullable: true
      additionalProperties: false
    ExternalNarrativeV2:
      type: object
      properties:
        line1:
          type: string
          nullable: true
      additionalProperties: false
    ExternalStatementResponseV2:
      type: object
      properties:
        accountNumber:
          type: string
          description: The account number.
          nullable: true
        currency:
          type: string
          description: >-
            The currency, determined by the first item in the list. The currency
            is the same for all items.
          nullable: true
        accountStatementItems:
          type: array
          items:
            $ref: '#/components/schemas/ExternalAccountStatementItemsV2'
          description: A collection of account statement items.
          nullable: true
        pageNumber:
          type: integer
          description: >-
            The page number. Default is 1 if no value is provided. This value
            specifies the exact page of each list of statements that you want to
            retrieve.
          format: int32
        pageSize:
          type: integer
          description: >-
            The exact number of records per page to be shown. Max 500
            items/rows. Value must be between 1-500. Default is 1 if no value is
            provided.
          format: int32
        pageCount:
          type: integer
          description: The total number of pages.
          format: int32
        totalNumberOfRecords:
          type: integer
          description: The total number of records.
          format: int32
      additionalProperties: false
    ValidationErrors:
      type: object
      properties:
        errorName:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        queryParameter:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
security:
  - BasicAuth: []
