Xflow Balance API

openapi: 3.0.0
info:
  contact:
    email: support@xflowpay.com
    name: Xflow Support
    url: https://xflowpay.com
  description: The Xflow REST API. Please see https://docs.xflowpay.com/2024-02-05/api for more details.
  termsOfService: https://docs.xflowpay.com/platform-agreement
  title: Xflow Accounts Balance API
  version: '2024-02-05'
servers:
- url: https://api.xflowpay.com/
security:
- bearerAuth: []
tags:
- name: Balance
paths:
  /v1/balance:
    get:
      description: Retrieve a balance.
      operationId: RetrieveBalance
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - description: Unique identifier for the account object for which this balance is associated. If this is not specified, then the balance object will be returned for the context that the user is in.
        in: query
        name: account_id
        required: false
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/balance'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Balance
  /v1/balance/aggregate:
    get:
      description: Retrieve an aggregate balance.
      operationId: RetrieveAggregateBalance
      parameters:
      - description: This header specifies the connected user's account on behalf of which the request is being made.
        in: header
        name: Xflow-Account
        required: false
        schema:
          type: string
      - description: Unique identifier for the account object for which this balance is associated. If this is not specified, then the balance object will be returned for the context that the user is in.
        in: query
        name: account_id
        required: false
        schema:
          type: string
      responses:
        '200':
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/balance'
          description: Successful response.
        default:
          headers:
            Date:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            Connection:
              schema:
                type: string
            x-amzn-RequestId:
              schema:
                type: string
            xflow-request-id:
              schema:
                type: string
            x-amz-apigw-id:
              schema:
                type: string
            X-Amzn-Trace-Id:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_object'
          description: Error response.
      tags:
      - Balance
components:
  schemas:
    balance:
      description: The balance object represents a snapshot of the user's balance within Xflow.
      properties:
        account_id:
          description: Unique identifier for the account object for which this balance is associated.
          type: string
        available:
          description: Funds that are available to the user within Xflow. For example, this could be funds which have been reconciled, but have not yet been picked up for reconciliation.
          items:
            properties:
              amount:
                description: Balance amount.
                type: string
              currency:
                description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                enum:
                - AED
                - AUD
                - CHF
                - CZK
                - DKK
                - EUR
                - GBP
                - HKD
                - INR
                - NOK
                - PLN
                - SEK
                - SGD
                - USD
                type: string
            title: BalanceAvailable
            type: object
          nullable: true
          type: array
        fee_advance:
          description: Funds that have been transferred by the user to maintain balance within Xflow to enable connected users to have fees lower than the passthrough fees. This is `[]` for non-platform users.
          items:
            properties:
              amount:
                description: Balance amount.
                type: string
              currency:
                description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                enum:
                - AED
                - AUD
                - CHF
                - CZK
                - DKK
                - EUR
                - GBP
                - HKD
                - INR
                - NOK
                - PLN
                - SEK
                - SGD
                - USD
                type: string
            title: BalanceFeeAdvance
            type: object
          nullable: true
          type: array
        livemode:
          description: Has the value true if the object exists in `livemode` or the value false if the object exists in `testmode`.
          type: boolean
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - balance
          type: string
        payout_processing:
          description: Funds that are being processed for payouts by Xflow.
          items:
            properties:
              amount:
                description: Balance amount.
                type: string
              currency:
                description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                enum:
                - AED
                - AUD
                - CHF
                - CZK
                - DKK
                - EUR
                - GBP
                - HKD
                - INR
                - NOK
                - PLN
                - SEK
                - SGD
                - USD
                type: string
            title: BalancePayoutProcessing
            type: object
          nullable: true
          type: array
        pending:
          description: Funds that are not yet available to the user within Xflow. For example, this could be funds which have been received against a particular account identifier but have not yet been reconciled.
          items:
            properties:
              amount:
                description: Balance amount.
                type: string
              currency:
                description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                enum:
                - AED
                - AUD
                - CHF
                - CZK
                - DKK
                - EUR
                - GBP
                - HKD
                - INR
                - NOK
                - PLN
                - SEK
                - SGD
                - USD
                type: string
            title: BalancePending
            type: object
          nullable: true
          type: array
        processing:
          description: Funds that are being processed by Xflow. This is an intermediate state. For example, transfers may result in the funds being in the processing compartment momentarily, before they reach the destination compartment.
          items:
            properties:
              amount:
                description: Balance amount.
                type: string
              currency:
                description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-digit code for the amount currency.
                enum:
                - AED
                - AUD
                - CHF
                - CZK
                - DKK
                - EUR
                - GBP
                - HKD
                - INR
                - NOK
                - PLN
                - SEK
                - SGD
                - USD
                type: string
            title: BalanceProcessing
            type: object
          nullable: true
          type: array
      title: Balance
      type: object
    error_object:
      description: 'Xflow uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.). Codes in the `5xx` range indicate an error with Xflow’s servers (these are rare).'
      properties:
        errors:
          description: An array of errors. Each element is a specific error.
          maxItems: 1
          minItems: 1
          items:
            properties:
              code:
                description: Enum value specific to the error. All Xflow error codes are defined [here](https://docs.xflowpay.com/latest/errors).
                enum:
                - account_activation_failed_missing_payout_address
                - account_activation_failed_missing_person
                - account_activation_failed_incorrect_number_of_persons
                - account_activation_failed_incorrect_relationship_for_person
                - account_email_invalid
                - account_id_invalid
                - account_not_unique_nickname
                - account_parameter_not_editable
                - account_partner_activate_disallowed
                - account_partner_deactivate_disallowed
                - account_platform_activate_disallowed
                - account_platform_create_disallowed
                - account_setting_parameter_not_editable
                - account_status_invalid
                - account_type_invalid
                - account_update_access_unauthorized
                - account_user_activate_disallowed
                - account_user_create_disallowed
                - action_invalid
                - action_not_enabled
                - action_unauthorized
                - address_cannot_be_deactivated
                - address_category_mismatch
                - address_category_not_allowed
                - address_domestic_credit_invalid
                - address_global_wire_invalid
                - address_global_wire_not_supported
                - address_parameter_not_editable
                - address_type_not_allowed
                - balance_insufficient
                - cancelled_request
                - country_code_invalid
                - country_code_not_supported
                - currency_amount_mismatch
                - currency_not_supported
                - date_invalid_format
                - deposit_account_address_mismatch
                - deposit_account_id_mismatch
                - deposit_parameter_not_editable
                - duplicate_currencies_not_supported
                - duplicate_values_found
                - event_type_invalid
                - fee_plan_parameter_not_editable
                - file_name_invalid
                - file_name_length_invalid
                - file_parameter_not_editable
                - file_purpose_mismatch
                - file_size_limit_exceeded
                - file_request_body_invalid
                - file_type_unsupported
                - header_parameter_invalid
                - header_parameter_missing
                - http_parameter_invalid
                - invalid_amount
                - invoice_date_invalid
                - invoice_due_date_invalid
                - metadata_count_exceeded
                - metadata_key_max_length_invalid
                - metadata_key_min_length_invalid
                - metadata_value_max_length_invalid
                - metadata_value_min_length_invalid
                - multiple_xflow_receive_same_category_not_allowed
                - minimum_required_values_not_present
                - object_not_found
                - parameter_address_invalid
                - parameter_character_invalid
                - parameter_empty
                - parameter_file_invalid
                - parameter_max_length_invalid
                - parameter_min_length_invalid
                - parameter_range_invalid
                - parameter_receivable_invalid
                - parameter_unexpected
                - parameter_value_invalid
                - payment_link_account_receivable_mismatch
                - payment_link_activate_disallowed
                - payment_link_deactivate_invalid
                - payment_link_expire_invalid
                - payment_link_extend_disallowed
                - payment_link_extend_invalid
                - payment_link_non_us_account_non_usd_currency
                - payment_link_parameter_not_editable
                - payment_link_receivable_count_exceed
                - payment_link_receivable_status_invalid
                - payout_parameter_not_editable
                - person_delete_not_allowed
                - person_parameter_not_editable
                - person_relationship_not_set
                - person_update_not_allowed
                - purpose_code_not_supported
                - receivable_additional_info_required
                - receivable_amount_invoice_amount_mismatch
                - receivable_amount_maximum_reconcilable_incorrect
                - receivable_cancel_disallowed
                - receivable_confirm_action_disallowed
                - receivable_creation_date_invoice_creation_date_mismatch
                - receivable_currency_invoice_currency_mismatch
                - receivable_due_date_invoice_due_date_mismatch
                - receivable_hold
                - receivable_invoice_document_incorrect
                - receivable_invoice_reference_number_exists
                - receivable_invoice_transaction_type_incorrect
                - receivable_parameter_not_editable
                - receivable_partner_country_invoice_partner_country_mismatch
                - receivable_partner_invoice_partner_mismatch
                - receivable_reconcile_action_disallowed
                - receivable_reconcile_amount_exceed
                - receivable_reference_number_invoice_reference_number_mismatch
                - receivable_unable_to_process
                - receivable_update_access_unauthorized
                - request_body_invalid
                - request_query_parameter_invalid
                - resource_locked
                - secret_key_invalid
                - secret_key_missing
                - testmode_action_only
                - timestamp_invalid
                - transfer_failed
                - transfer_parameter_not_editable
                - transfer_type_invalid
                - url_invalid
                - webhook_endpoint_limit_exceeded
                - webhook_endpoint_parameter_not_editable
                - website_invalid
                type: string
              message:
                description: Description of the error with guidance on how to recover.
                type: string
              metadata:
                additionalProperties:
                  type: string
                description: Additional information associated with the error in the form of key-value pairs.
                nullable: true
                title: ErrorMetadata
                type: object
            title: ErrorObjectSingle
            type: object
          type: array
        http_status_code:
          description: HTTP status code.
          type: integer
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - error
          type: string
      title: ErrorObject
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: auth-scheme
      description: 'Bearer HTTP authentication. Allowed headers-- Authorization: Bearer <api_key>'
      scheme: bearer
      type: http