openapi: 3.0.1
info:
  title: Statement
  version: '1'
  x-metadata:
    category:
      - Accounts
    business:
      - Enterprise
    generated: false
  description: >-
    Retrieve your account statement and see individual entries for all credits
    and debits. Specify a date range and other optional filter values.


    __Authentication header__

      ```
        Authorization: {your_credentials}
      ```
      Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.
      <br /> <br />
      You **must** use the `Authorization` header for any request you send to our Account APIs.
      <br /><br />
      __Accept header__
      ```
        Accept: application/vnd.worldpay.accounts.statements-v1+json
      ```

    We 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 Account APIs.

    <br /><br />

    __DNS whitelisting__


    Whitelist the following URLs:

    * `https://try.access.worldpay-bsh.securedataplatform.com/`

    * `https://access.worldpay-bsh.securedataplatform.com/`


    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.
servers:
  - url: https://try.access.worldpay-bsh.securedataplatform.com
    description: Test (Try)
  - url: https://access.worldpay-bsh.securedataplatform.com
    description: Live
paths:
  /accounts/statements:
    get:
      summary: Query account statement items
      description: >-
        Retrieve statement entries for an account number using the filter
        criteria.
      operationId: getAccountStatement
      parameters:
        - name: accountNumber
          in: query
          description: The account number.
          required: true
          example: '0005553123712133'
          schema:
            type: string
            minLength: 16
            maxLength: 16
        - 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
            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
            format: date-time
            example: '2022-05-05T15:16:30Z'
        - 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.
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
        - 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.
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 500
        - 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.
          required: false
          schema:
            type: string
            enum:
              - credit
              - debit
        - name: transferType
          in: query
          description: >-
            Type of the transaction used to filter out statement entries.
            Alphanumeric only. Special characters are restricted.
          required: false
          schema:
            $ref: '#/components/schemas/AlphanumericRestricted'
            maxLength: 20
        - name: countryCode
          in: query
          description: ISO country code of the transaction.
          required: false
          schema:
            $ref: '#/components/schemas/CountryCode'
            maxLength: 2
        - name: amount
          in: query
          description: The transaction amount.
          required: false
          schema:
            type: number
            format: decimal
        - 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#-transactionreference-format)
          required: false
          schema:
            type: string
            maxLength: 50
        - in: header
          name: Accept
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.accounts.statements-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/vnd.worldpay.accounts.statements-v1+json:
              schema:
                $ref: '#/components/schemas/ExternalStatementResponse'
        '400':
          description: BAD REQUEST response if the request is not valid
          content:
            application/vnd.worldpay.accounts.statements-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                mandatoryFieldMissing:
                  value:
                    httpStatusCode: 400
                    customCode: STAB16
                    message: There was an error in the request
                    errors:
                      enddate:
                        - endDate is mandatory
                noFutureDates:
                  value:
                    httpStatusCode: 400
                    customCode: STAB16
                    message: There was an error in the request
                    errors:
                      startdate:
                        - Request date shouldn't be a future date
                dateIntervalLimitExceeded:
                  value:
                    httpStatusCode: 400
                    customCode: STAB16
                    message: There was an error in the request
                    errors:
                      startdate:
                        - >-
                          Date interval limit exceeded in the request. Max
                          interval is 30 days
                exceededMaxLimit:
                  value:
                    httpStatusCode: 400
                    customCode: STAB16
                    message: There was an error in the request
                    errors:
                      pagesize:
                        - >-
                          pageSize limit exceeded in the request. Maximum number
                          of pageSize is 500
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiAuthErrorResponse'
              examples:
                accessDenied1:
                  value:
                    errorName: accessDenied
                    message: Access to the requested resource has been denied
                accessDenied2:
                  value:
                    httpStatusCode: 401
                    customCode: STAU06
                    message: Unauthorized request
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    httpStatusCode: 403
                    customCode: STAF18
                    message: Forbidden
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.accounts.statements-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    httpStatusCode: 404
                    customCode: STAN15
                    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/vnd.worldpay.accounts.statements-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                httpStatusCode: 500
                customCode: STAE00A
                message: Internal Server Error
components:
  schemas:
    AlphanumericRestricted:
      type: string
      pattern: ^[a-zA-Z0-9 ._-]*$
    CountryCode:
      type: string
      minLength: 2
      maxLength: 2
      pattern: ^[a-zA-Z0-9]*$
    ErrorResponse:
      type: object
      properties:
        httpStatusCode:
          type: integer
          format: int32
        customCode:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        errors:
          type: object
          items:
            $ref: '#/components/schemas/ErrorResponseItem'
          nullable: true
      additionalProperties: false
    ErrorResponseItem:
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    AltAuthErrorResponse:
      type: object
      properties:
        errorName:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
    MultiAuthErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - $ref: '#/components/schemas/AltAuthErrorResponse'
    ExternalAccountStatementItems:
      type: object
      properties:
        transactionReference:
          description: Your unique reference for the transaction.
          type: string
          nullable: true
        transferType:
          description: The transfer type.
          type: string
          nullable: true
        amount:
          description: The amount.
          type: number
          format: double
        timestamp:
          description: The posting date of the specific statement item.
          type: string
          format: date-time
        fundingType:
          description: A credit or debit operation. Value can be `credit` or `debit`.
          type: string
          nullable: true
        rate:
          description: The rate applied for FX conversion.
          type: number
          format: double
          nullable: true
        cleared:
          description: Cleared balance or uncleared balance. Value can be `yes` or `no`.
          type: string
          nullable: true
        description:
          description: The description of this statement item.
          type: string
          nullable: true
        statementItemId:
          description: The statement identifier.
          type: string
          format: uuid
        balance:
          description: The balance that resulted from this statement item's transaction.
          type: number
          format: double
        statementNumber:
          description: The statement number.
          type: integer
          format: int64
        narrative:
          description: The reference to the specific transaction.
          type: string
          nullable: true
        countryCode:
          description: The country code.
          type: string
          nullable: true
        originalCurrency:
          description: >
            For statement items (debits/credits) with no FX conversion involved,
            originalCurrency value will be null.


            In case an FX conversion is involved, then:
              - For debit items, originalCurrency shows the target currency.
              - For credit items, originalCurrency shows the source currency.
          type: string
          nullable: true
        originalAmount:
          description: >
            For statement items (debits/credits) with no FX conversion involved,
            originalAmount value will be null.


            In case an FX conversion is involved, then:
              - For debit items, originalAmount shows the target amount.
              - For credit items, originalAmount shows the source amount.
          type: number
          format: double
          nullable: true
      additionalProperties: false
    ExternalStatementResponse:
      type: object
      properties:
        accountNumber:
          description: The account number.
          type: string
          nullable: true
        currency:
          description: >-
            The currency, determined by the first item in the list. The currency
            is the same for all items.
          type: string
          nullable: true
        accountStatementItems:
          description: A collection of account statement items.
          type: array
          items:
            $ref: '#/components/schemas/ExternalAccountStatementItems'
          nullable: true
        pageNumber:
          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.
          type: integer
          format: int32
        pageSize:
          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.
          type: integer
          format: int32
        pageCount:
          description: The total number of pages.
          type: integer
          format: int32
        totalNumberOfRecords:
          description: The total number of records.
          type: integer
          format: int32
      additionalProperties: false
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
