openapi: 3.0.1
info:
  title: Balance
  description: >-
    Request your account details for a single account or all accounts under an
    entity.


    __Authentication Header__
      ```
        Authorization: {your_credentials}
      ```
    Replace `{your_credentials}` with your base64-encoded Basic Auth username
    and password given to your by your Implementation Manager.

    <br /> <br />


    You **must** use the `Authorization` header for any request you send to our
    Balance API.


    __Accept Header__
      ```
        Accept: application/vnd.worldpay.accounts.balance-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 Balance API.

    <br /><br />



    __DNS Whitelisting__  

    Whitelist the following URLs:

    * `https://try.access.worldpay.com/`

    * `https://access.worldpay.com/`


    Please ensure you use DNS whitelisting, not explicit IP whitelisting.
  version: v1
  x-metadata:
    category:
      - Accounts
    business:
      - Enterprise
      - Marketplaces
    catalog-list: true
    generated: false
  license:
    name: Worldpay
    url: developers.worldpay.com/license
servers:
  - url: https://try.access.worldpay.com
    description: testing (try)
  - url: https://access.worldpay.com
    description: live
paths:
  /accounts/balance/{accountNumber}:
    get:
      summary: Get account details
      description: Retrieve the details of one specific account.
      operationId: getAccount
      parameters:
        - 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: accountNumber
          in: path
          description: The account number
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          description: BAD REQUEST response if the request is incorrectly validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  $ref: '#/components/examples/400'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  $ref: '#/components/examples/400'
        '401':
          description: UNAUTHORIZED response if JWT is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  $ref: '#/components/examples/401'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  $ref: '#/components/examples/401'
        '403':
          description: FORBIDDEN response if you are not authorized to access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FORBIDDEN:
                  $ref: '#/components/examples/403'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FORBIDDEN:
                  $ref: '#/components/examples/403'
        '404':
          description: NOT FOUND response if the AccountNumber or Page was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                NOT FOUND:
                  $ref: '#/components/examples/404'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                NOT FOUND:
                  $ref: '#/components/examples/404'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                Internal server error:
                  $ref: '#/components/examples/500'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                Internal server error:
                  $ref: '#/components/examples/500'
  /accounts/balance:
    get:
      summary: Get details for all your accounts
      description: Retrieve account details for all your accounts.
      operationId: getEntity
      parameters:
        - 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: entity
          in: query
          description: Your unique 6-digit ID given during the onboarding process.
          schema:
            type: string
            example: '11155'
      responses:
        '200':
          description: OK response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  $ref: '#/components/examples/400'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  $ref: '#/components/examples/400'
        '401':
          description: UNAUTHORIZED response if JWT is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  $ref: '#/components/examples/401'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  $ref: '#/components/examples/401'
        '403':
          description: FORBIDDEN response if you are not authorized to access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FORBIDDEN:
                  $ref: '#/components/examples/403'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FORBIDDEN:
                  $ref: '#/components/examples/403'
        '404':
          description: NOT FOUND response if the AccountNumber or Page was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                NOT FOUND:
                  $ref: '#/components/examples/404'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                NOT FOUND:
                  $ref: '#/components/examples/404'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                Internal server error:
                  $ref: '#/components/examples/500'
            application/vnd.worldpay.accounts.balance-v1+json:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
              examples:
                Internal server error:
                  $ref: '#/components/examples/500'
components:
  schemas:
    Account:
      type: object
      properties:
        accountNumber:
          type: string
          description: The account number.
          nullable: true
          example: '1111557890987654'
        accountName:
          type: string
          description: >-
            The name of the account. (This is given to you during onboarding and
            typically consist of your merchant name followed by currency code.)
          nullable: true
          example: Etsy GBP
        currency:
          type: string
          description: >-
            The [ISO 4217 currency
            codes](/products/reference/supported-countries-currencies#iso-currency-codes)
            of the account.
          nullable: true
          example: GBP
        clearedBalance:
          type: number
          description: The cleared balance.
          format: double
          example: 142.5
        unclearedBalance:
          type: number
          description: The uncleared balance.
          format: double
          example: 100.8
        balance:
          type: number
          description: The total balance.
          format: double
          example: 243.5
        accountStatus:
          type: string
          description: The status of the account.
          nullable: true
          example: ACTIVE
      additionalProperties: false
    AccountResponse:
      type: object
      properties:
        entity:
          type: string
          description: Your unique 6-digit ID given to you during the onboarding process.
          nullable: true
          example: '111155'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'
          description: Collection of account details.
          nullable: true
      additionalProperties: false
      description: The GET account response.
    BaseErrorResponse:
      type: object
      properties:
        httpStatusCode:
          type: integer
          description: The HTTP status
          format: int32
        customCode:
          type: string
          description: The unique response code for this endpoint.
          nullable: true
        message:
          type: string
          description: The error message.
          nullable: true
      additionalProperties: false
      description: The error response.
    ErrorResponse:
      type: object
      properties:
        httpStatusCode:
          type: integer
          description: The HTTP status.
          format: int32
        customCode:
          type: string
          description: The unique response code for this endpoint.
          nullable: true
        message:
          type: string
          description: The error message.
          nullable: true
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
            nullable: true
          description: Collection of error details.
          nullable: true
      additionalProperties: false
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  examples:
    '400':
      value:
        httpStatusCode: 400
        customCode: ACCB05
        message: Schema validation failed
        errors:
          AccountNumber:
            - AccountNumber should be 16 digits
    '401':
      value:
        httpStatusCode: 401
        customCode: ACCU06
        message: Unauthorized request
    '403':
      value:
        httpStatusCode: 403
        customCode: ACCF18
        message: Forbidden
        errors:
          Domain:
            - Authorisation Failed for this Domain
    '404':
      value:
        httpStatusCode: 404
        customCode: ACCN15
        message: Could not find details for accountNumber
    '500':
      value:
        httpStatusCode: 500
        customCode: ACCE11
        message: Unexpected Issue. Please try again
security:
  - basicAuth: []
