Xflow Account Settings API

openapi: 3.2.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 Account Settings API
  version: '2024-02-05'
servers:
- url: https://api.xflowpay.com/
security:
- bearerAuth: []
tags:
- name: Account Settings
paths:
  /v1/account_settings:
    get:
      description: This endpoint returns all AccountSettings (filtered by the applied below query parameters) associated with the platform, connected user or direct user in question.
      operationId: ListAccountSettings
      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: This parameter represents the account object with which the AccountSetting object is associated.
        in: query
        name: account_id
        required: false
        schema:
          items:
            enum:
            - draft
            - verifying
            - activated
            - deactivated
            - hold
            type: string
          type: array
      - description: Indicates whether an address is available by default for a connected user.
        in: query
        name: address.connected_user
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a connected user's partner.
        in: query
        name: address.connected_user_partner
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a partner.
        in: query
        name: address.partner
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a platform.
        in: query
        name: address.platform
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a user.
        in: query
        name: address.user
        required: false
        schema:
          type: boolean
      - description: Return results where the `created` field is equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.eq
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: A cursor for use in pagination. `ending_before` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
        in: query
        name: ending_before
        required: false
        schema:
          type: string
      - description: A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: Whether Xflow can send payouts to this account. This parameter can be set by Xflow for a direct user or by the platform on behalf of a connected user. The former is an Xflow account of `type=user` which is not connected to an account of `type=platform`.
        in: query
        name: payouts.enabled
        required: false
        schema:
          type: boolean
      - description: The reason code if payouts are not enabled.
        in: query
        name: payouts.reason_code_not_enabled
        required: false
        schema:
          items:
            enum:
            - account_not_activated
            - platform_hold
            - xflow_hold
            type: string
          type: array
      - description: A cursor for use in pagination. `starting_after` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with `obj_bar`, your subsequent call can include `starting_after=obj_bar` in order to fetch the next page of the list.
        in: query
        name: starting_after
        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:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/account_setting'
                    type: array
                  has_next:
                    description: True if this list has another page of items after this one that can be fetched.
                    type: boolean
                  object:
                    description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
                    enum:
                    - list
                    type: string
                title: ListAccountSettingsResponse
                type: object
          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:
      - Account Settings
      summary: List account settings
      x-summary-source: derived
  /v1/account_settings/connected:
    get:
      description: This endpoint returns all AccountSettings (filtered by the applied below query parameters) associated with the connected users of a platform.
      operationId: ListAccountSettingsConnected
      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: This parameter represents the account object with which the AccountSetting object is associated.
        in: query
        name: account_id
        required: false
        schema:
          items:
            enum:
            - draft
            - verifying
            - activated
            - deactivated
            - hold
            type: string
          type: array
      - description: Indicates whether an address is available by default for a connected user.
        in: query
        name: address.connected_user
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a connected user's partner.
        in: query
        name: address.connected_user_partner
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a partner.
        in: query
        name: address.partner
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a platform.
        in: query
        name: address.platform
        required: false
        schema:
          type: boolean
      - description: Indicates whether an address is available by default for a user.
        in: query
        name: address.user
        required: false
        schema:
          type: boolean
      - description: Return results where the `created` field is equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.eq
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is greater than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.gte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lt
        required: false
        schema:
          format: unix-time
          type: integer
      - description: Return results where the `created` field is lesser than or equal to the timestamp value in seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time).
        in: query
        name: created.lte
        required: false
        schema:
          format: unix-time
          type: integer
      - description: A cursor for use in pagination. `ending_before` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
        in: query
        name: ending_before
        required: false
        schema:
          type: string
      - description: A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: Whether Xflow can send payouts to this account. This parameter can be set by Xflow for a direct user or by the platform on behalf of a connected user. The former is an Xflow account of `type=user` which is not connected to an account of `type=platform`.
        in: query
        name: payouts.enabled
        required: false
        schema:
          type: boolean
      - description: The reason code if payouts are not enabled.
        in: query
        name: payouts.reason_code_not_enabled
        required: false
        schema:
          items:
            enum:
            - account_not_activated
            - platform_hold
            - xflow_hold
            type: string
          type: array
      - description: A cursor for use in pagination. `starting_after` is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with `obj_bar`, your subsequent call can include `starting_after=obj_bar` in order to fetch the next page of the list.
        in: query
        name: starting_after
        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:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/account_setting'
                    type: array
                  has_next:
                    description: True if this list has another page of items after this one that can be fetched.
                    type: boolean
                  object:
                    description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
                    enum:
                    - list
                    type: string
                title: ListAccountSettingsConnectedResponse
                type: object
          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:
      - Account Settings
      summary: List account settings connected
      x-summary-source: derived
  /v1/account_settings/{account_setting}:
    get:
      description: Retrieves the details of an AccountSetting.
      operationId: RetrieveAccountSetting
      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
      - in: path
        name: account_setting
        required: true
        schema:
          type: string
        style: simple
      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/account_setting'
          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:
      - Account Settings
      summary: Retrieve account setting
      x-summary-source: derived
    post:
      description: Update the details of an AccountSetting.
      operationId: UpdateAccountSetting
      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
      - in: path
        name: account_setting
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              properties:
                address:
                  description: Default values for address of category `xflow_receive` availability for different types of accounts.
                  properties:
                    connected_user:
                      description: Indicates whether an address is available by default for a connected user.
                      type: boolean
                    connected_user_partner:
                      description: Indicates whether an address is available by default for a connected user's partner.
                      type: boolean
                    partner:
                      description: Indicates whether an address is available by default for a partner.
                      type: boolean
                  title: UpdateAccountSettingRequestAddress
                  type: object
                address_currency:
                  description: Default values for address of category `xflow_receive` availability for different types of accounts.
                  properties:
                    connected_user:
                      description: Indicates whether an address is available by default for a connected user.
                      items:
                        type: string
                      type: array
                    connected_user_partner:
                      description: Indicates whether an address is available by default for a connected user's partner.
                      items:
                        type: string
                      type: array
                    partner:
                      description: Indicates whether an address is available by default for a partner.
                      items:
                        type: string
                      type: array
                    user:
                      description: Indicates whether an address is available by default for a user.
                      items:
                        type: string
                      type: array
                  title: UpdateAccountSettingRequestAddressCurrency
                  type: object
                metadata:
                  additionalProperties:
                    type: string
                  description: Set of [key-value pairs](https://docs.xflowpay.com/2024-02-05/api#metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
                  title: UpdateAccountSettingRequestMetadata
                  type: object
                payouts:
                  description: Payouts details.
                  properties:
                    enabled:
                      description: Whether Xflow can send payouts to this account. This parameter can be set by Xflow for a direct user or by the platform on behalf of a connected user. The former is an Xflow account of `type=user` which is not connected to an account of `type=platform`.
                      type: boolean
                    interval:
                      description: How frequently funds will be paid out. One of `daily`, `weekly`, or `monthly`.
                      enum:
                      - daily
                      - weekly
                      - monthly
                      type: string
                    monthly_anchor:
                      description: The day of the month funds will be paid out. Only applies if interval is monthly. Payouts scheduled between the 29th and 31st of the month are sent on the last day of shorter months.
                      format: int64
                      maximum: 31
                      minimum: 1
                      type: integer
                    weekly_anchor:
                      description: The day of the week funds will be paid out, of the style ‘monday’, ‘tuesday’, etc. Only applies if interval is `weekly`.
                      enum:
                      - monday
                      - tuesday
                      - wednesday
                      - thursday
                      - friday
                      - saturday
                      - sunday
                      type: string
                  title: UpdateAccountSettingPayouts
                  type: object
              title: UpdateAccountSettingRequest
              type: object
      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/account_setting'
          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:
      - Account Settings
      summary: Update account setting
      x-summary-source: derived
components:
  schemas:
    account_setting:
      description: Account objects are fundamental to Xflow and model entities like direct users, connected users, partners and platforms. Depending on whether you are setup as a direct user or platform, you can create new accounts, retrieve existing accounts to see it’s properties or take action on accounts to accept funds on their behalf.
      properties:
        address:
          description: Default values for address of category `xflow_receive` availability for different types of accounts.
          properties:
            connected_user:
              description: Indicates whether an address is available by default for a connected user. This is set to `null` for a connected user and a direct user AccountSetting.
              type: boolean
            connected_user_partner:
              description: Indicates whether an address is available by default for a connected user's partner. This is set to `null` for a direct user AccountSetting.
              type: boolean
            partner:
              description: Indicates whether an address is available by default for a partner.
              type: boolean
            platform:
              description: Indicates whether an address is available by default for a platform. This is set to `null` for a connected user and a direct user AccountSetting.
              type: boolean
            user:
              description: Indicates whether an address is available by default for a user. This is set to `null` for a platform AccountSetting.
              type: boolean
          title: AccountSettingAddress
          type:
          - object
          - 'null'
        address_currency:
          description: Default values for the currency for address of category `xflow_receive` for different types of accounts.
          properties:
            connected_user:
              description: Indicates the default currency for a connected user. This is set to `null` for a connected user and a direct user AccountSetting.
              items:
                type: string
              type: array
            connected_user_partner:
              description: Indicates the default currency for a connected user's partner. This is set to `null` for a direct user AccountSetting.
              items:
                type: string
              type: array
            partner:
              description: Indicates the default currency for a partner.
              items:
                type: string
              type: array
            platform:
              description: Indicates the default currency for a platform. This is set to `null` for a connected user and a direct user AccountSetting.
              items:
                type: string
              type: array
            user:
              description: Indicates the default currency for a user. This is set to `null` for a platform AccountSetting.
              items:
                type: string
              type: array
          title: AccountSettingAddressCurrency
          type:
          - object
          - 'null'
        created:
          description: The seconds elapsed since [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) at which the account was created.
          format: unix-time
          type: integer
        id:
          description: Unique identifier for the object.
          type: string
        live_fx:
          description: Indicates whether live FX is enabled for a platform's connected users. If `true`, payouts are processed immediately for all connected users. At present, this will be set to `false`.
          type:
          - boolean
          - 'null'
        livemode:
          description: Has the value `true` if the object exists in livemode, the value `false` if the object exists in testmode or `null` in the case of a direct user or a platform (a direct user is an Xflow account of `type=user` which is not connected to an account of `type=platform`).
          type:
          - boolean
          - 'null'
        metadata:
          additionalProperties:
            type: string
          description: Set of [key-value pairs](https://docs.xflowpay.com/2024-02-05/api#metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          title: AccountSettingMetadata
          type:
          - object
          - 'null'
        object:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - account_setting
          type: string
        payouts:
          description: Payouts details.
          properties:
            enabled:
              description: Whether Xflow can send payouts to this account. This parameter can be set by Xflow for a direct user or by the platform on behalf of a connected user. The former is an Xflow account of `type=user` which is not connected to an account of `type=platform`.
              type: boolean
            interval:
              description: How frequently funds will be paid out. One of `daily`, `weekly`, or `monthly`.
              enum:
              - daily
              - weekly
              - monthly
              type: string
            monthly_anchor:
              description: The day of the month funds will be paid out. Only applies if interval is monthly. Payouts scheduled between the 29th and 31st of the month are sent on the last day of shorter months.
              format: int64
              maximum: 31
              minimum: 1
              type:
              - integer
              - 'null'
            reason_code_not_enabled:
              description: The reason code if payouts are not enabled. Valid values include `account_not_activated`, `platform_hold` and `xflow_hold`.
              type:
              - string
              - 'null'
            weekly_anchor:
              description: The day of the week funds will be paid out, of the style ‘monday’, ‘tuesday’, etc. Only applies if interval is `weekly`.
              enum:
              - monday
              - tuesday
              - wednesday
              - thursday
              - friday
              - saturday
              - sunday
              type:
              - string
              - 'null'
          title: AccountSettingPayouts
          type:
          - object
          - 'null'
      title: AccountSetting
      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_

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xflow/refs/heads/main/openapi/xflow-account-settings-api-openapi.yml