openapi-spec.yaml

openapi: 3.0.0
info:
  title: Busha API
  contact:
    email: developers@busha.co
  description: |
    ## Introduction
    The **Busha API** is designed to provide businesses with tools for borderless financial transactions and operations, enabling modern, global money management. It serves as the backbone for facilitating:
    - Creation and management of multi-currency balances
    - Retrieval of real-time cryptocurrency rates
    - Substantial data insights for business owners

    Whether you’re a product-driven fintech or a developer building integrations, this API significantly accelerates implementation while reducing financial complexities.
    For detailed guides on API integration, visit our [official documentation]().


    ## Authentication
    All API requests require a **Bearer Token** for authentication, passed in the `Authorization` header.
    Your authorization value is a base64 encoded value of your api key and your secret key.
    You can obtain API tokens via your Busha user or business account. Authentication is mandatory to ensure secure and authorized interactions with the API.
    The API keys from the dashboard provides a base64 encoding of the your authorization tokens.

    Your generated Key should look like this:
    `VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=`

    Example Header:
    ``` curl
    Authorization: Bearer VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=
    ```

    ## Error Handling
    #Standardized error responses ensure predictable interactions. Errors are detailed for easy debugging and understanding:
    | **Error Code** | **HTTP Status Code** | **Description** |
    | --- | --- | --- |
    | `bad_request` | 400 | Invalid input or malformed request |
    | `unauthorized` | 401 | Invalid or missing authentication |
    | `not_found` | 404 | Resource not found |
    | `service_unavailable` | 503 | Server error |

    Basic Error Example:
    ``` json
    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      }
    }
    ```

    Schema Error Body Example:
    ``` json
    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "schema": {
        "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
        "fix": "Ensure that the object being submitted, matches the schema correctly"
      }
    }
    ```

    Field Error Body Example:
    ``` json
    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "fields": {
        "field1": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          },
        ],
        "field2": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          }
        ],
      }
    }
    ```

    ## Pagination
    Pagination uses cursors provided as:
    The API supports **cursor-based pagination** for endpoints with large datasets. Pagination uses a `next_cursor` and `previous_cursor` returned in the response.
    Example Response Format:
    ``` json
    {
      "current_entries_size": 10,
      "next_cursor": "base64_cursor_value",
      "previous_cursor": "base64_previous_cursor_value"
    }
    ```

    ## Rate Limiting
    Rate limits determine how many API calls can be made in a rolling minute. This ensures fair and optimized use of system resources.

    The rate limits allowed by each resource will be provided with the header:
    ```curl
    x-rate-limit 100
    ```
    If this header does not exist, then the rate limit is set at a default 100 req/min

    Requests exceeding the allocated quota will receive a `429 Too Many Requests` response.

    ##  Common Parameters
    Common parameters enhance consistency across endpoints:
      | **Parameter Name** | **Location** | **Description** | **Example** |
      | --- | --- | --- | --- |
      | `X-BU-PROFILE-ID` | Header | User profile identifier | `BUS_qwejinoiuiqw93ejjw` |
      | `id` | Path | Unique NanoID identifier | `dpt_jweqafajsndiun34fd` |
      | `cursor` | Query | Pagination cursor | `base64_cursor_string` |

    #### Paginated Response Example
      ``` json
      {
        "status": "success",
        "message": "Data retrieved",
        "pagination": {
          "next_cursor": "value_for_next_page",
          "current_entries_size": 20
        },
        "data": [...]
      }
      ```
  version: 1.0.0
servers:
  - url: https://api.sandbox.busha.so
    description: Sandbox Environment
  - url: https://api.busha.io
    description: Production Environment
tags:
  - name: Balances
    description: Handles account balances across different currencies
    x-displayName: Balances
  - name: Bills
    description: Lorem Ipsum
    x-displayName: Bills
  - name: Cards
    description: Lorem Ipsum
    x-displayName: Cards
  - name: Cashback
    description: Main tag for cashback service endpoints
    x-displayName: Cashback
  - name: Currencies
    description: |
      Endpoints to manage supported currencies, their properties, and network details.
    x-displayName: Currencies
  - name: Customers
    x-internal: false
    description: Handle customer requests and responses
    x-displayName: Customers
  - name: Files
    description: Provides APIs to handle files upload
    x-displayName: Files
  - name: Mandate
    x-displayName: Mandate
  - name: Miscellaneous
    description: Provides auxiliary APIs to complement and enhance other services.
    x-displayName: Miscellaneous
  - name: News
    description: News article endpoints
    x-displayName: News
  - name: Pairs
    description: Access trading pair information and rates
    x-displayName: Pairs
  - name: PaymentLinks
    description: Payment Links
    x-displayName: PaymentLinks
  - name: PaymentRequests
    description: Payment request
    x-displayName: PaymentRequests
  - name: PriceAlerts
    description: Price alert management endpoints
    x-displayName: PriceAlerts
  - name: Quotes
    description: Handle quotes requests and responses
    x-displayName: Quotes
  - name: Recipients
    x-displayName: Recipients
  - name: Transactions
    x-displayName: Transactions
  - name: Transfers
    x-displayName: Transfers
  - name: Widget
    description: Widget operations
    x-displayName: Widget
paths:
  /v1/balances:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - balances:write
            - api:write
      tags:
        - Balances
      operationId: createBalance
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      summary: Create currency balance
      description: Creates a new balance for managing funds in a specific currency.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBalanceRequest'
      responses:
        '201':
          description: Balance created successfully
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Balance'
        4XX:
          $ref: '#/components/responses/BalanceError4XX'
        5XX:
          $ref: '#/components/responses/BalanceError5XX'
    get:
      tags:
        - Balances
      operationId: listBalances
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: currency
          in: query
          schema:
            $ref: '#/components/schemas/Currency'
      summary: List all balances
      description: Retrieves all account balances with their current status.
      responses:
        '200':
          description: List of account balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
        4XX:
          $ref: '#/components/responses/BalanceError4XX'
        5XX:
          $ref: '#/components/responses/BalanceError5XX'
      security:
        - Auth:
            - balances:read
            - api:read
  /v1/balances/{id_or_code}:
    get:
      tags:
        - Balances
      operationId: getBalance
      summary: Get balance details
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: id_or_code
          in: path
          required: true
          schema:
            type: string
          description: Balance ID or currency code
      responses:
        '200':
          description: Balance details retrieved successfully
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Balance'
        4XX:
          $ref: '#/components/responses/BalanceError4XX'
        5XX:
          $ref: '#/components/responses/BalanceError5XX'
      security:
        - Auth:
            - balances:read
            - api:read
  /v1/bill/purchase:
    post:
      operationId: PurchaseBill
      summary: Purchase a bill
      description: Create a bill payment order. Holds funds from the customer's balance and initiates the purchase with the provider.
      tags:
        - Bill
      security:
        - Auth:
            - bill:write
            - api:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/BillOrder'
  /v1/bill/quote:
    post:
      operationId: QuotePurchase
      summary: Get a purchase quote
      description: |
        Returns a real-time cost breakdown before purchase. Shows bill amount, source amount, exchange rate (if cross-currency), fees, and total. Stateless — no DB record, no rate locking.
      tags:
        - Bill
      security:
        - Auth:
            - bill:read
            - api:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseQuoteRequest'
      responses:
        '200':
          description: Quote generated
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PurchaseQuoteResponse'
  /v1/bill/orders:
    get:
      operationId: ListBillOrders
      summary: List customer orders
      description: Returns bill orders for the authenticated customer, newest first.
      tags:
        - Bill
      parameters:
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - name: status
          in: query
          required: false
          description: Filter by order status
          schema:
            type: string
            enum:
              - pending
              - processing
              - completed
              - failed
              - cancelled
        - name: category
          in: query
          required: false
          description: Filter by bill category
          schema:
            type: string
            enum:
              - airtime
              - data
              - electricity
              - cable
              - betting
              - voucher
        - name: voucher_status
          in: query
          required: false
          description: |
            Filter voucher orders by lifecycle status. `unusable` is a virtual bucket that matches fully_used OR expired OR inactive vouchers — i.e. everything the customer can no longer redeem.
          schema:
            type: string
            enum:
              - active
              - fully_used
              - expired
              - inactive
              - unknown
              - unusable
      responses:
        '200':
          description: Orders retrieved
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CursorPagination'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/BillOrder'
      security:
        - Auth:
            - bill:read
            - api:read
  /v1/bill/orders/{id}:
    get:
      operationId: GetBillOrder
      summary: Get order details
      description: Returns a single bill order by ID, scoped to the authenticated customer.
      tags:
        - Bill
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
      responses:
        '200':
          description: Order retrieved
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/BillOrder'
      security:
        - Auth:
            - bill:read
            - api:read
  /v1/currencies:
    get:
      security:
        - AuthOptional: []
      tags:
        - Currencies
      summary: Retrieve supported currencies
      description: |
        Retrieves a list of all supported currencies along with their basic details. This endpoint can be used to display available currencies in wallets or APIs requiring currency data.
      operationId: listCurrencies
      parameters:
        - $ref: '#/components/parameters/XBuPublicKey'
        - $ref: '#/components/parameters/CurrencyType'
        - $ref: '#/components/parameters/SortQueryParam'
        - name: payments_request
          in: query
          required: false
          schema:
            type: boolean
        - name: ramp
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A list of supported currencies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrenciesListResponse'
        4XX:
          $ref: '#/components/responses/CurrenciesError4XX'
        5XX:
          $ref: '#/components/responses/CurrenciesError5XX'
  /v1/currencies/{code}:
    get:
      security:
        - AuthOptional: []
      tags:
        - Currencies
      summary: Retrieve details of a specific currency
      description: |
        Fetches detailed information about a specific currency using its unique code. This includes details such as network support, decimal precision, and transaction limits.
      parameters:
        - $ref: '#/components/parameters/CurrencyCodePathParam'
        - $ref: '#/components/parameters/ProfileHeader'
      operationId: getCurrency
      responses:
        '200':
          description: Details of the requested currency.
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Currencies'
        4XX:
          $ref: '#/components/responses/CurrenciesError4XX'
        5XX:
          $ref: '#/components/responses/CurrenciesError5XX'
  /v1/customers:
    post:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Create a new customer
      description: Creates a new customer entry in the system. The required fields depend on the `type` of customer being created ('individual' or 'business').
      operationId: createCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Customer details needed to create a new customer.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            examples:
              individual_customer:
                summary: Individual Customer
                description: An example of a request payload to create an **individual** customer profile.
                value:
                  email: johninu@busha.co
                  has_accepted_terms: true
                  type: individual
                  country_id: NG
                  phone: '+2348012345678'
                  birth_date: 24-12-1990
                  first_name: John
                  last_name: Doe
                  address:
                    street: 123 Main Street
                    city: Lagos
                    state: Lagos
                    postal_code: '100211'
                    country: NG
              business_customer:
                summary: Business Customer
                description: An example of a request payload to create a **business** customer profile. Note the additional `business_*` fields.
                value:
                  email: johninu@busha.co
                  has_accepted_terms: true
                  type: business
                  country_id: NG
                  phone: '+2348098765432'
                  address:
                    street: 456 Corporate Avenue
                    city: Abuja
                    state: FCT
                    postal_code: '900288'
                    country: NG
                  business_name: ABC Corporation
                  business_industry: BIN_C4UvTYR5V8jsOx5LmwQ
                  business_incorporation_date: '2015-06-15'
      responses:
        '201':
          $ref: '#/components/responses/CustomerResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
    get:
      x-internal: false
      summary: List Customers
      description: List all customers in created for the business
      operationId: listCustomers
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - name: q
          in: query
          x-internal: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:100
          schema:
            type: string
            maxLength: 100
            minLength: 3
            example: kay@busha.co
      responses:
        '200':
          $ref: '#/components/responses/CustomerListResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
      security:
        - Auth:
            - customers:read
            - api:read
  /v1/customers/export:
    get:
      x-internal: false
      summary: Export Customers
      description: Export customers to a csv file
      operationId: exportCustomers
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/SortQueryParam'
        - name: q
          in: query
          x-internal: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:100
          schema:
            type: string
            maxLength: 100
            minLength: 3
            example: kay@busha.co
      responses:
        '200':
          description: Successful response
          content:
            text/csv:
              schema:
                type: string
                format: binary
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
      security:
        - Auth:
            - customers:read
            - api:read
  /v1/customers/{id}:
    get:
      x-internal: false
      summary: Get a customer by ID
      description: Retrieve a specific customer by their unique ID
      operationId: getCustomerByID
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/CustomerResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
      security:
        - Auth:
            - customers:read
            - api:read
    put:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Update a customer
      description: Update the details of an existing customer
      operationId: updateCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Customer details to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
      responses:
        '200':
          $ref: '#/components/responses/CustomerResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
    delete:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Delete a customer
      description: Delete a customer by their unique ID
      operationId: deleteCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '204':
          description: Successfully deleted the customer (No Content)
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/{id}/verify:
    post:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Verify a customer
      description: Verify the identity and information provided by a customer
      operationId: verifyCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/GeneralResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/{id}/token-share:
    post:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Share customer token
      description: Token sharing.
      operationId: customerTokenShare
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        required: true
        description: JWT token to be shared for the customer
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerTokenShareRequest'
            examples:
              default:
                summary: Token share request
                value:
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          $ref: '#/components/responses/GeneralResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/industries:
    get:
      x-internal: false
      summary: List Business Industries
      description: List all business industries
      operationId: listIndustries
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      tags:
        - Customers
      responses:
        '200':
          $ref: '#/components/responses/CustomerBusinessIndustries'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
      security:
        - Auth:
            - customers:read
            - api:read
  /v1/files:
    post:
      x-rate-limit: 10
      security:
        - Auth:
            - presign_url:write
            - api:write
      tags:
        - Files
      summary: Generate presigned upload URL
      description: Generates a presigned URL for uploading files directly to storage
      operationId: generatePresignedURL
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Request parameters for presigned URL
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresignedUrlRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignedUrlResponse'
        4XX:
          $ref: '#/components/responses/FilesError4XX'
        5XX:
          $ref: '#/components/responses/FilesError5XX'
  /v1/validate:
    post:
      x-rate-limit: 5
      tags:
        - Miscellaneous
      summary: Validate payment destination
      description: validates a payment destination is valid
      operationId: validatePaymentDestination
      requestBody:
        description: validate a payment destination
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateDestinationRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateDestinationResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
      security: []
  /v1/banks:
    get:
      x-rate-limit: 20
      tags:
        - Miscellaneous
      summary: List banks resource
      description: Returns a list of all banks and their bank codes
      operationId: listBanks
      parameters:
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - $ref: '#/components/parameters/CountryQueryParam'
        - name: direct_debit
          in: query
          required: false
          description: Filter by direct debit support
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBankResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
      security: []
  /v1/countries:
    get:
      tags:
        - Miscellaneous
      summary: Returns a list of countries
      description: Returns a list of countries and their supported payment channels
      operationId: listCountries
      parameters:
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CountryQueryParam'
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - $ref: '#/components/parameters/ProfileHeader'
        - name: withdrawal
          in: query
          required: false
          description: Filter countries by withdrawal support
          schema:
            type: boolean
        - name: deposit
          in: query
          required: false
          description: Filter countries by deposit support
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountriesListResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
      security: []
  /v1/pay/{username}:
    get:
      x-rate-limit: 5
      security:
        - Auth: []
      tags:
        - Miscellaneous
      summary: Look up users addresses
      description: Returns a user's addresses based on currency and network
      operationId: lookupUserAddresses
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
          description: Username to lookup addresses for
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:50|ends_with:busha
            filter: trim|lower
        - name: currency
          in: query
          required: true
          description: Filter by currency
          x-oapi-codegen-extra-tags:
            validate: required|min_len:3|max_len:10
          schema:
            type: string
            example: USDT
        - name: networks
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Currency'
          description: Filter addresses by network
          style: form
          explode: false
          x-oapi-codegen-extra-tags:
            filter: slice_upper|slice_trim
        - name: auto_convert_to
          in: query
          required: false
          description: Currency to convert the deposit to
          schema:
            type: string
            example: NGN
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: upper|trim
      responses:
        '200':
          $ref: '#/components/responses/LookupResponses'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/addresses/{code}:
    get:
      x-rate-limit: 5
      security:
        - Auth:
            - addresses:write
            - api:write
      tags:
        - Miscellaneous
      summary: Get deposit address
      description: Get an address for a currency
      operationId: getDepositAddress
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CurrencyCodePathParam'
      responses:
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/addresses/regenerate:
    post:
      x-rate-limit: 5
      security:
        - Auth:
            - addresses:write
            - api:write
      tags:
        - Miscellaneous
      summary: Regenerate deposit address
      description: Regenerate an address for a network
      operationId: regenerateDepositAddress
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Regenerate deposit address request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegenerateDepositAddressReq'
      responses:
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/virtual_bank_accounts/{code}:
    get:
      x-rate-limit: 30
      security:
        - Auth:
            - virtual_bank_accounts:read
            - api:read
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CurrencyCodePathParam'
        - name: amount
          in: query
          required: false
          description: The amount to calculate fees for
          schema:
            type: string
            example: '100'
      tags:
        - Miscellaneous
      operationId: getVirtualBankAccount
      summary: Get virtual bank account
      description: Get a virtual bank account for a currency
      responses:
        '200':
          $ref: '#/components/responses/VirtualBankAccountResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/virtual_bank_accounts/{code}/terms:
    get:
      x-rate-limit: 10
      security:
        - Auth:
            - virtual_bank_accounts:read
            - api:read
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CurrencyCodePathParam'
      tags:
        - Miscellaneous
      operationId: getVirtualBankAccountTerms
      summary: Get virtual bank account terms
      description: Get the terms and conditions for a virtual bank account by currency code
      responses:
        '200':
          $ref: '#/components/responses/VirtualBankAccountTermsResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/pairs:
    get:
      tags:
        - Pairs
      security:
        - AuthOptional: []
      summary: List trading pairs
      description: Retrieves all available trading pairs with their current rates.
      operationId: listPairs
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: id
          in: query
          x-oapi-codegen-extra-tags:
            validate: min_len:4|max_len:20
            filter: trim|upper
          schema:
            type: string
        - name: type
          in: query
          description: |
            This filter pairs based on the type. fiat filter return pairs where the counter currency-type is a fiat crypto filter return pairs where the counter currency type is digital stablecoin filter return pairs where the base or counter currency is a stablecoin base_crypto filter return pairs where the base currency is digital base_fiat filter return pairs where the base currency is a fiat
          schema:
            type: string
            enum:
              - fiat
              - stablecoin
              - crypto
              - base_crypto
              - base_fiat
        - name: is_business
          in: query
          schema:
            type: boolean
        - name: base
          in: query
          x-oapi-codegen-extra-tags:
            validate: min_len:2|max_len:10
            filter: trim|upper
          schema:
            $ref: '#/components/schemas/Currency'
        - name: counter
          in: query
          x-oapi-codegen-extra-tags:
            validate: min_len:2|max_len:10
            filter: trim|upper
          schema:
            $ref: '#/components/schemas/Currency'
        - name: sort_by
          in: query
          schema:
            type: string
            enum:
              - alphabetical
              - date_added
              - market_cap
              - current_price
              - price_change
              - most_bought
              - most_sold
        - name: price_change_direction
          in: query
          schema:
            type: string
            enum:
              - positive
              - negative
              - absolute
        - $ref: '#/components/parameters/SortQueryParam'
      responses:
        '200':
          description: List of trading pairs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairsListResponse'
        4XX:
          $ref: '#/components/responses/PairError4XX'
        5XX:
          $ref: '#/components/responses/PairError5XX'
  /v1/payments/links:
    post:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      summary: Create a payment link
      description: Create a payment link
      operationId: createPaymentLink
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkReq'
            examples:
              invoice:
                summary: Create an invoice
                value:
                  type: invoice
                  fixed: true
                  one_time: true
                  name: Invoice for Consulting Services
                  title: Consulting Services - March 2024
                  description: Payment for consulting services rendered
                  target_currency: USDC
                  target_amount: '500.00'
                  customer_email: client@example.com
                  customer_name: John Doe
                  due_date: '2024-04-15T00:00:00Z'
                  note: Thank you for your business!
                  items:
                    - item: Consulting Hours
                      quantity: 10
                      amount: '40.00'
                    - item: Documentation Fee
                      quantity: 1
                      amount: '100.00'
              payment_link:
                summary: Create a payment link
                value:
                  fixed: true
                  one_time: false
                  name: Product Purchase
                  title: Buy Our Product
                  description: Payment for product purchase
                  target_currency: BTC
                  target_amount: '0.01'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
              examples:
                invoice:
                  summary: Invoice created successfully
                  value:
                    status: success
                    message: Payment link created successfully
                    data:
                      id: PAYL_abc123xyz
                      profile_id: PROF_user123
                      type: invoice
                      fixed: true
                      one_time: true
                      link: https://pay.busha.io/charges/PAYL_abc123xyz
                      name: Invoice for Consulting Services
                      title: Consulting Services - March 2024
                      description: Payment for consulting services rendered
                      target_currency: USDC
                      target_amount: '500.00'
                      meta:
                        customer_email: client@example.com
                        customer_name: John Doe
                        due_date: '2024-04-15T00:00:00Z'
                        note: Thank you for your business!
                        items:
                          - item: Consulting Hours
                            quantity: 10
                            amount: '40.00'
                          - item: Documentation Fee
                            quantity: 1
                            amount: '100.00'
                      status: active
                      created_at: '2024-03-10T12:00:00Z'
                      updated_at: '2024-03-10T12:00:00Z'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
    get:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - api:get
            - transfers:get
      summary: List payment links
      description: List payment links
      operationId: listPaymentLink
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - name: q
          in: query
          required: false
          description: Search query for payment links
          schema:
            type: string
        - name: status
          in: query
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PaymentLinkStatus'
        - $ref: '#/components/parameters/PaymentLinkTypeQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaymentLinkListResponse'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
  /v1/payments/links/{id}:
    get:
      tags:
        - PaymentLinks
      security:
        - AuthOptional:
            - api:get
            - transfers:get
      summary: Retrieve a payment link
      description: Retrieve a payment link
      operationId: getPaymentLink
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
    patch:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: updatePaymentLink
      summary: Update a payment link
      description: Update a payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentLinkReq'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
    delete:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: deletePaymentLink
      summary: Delete a payment link
      description: Delete a payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
  /v1/payments/links/{id}/requests:
    get:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: listPaymentLinkRequests
      summary: List payment requests for payment link
      description: List payment requests for payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - name: status
          in: query
          description: Filter by status
          required: false
          schema:
            $ref: '#/components/schemas/PaymentRequestStatus'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CursorPagination'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/PaymentRequest'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
    post:
      tags:
        - PaymentLinks
      security:
        - AuthOptional:
            - transfers:write
            - api:write
      operationId: createPaymentLinkRequest
      summary: Create a payment request for payment link
      description: Create a payment request for payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequestForLinkReq'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentRequest'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
  /v1/payments/links/{id}/activate:
    post:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: activateInvoice
      summary: Activate a draft invoice
      description: Transitions an invoice from draft status to active and sends email notification to customer
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Invoice activated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
  /v1/payments/requests:
    post:
      tags:
        - PaymentRequests
      security:
        - AuthOptional:
            - transfers:write
            - api:write
      summary: Create a payment request
      description: Create a payment request
      operationId: createPaymentRequest
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/XBuPublicKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentRequest'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
    get:
      tags:
        - PaymentRequests
      security:
        - Auth:
            - transfers:read
            - api:read
      summary: List payment requests
      description: List payment requests
      operationId: listPaymentRequests
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/PlatformIDInQueryParam'
        - name: q
          in: query
          required: false
          description: Search query for payment requests
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: filter by status
          schema:
            type: string
            description: Payment Status
        - name: asset
          in: query
          required: false
          description: filter by asset
          schema:
            type: array
            description: Payment assets
            items:
              type: string
          style: form
          explode: false
        - name: start_time
          in: query
          required: false
          description: filter by date
          schema:
            type: string
            format: date
            description: Filter by date in ISO 8601 format
            example: '2023-10-01'
        - name: end_time
          in: query
          required: false
          description: filter by date
          schema:
            type: string
            format: date
            description: Filter by date in ISO 8601 format
            example: '2023-10-01'
        - name: type
          in: query
          required: false
          description: filter by type
          schema:
            type: string
            description: Payment Type
            enum:
              - donation
              - checkout
              - invoice
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestListResponse'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
  /v1/payments/requests/{id}:
    get:
      security:
        - AuthOptional:
            - transfers:read
            - api:read
      tags:
        - PaymentRequests
      summary: Retrieve a payment request
      description: Retrieve a payment request
      operationId: getPaymentRequest
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/XBuPublicKey'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestResponse'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
  /v1/payments/requests/{id}/finalize:
    post:
      tags:
        - PaymentRequests
      security:
        - Auth:
            - transfers:write
            - api:write
      summary: Finalize a payment request
      description: Finalize a payment request
      operationId: finalizePaymentRequest
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizePaymentRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestResponse'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
  /v1/quotes:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - quotes:write
            - api:write
      summary: Create a new Quote
      description: Create Quote
      operationId: createQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/XBuPublicKey'
      requestBody:
        description: Create a new Quote
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuoteRequest'
      responses:
        '201':
          $ref: '#/components/responses/QuoteResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
    get:
      summary: List Quotes
      description: List Quotes
      operationId: listQuotes
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/QuotesListResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
      security:
        - Auth:
            - quotes:read
            - api:read
  /v1/quotes/{id}:
    get:
      summary: Get Quote
      description: Returns a single quote by it's unique ID
      operationId: getQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/QuoteResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
      security:
        - Auth:
            - quotes:read
            - api:read
  /v1/quotes/unauthenticated:
    post:
      x-rate-limit: 20
      security: []
      summary: Create Unauthenticated Quotes
      description: Create Unauthenticated Quote
      operationId: unauthenticatedCreateQuote
      tags:
        - Quotes
      requestBody:
        description: Create a unauthenticated Quote
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnauthenticatedCreateQuote'
      responses:
        '201':
          $ref: '#/components/responses/QuoteResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
  /v1/quote/payment_options:
    get:
      summary: List Payment Options
      description: List Fiat Payment Options
      operationId: listPaymentOptions
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: currency
          in: query
          required: false
          description: The currency to get payment options for.
          schema:
            type: string
            example: USD
        - name: support_conversion
          in: query
          required: false
          description: This shows if the payment options is supported for conversions
          schema:
            type: boolean
        - name: type
          in: query
          required: false
          description: The type of payment options to retrieve.
          schema:
            type: string
            example: withdraw
            enum:
              - withdraw
              - deposit
        - name: amount
          in: query
          required: false
          description: The amount to get payment options for.
          schema:
            type: number
            example: 1500
        - name: purpose
          in: query
          required: false
          description: Filter payment options by intended use case.
          schema:
            type: string
            enum:
              - wallet
              - auto_save
              - auto_buy
              - savings
              - loans
      responses:
        '200':
          $ref: '#/components/responses/PaymentOptionsListResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
      security:
        - Auth:
            - quotes:read
            - api:read
  /v1/recipients:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - recipients:write
            - api:write
      tags:
        - Recipients
      operationId: createRecipient
      summary: Create a recipient
      description: Create a new recipient for transfers.
      parameters:
        - $ref: '#/components/parameters/X-BU-Version'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipientRequest'
            examples:
              legacy_response:
                summary: Recipient creation - Legacy
                value:
                  currency_id: NGN
                  country_id: NG
                  type: ngn_bank_transfer
                  legal_entity_type: business
                  fields:
                    - name: bank_name
                      value: Access Bank Nigeria
                    - name: account_number
                      value: '1234567890'
                    - name: bank_code
                      value: '000014'
                    - name: account_name
                      value: John Doe
              ngn:
                summary: Recipient creation NGN (2025-07-11)
                value:
                  currency: NGN
                  country_code: NG
                  type: ngn_bank
                  bank_name: UNITED BANK FOR AFRICA
                  bank_code: '000004'
                  account_number: '2134211381'
                  account_name: John Doe
              usd_ach:
                summary: Recipient creation USD - ACH (2025-07-11)
                value:
                  type: usd_bank
                  entity_type: personal
                  transfer_type: ach
                  account_name: Jane Smith
                  bank_name: Chase Bank
                  routing_number: '021000021'
                  account_number: '9876543210'
              usd_wire:
                summary: Recipient creation USD - Wire (2025-07-11)
                value:
                  type: usd_bank
                  entity_type: business
                  transfer_type: wire
                  account_name: Tech Corp LLC
                  bank_name: Bank of America
                  routing_number: '026009593'
                  account_number: '1122334455'
              usd_swift:
                summary: Recipient creation USD - SWIFT (2025-07-11)
                value:
                  type: usd_bank
                  entity_type: business
                  transfer_type: swift
                  account_name: Global Corp Ltd
                  iban: GB29NWBK60161331926819
                  swift_code: CHASUS33XXX
                  bank_name: Bank of International Transfers
                  recipient_address: 123 Hauptstrasse, Berlin, 10115, Germany
                  intermediary_bank_name: Intermediary Global Bank
                  intermediary_bank_address: 456 Avenue of Banks, Zurich
                  intermediary_swift_code: CHASUS33XXX
              kes:
                summary: Recipient creation MPESA MOBILE MONEY (2025-07-11)
                value:
                  currency: KES
                  country_code: KE
                  type: mpesa_mobile_money
                  phone_number: +254 712345678
                  account_name: Business Account
              kes_business_mobile_money_till:
                summary: Recipient creation BUSINESS MOBILE MONEY - Till (2025-07-11)
                value:
                  currency: KES
                  country_code: KE
                  type: till
                  till_number: '20029'
                  account_name: Busines Name
              kes_business_mobile_money_paybill:
                summary: Recipient creation BUSINESS MOBILE MONEY - Paybill (2025-07-11)
                value:
                  currency: KES
                  country_code: KE
                  type: paybill
                  paybill: '254701548525'
                  account_number: '63902'
                  account_name: Business Account
              crypto_btc:
                summary: Recipient creation BTC (2025-07-11)
                value:
                  type: crypto
                  address_label: My Bitcoin Wallet
                  network: BTC
                  address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
              crypto_usdt_on_eth:
                summary: Recipient creation USDT ON ETH NETWORK (2025-07-11)
                value:
                  type: crypto
                  address_label: My Ethereum Wallet
                  network: ETH
                  address: '0x742d35Cc6543C4532f5D2b8d9a2b2A1234567890'
              crypto_stellar_lumens_with_memo:
                summary: Recipient creation STELLAR LUMENS (2025-07-11)
                value:
                  type: crypto
                  address_label: My Stellar Wallet
                  network: XLM
                  address: GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A
                  memo: '123456789'
      responses:
        '201':
          description: Recipient created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
              examples:
                legacy_response:
                  summary: Recipient response - Legacy
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      object: recipient
                      id: 8014c2ee-c70f-4c72-8d9f-c8b9d708a688
                      user_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      profile_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      currency_id: NGN
                      country_id: NG
                      type: ngn_bank_transfer
                      legal_entity_type: business
                      owned_by_customer: true
                      active: true
                      created_at: '2024-05-16T13:06:31.409336+01:00'
                      updated_at: '2024-05-16T13:06:31.409336+01:00'
                      fields:
                        - value: Access Bank Nigeria
                          display_name: Bank Name
                          name: bank_name
                          is_copyable: false
                          is_visible: true
                          required: true
                        - value: '0013246052'
                          display_name: Account Number
                          name: account_number
                          is_copyable: false
                          is_visible: true
                          required: true
                ngn:
                  summary: Recipient response NGN (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 687560e1255ff9424db5e4c5
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: INU JOHN
                      account_number: '2134211381'
                      active: true
                      bank_code: '000004'
                      bank_name: 9 PAYMENT SOLUTIONS BANK
                      category: bank
                      country_code: NG
                      currency: NGN
                      object: recipients
                      owned_by_customer: true
                      type: ngn_bank
                usd_ach:
                  summary: Recipient response USD - ACH (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 687564c9255ff9424db5e4c6
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Jane Smith
                      account_number: '9876543210'
                      active: true
                      bank_name: Chase Bank
                      category: bank
                      entity_type: personal
                      object: recipients
                      owned_by_customer: true
                      routing_number: '021000021'
                      transfer_type: ach
                      type: usd_bank
                usd_wire:
                  summary: Recipient response USD - WIRE (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 687564c9255ff9424db5e4c7
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Tech Corp LLC
                      account_number: '1122334455'
                      active: true
                      bank_name: Bank of America
                      category: bank
                      entity_type: business
                      object: recipients
                      owned_by_customer: true
                      routing_number: '026009593'
                      transfer_type: wire
                      type: usd_bank
                usd_swift:
                  summary: Recipient response USD - SWIFT (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756991255ff9424db5e4e0
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Global Corp Ltd
                      active: true
                      bank_name: Bank of International Transfers
                      category: bank
                      entity_type: business
                      iban: GB29NWBK60161331926819
                      intermediary_bank_address: 456 Avenue of Banks, Zurich
                      intermediary_bank_name: Intermediary Global Bank
                      intermediary_swift_code: CHASUS33XXX
                      object: recipients
                      owned_by_customer: true
                      recipient_address: 123 Hauptstrasse, Berlin, 10115, Germany
                      swift_code: CHASUS33XXX
                      transfer_type: swift
                      type: usd_bank
                kes:
                  summary: Recipient response MPESA MOBILE MONEY (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756bbc255ff9424db5e4e2
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Samuel Kiprotich
                      active: true
                      category: mpesa_mobile_money
                      country_code: KE
                      currency: KES
                      object: recipients
                      owned_by_customer: true
                      phone_number: +254 712345678
                      type: mpesa_mobile_money
                kes_business_mobile_money_till:
                  summary: Recipient response BUSINESS MOBILE MONEY - Till (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 6984a536631abd8caf69cf45
                      profile_id: 01b044c7-dff6-464c-9792-f49b3c3c02c3
                      account_name: Account Name
                      active: true
                      category: mobile_money
                      country_code: KE
                      currency: KES
                      object: recipients
                      owned_by_customer: true
                      paybill: '20029'
                      type: paybill
                kes_business_mobile_money_paybill:
                  summary: Recipient response BUSINESS MOBILE MONEY - Paybill (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 6984a536631abd8caf69cf45
                      profile_id: 01b044c7-dff6-464c-9792-f49b3c3c02c3
                      account_name: Samuel Kiprotich
                      account_number: '63902'
                      active: true
                      category: mobile_money
                      country_code: KE
                      currency: KES
                      object: recipients
                      owned_by_customer: true
                      paybill: '254701548525'
                      type: paybill
                crypto_btc:
                  summary: Recipient response BTC (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756cd6255ff9424db5e4e3
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      active: true
                      address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
                      address_label: My Bitcoin Wallet
                      category: crypto
                      network: BTC
                      object: recipients
                      owned_by_customer: true
                      type: crypto
                crypto_usdt_on_eth:
                  summary: Recipient response USDT ON ETH NETWORK (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756df6255ff9424db5e4e5
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      active: true
                      address: '0x742d35Cc6543C4532f5D2b8d9a2b2A1234567890'
                      address_label: My Ethereum Wallet
                      category: crypto
                      network: ETH
                      object: recipients
                      owned_by_customer: true
                      type: crypto
                crypto_stellar_lumens_with_memo:
                  summary: Recipient response STELLAR LUMENS (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756eb4255ff9424db5e4e7
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      active: true
                      address: GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A
                      address_label: My Stellar Wallet
                      category: crypto
                      memo: '123456789'
                      network: XLM
                      object: recipients
                      owned_by_customer: true
                      type: crypto
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
    get:
      tags:
        - Recipients
      operationId: listRecipients
      summary: List recipients
      description: Retrieve a list of all recipients
      parameters:
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CountryQueryParam'
        - $ref: '#/components/parameters/X-BU-Version'
        - $ref: '#/components/parameters/ProfileHeader'
        - name: network
          in: query
          description: Filter by recipient network
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: category
          in: query
          description: Filter by recipient category
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: Filter recipient by the type
          required: false
          schema:
            type: array
            items:
              type: string
              x-oapi-codegen-extra-tags:
                validate: nanoid
          style: form
          explode: false
        - name: phone_number
          in: query
          description: Filter recipients by phone number
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: account_number
          in: query
          description: Filter recipients by account number
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: username
          in: query
          description: Filter recipients by username
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Recipients retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientListResponse'
              examples:
                legacy_response:
                  summary: Recipient list response - Legacy
                  value:
                    status: success
                    message: Recipients retrieved successfully
                    data:
                      - object: recipient
                        id: 8014c2ee-c70f-4c72-8d9f-c8b9d708a688
                        user_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                        profile_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                        currency_id: NGN
                        country_id: NG
                        type: ngn_bank_transfer
                        legal_entity_type: business
                        owned_by_customer: true
                        active: true
                        created_at: '2024-05-16T13:06:31.409336+01:00'
                        updated_at: '2024-05-16T13:06:31.409336+01:00'
                        fields:
                          - value: Access Bank Nigeria
                            display_name: Bank Name
                            name: bank_name
                            is_copyable: false
                            is_visible: true
                            required: true
                          - value: '0013246052'
                            display_name: Account Number
                            name: account_number
                            is_copyable: false
                            is_visible: true
                            required: true
                response_2025_07_11:
                  summary: Recipient list response (2025-07-11)
                  value:
                    status: success
                    message: Recipients retrieved successfully
                    pagination:
                      next_cursor: MjAyNC0xMC0xNVQxMTowNTo1My45NTkxNDErMDE6MDA=
                      current_entries_size: 20
                      previous_cursor: MjAyNC0xMC0xNVQxMTowNTo1My45NTkxNDErMDE6MDA=
                    data:
                      - id: 68756eb4255ff9424db5e4e7
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        active: true
                        address: GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A
                        category: crypto
                        memo: '123456789'
                        network: XLM
                        object: recipients
                        owned_by_customer: true
                        type: crypto
                      - id: 68756bbc255ff9424db5e4e2
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: Samuel Kiprotich
                        active: true
                        category: mpesa_mobile_money
                        country_code: KE
                        currency: KES
                        object: recipients
                        owned_by_customer: true
                        phone_number: +254 712345678
                        type: mpesa_mobile_money
                      - id: 68756991255ff9424db5e4e0
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: Global Corp Ltd
                        active: true
                        bank_name: Bank of International Transfers
                        category: bank
                        entity_type: business
                        iban: GB29NWBK60161331926819
                        intermediary_bank_address: 456 Avenue of Banks, Zurich
                        intermediary_bank_name: Intermediary Global Bank
                        intermediary_swift_code: CHASUS33XXX
                        object: recipients
                        owned_by_customer: true
                        recipient_address: 123 Hauptstrasse, Berlin, 10115, Germany
                        swift_code: CHASUS33XXX
                        transfer_type: swift
                        type: usd_bank
                      - id: 687564c9255ff9424db5e4c6
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: Jane Smith
                        account_number: '9876543210'
                        active: true
                        bank_name: Chase Bank
                        category: bank
                        entity_type: personal
                        object: recipients
                        owned_by_customer: true
                        routing_number: '021000021'
                        transfer_type: ach
                        type: usd_bank
                      - id: 687560e1255ff9424db5e4c5
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: INU JOHN OSHIOGIEMHE
                        account_number: '2134211381'
                        active: true
                        bank_code: '000004'
                        bank_name: 9 PAYMENT SOLUTIONS BANK
                        category: bank
                        country_code: NG
                        currency: NGN
                        object: recipients
                        owned_by_customer: true
                        type: ngn_bank
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
      security:
        - Auth:
            - recipients:read
            - api:read
  /v1/recipients/{id}:
    get:
      tags:
        - Recipients
      summary: Retrieve a recipient
      description: Get details of a specific recipient
      operationId: getRecipient
      parameters:
        - $ref: '#/components/parameters/PathParamUUID'
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/X-BU-Version'
      responses:
        '200':
          description: Recipient retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
              examples:
                legacy_response:
                  summary: Recipient response - Legacy
                  value:
                    status: success
                    message: Recipient retrieved successfully
                    data:
                      object: recipient
                      id: 8014c2ee-c70f-4c72-8d9f-c8b9d708a688
                      user_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      profile_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      currency_id: NGN
                      country_id: NG
                      type: ngn_bank
                      legal_entity_type: personal
                      owned_by_customer: true
                      active: true
                      created_at: '2024-05-16T13:06:31.409336+01:00'
                      updated_at: '2024-05-16T13:06:31.409336+01:00'
                      fields:
                        - value: Access Bank Nigeria
                          display_name: Bank Name
                          name: bank_name
                          is_copyable: false
                          is_visible: true
                          required: true
                        - value: '0013246052'
                          display_name: Account Number
                          name: account_number
                          is_copyable: false
                          is_visible: true
                          required: true
                response_2025_07_11:
                  summary: Recipient response (2025-07-11)
                  value:
                    status: success
                    message: Recipient retrieved successfully
                    data:
                      id: 687560e1255ff9424db5e4c5
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: INU JOHN OSHIOGIEMHE
                      account_number: '2134211381'
                      active: true
                      bank_code: '000004'
                      bank_name: 9 PAYMENT SOLUTIONS BANK
                      category: bank
                      country_code: NG
                      currency: NGN
                      object: recipients
                      owned_by_customer: true
                      type: ngn_bank
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
      security:
        - Auth:
            - recipients:read
            - api:read
    delete:
      tags:
        - Recipients
      summary: Delete a recipient
      description: Delete a specific recipient
      operationId: deleteRecipient
      parameters:
        - $ref: '#/components/parameters/PathParamUUID'
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/X-BU-Version'
      responses:
        '204':
          description: Recipient deleted successfully
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
      security:
        - Auth:
            - recipients:read
            - api:read
  /v1/recipients/resolve-bank-account:
    post:
      security:
        - Auth:
            - recipients:write
            - api:write
      tags:
        - Recipients
      operationId: resolveBankAccount
      x-rate-limit: 5
      summary: Resolves a bank account
      description: Resolves a bank account for bank transfers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveBankAccountRequest'
      responses:
        '201':
          description: Recipient created successfully
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ResolveBankAccountResp'
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
  /v1/transactions:
    get:
      tags:
        - Transactions
      description: Returns a list of transactions
      operationId: listTransactions
      summary: List transactions
      parameters:
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - name: is_fiat
          in: query
          description: Filter by fiat currencies
          required: false
          schema:
            type: boolean
        - name: is_credit
          in: query
          description: Filter by transactions that are credit
          required: false
          schema:
            type: boolean
        - name: type
          in: query
          description: Filter transactions by type
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TransactionTypes'
          style: form
          explode: false
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsListResponse'
        4XX:
          $ref: '#/components/responses/TransactionsError4XX'
        5XX:
          $ref: '#/components/responses/TransactionsError5XX'
      security:
        - Auth:
            - transactions:read
            - api:read
  /v1/transactions/{id}:
    get:
      tags:
        - Transactions
      description: Retrieves a transactions
      operationId: getTransaction
      summary: Get transaction
      parameters:
        - $ref: '#/components/parameters/PathParamUUID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Transaction'
        4XX:
          $ref: '#/components/responses/TransactionsError4XX'
        5XX:
          $ref: '#/components/responses/TransactionsError5XX'
      security:
        - Auth:
            - transactions:read
            - api:read
  /v1/transfers:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - transfers:write
            - api:write
      summary: Create transfer
      description: Create a transfer object
      operationId: createTransfer
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Transfer Request Body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransferRequest'
      responses:
        '201':
          $ref: '#/components/responses/TransferResponse'
        4XX:
          $ref: '#/components/responses/TransferError4XX'
        5XX:
          $ref: '#/components/responses/TransferError5XX'
    get:
      summary: List transfers
      description: Gets all transfers
      operationId: listTransfer
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: id
          in: query
          description: Filter by ID
          required: false
          schema:
            type: string
        - name: quote_id
          in: query
          description: Filter by quote ID
          required: false
          schema:
            $ref: '#/components/schemas/NanoID'
        - name: start_date
          in: query
          description: Filter by start date
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-01'
        - name: end_date
          in: query
          description: Filter by end date
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-01'
        - name: source_currency
          in: query
          description: Filter by source_currency code
          required: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: trim|upper
          schema:
            type: string
        - name: target_currency
          in: query
          description: Filter by target_currency code
          required: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: trim|upper
          schema:
            type: string
        - $ref: '#/components/parameters/StatusQueryParam'
        - name: referred
          in: query
          description: Specify whether to get referred transfers or not
          required: false
          schema:
            type: boolean
        - name: includes_step
          in: query
          description: Filter transfers that include a specific step in their flow.
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - deposit
                - withdrawal
                - conversion
                - no_deposit
                - no_withdrawal
                - no_conversion
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/TransferListResponse'
        4XX:
          $ref: '#/components/responses/TransferError4XX'
        5XX:
          $ref: '#/components/responses/TransferError5XX'
      security:
        - Auth:
            - transfers:read
            - api:read
  /v1/transfers/{id}:
    get:
      summary: Get transfer
      description: Retrieves a transfer
      operationId: getTransfer
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/TransferResponse'
        4XX:
          $ref: '#/components/responses/TransferError4XX'
        5XX:
          $ref: '#/components/responses/TransferError5XX'
      security:
        - Auth:
            - transfers:read
            - api:read
components:
  parameters:
    ProfileHeader:
      in: header
      name: X-BU-PROFILE-ID
      required: false
      description: User profile header
      schema:
        type: string
        example: BUS_YOK8tp5Zga01qOKEsqp07
    CursorQueryParams:
      name: cursor
      in: query
      description: The cursor
      schema:
        type: string
        format: string
    LimitQueryParam:
      name: limit
      in: query
      description: The number of items to return
      schema:
        type: integer
        example: 10
        x-go-type: uint64
    PathParamNanoID:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: nanoid
        example: bus_123456789
      x-oapi-codegen-extra-tags:
        validate: required|nanoid
    SortQueryParam:
      name: sort
      in: query
      description: The order to sort the results
      schema:
        type: string
        enum:
          - asc
          - desc
        example: asc
    CountryQueryParam:
      name: country
      in: query
      x-oapi-codegen-extra-tags:
        validate: alpha2
        filter: trim|upper
      schema:
        type: string
    CurrencyCodePathParam:
      name: code
      in: path
      required: true
      description: The currency path parameter
      schema:
        type: string
        example: BTC
        x-go-type: string
    CurrencyQueryParam:
      name: currency
      in: query
      required: false
      description: Filter by currency
      schema:
        type: array
        items:
          type: string
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: trim|upper
      style: form
      explode: false
    XBuPublicKey:
      in: header
      name: X-BU-PUBLIC-KEY
      required: false
      schema:
        type: string
        example: pub_uibaidu930ani
    CurrencyType:
      name: type
      in: query
      schema:
        type: array
        items:
          type: string
          enum:
            - fiat
            - crypto
            - stablecoin
      style: form
      example: fiat
      explode: false
    PlatformIDInQueryParam:
      in: query
      name: id
      description: uuid and nano_id
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
      example: platform_123456
    PathParamUUID:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
        x-go-type: string
      x-oapi-codegen-extra-tags:
        validate: required|uuid
    PaymentLinkTypeQueryParam:
      name: type
      in: query
      required: false
      style: form
      explode: false
      description: Filter by type (payment_link or invoice)
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PaymentLinkType'
    X-BU-Version:
      in: header
      name: X-BU-Version
      description: The API version to use for this request.
      required: false
      schema:
        type: string
        default: '2025-07-11'
        example: '2025-07-11'
        enum:
          - '2025-06-01'
          - '2025-07-11'
    StatusQueryParam:
      name: status
      in: query
      description: Filter by status (comma-separated)
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/TransferStatus'
      example: funds_refunded,funds_converted
  schemas:
    Balance:
      type: object
      required:
        - id
        - currency
        - name
        - type
        - pending
        - available
        - savings
        - investments
        - total
        - user_id
        - profile_id
      properties:
        id:
          $ref: '#/components/schemas/ResourceUUID'
        user_id:
          $ref: '#/components/schemas/ID'
        profile_id:
          $ref: '#/components/schemas/ID'
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 6
        name:
          type: string
          x-order: 7
          example: Bitcoin
        type:
          type: string
          x-order: 8
          enum:
            - fiat
            - crypto
          example: crypto
        pending:
          $ref: '#/components/schemas/AmountWithCurrencyAndFiat'
        available:
          $ref: '#/components/schemas/AmountWithCurrencyAndFiat'
        savings:
          $ref: '#/components/schemas/AmountWithCurrencyAndFiat'
        investments:
          $ref: '#/components/schemas/AmountWithCurrencyAndFiat'
        total:
          $ref: '#/components/schemas/AmountWithCurrencyAndFiat'
    Amount:
      $ref: '#/components/schemas/AmountWithCurrencyAndFiat'
    BalanceListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Balance'
    CreateBalanceRequest:
      type: object
      required:
        - currency
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
    Currency:
      type: string
      x-order: 20
      example: BTC
      format: string
      maxLength: 10
      minLength: 1
      description: A valid currency
      x-oapi-codegen-extra-tags:
        validate: required|min_len:1|max_len:10
        filter: trim|upper
    BaseSchema:
      description: General response Values
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          x-order: 1
          x-go-type: string
          enum:
            - success
            - error
          example: success
        message:
          type: string
          x-order: 2
          example: message for success
    CursorPagination:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - pagination
          properties:
            pagination:
              type: object
              required:
                - current_entries_size
              properties:
                next_cursor:
                  type: string
                  example: MjAyNC0xMC0xNVQxMTowNTo1My45NTkxNDErMDE6MDA=
                current_entries_size:
                  type: integer
                  example: 20
                previous_cursor:
                  type: string
                  example: MjAyNC0xMC0xNVQxMDowNTo1My45NTIxQjE3MDE6MDA=
    ResourceUUID:
      type: string
      x-order: 1
      example: 550e8400-e29b-41d4-a716-446655440000
      format: uuid
      description: A valid UUID
      x-oapi-codegen-extra-tags:
        validate: required|uuid
      x-go-type: uuid.UUID
      x-go-type-import:
        path: github.com/gofrs/uuid
        name: uuid
    ID:
      type: string
      x-order: 4
      example: platform_123456
      format: nanoid
      description: A valid id that supports uuid and nanoid
      x-oapi-codegen-extra-tags:
        validate: required|nanoid|string
    Decimal:
      type: string
      description: decimal value
      example: '100'
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
        name: decimal
    AmountWithCurrency:
      type: object
      description: Amount with currency
      required:
        - amount
        - currency
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          $ref: '#/components/schemas/Currency'
    AmountWithCurrencyAndFiat:
      allOf:
        - $ref: '#/components/schemas/AmountWithCurrency'
        - type: object
          properties:
            fiat:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
              description: amount in fiat
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - name
            - message
          properties:
            name:
              type: string
              x-order: 40
              example: bad_request
            message:
              type: string
              example: Invalid Request
        fields:
          type: object
        schema:
          type: array
          items:
            type: object
      example:
        error:
          name: bad_request
          message: Invalid Request
    BillOrder:
      type: object
      required:
        - id
        - reference
        - category
        - recipient
        - amount
        - currency
        - status
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/ResourceID'
        reference:
          type: string
          description: Unique order reference
          example: BILL-abc123def456
        recipient:
          type: string
          description: Meter number, smartcard, customer ID, etc.
        amount:
          type: string
          description: Bill amount in bill currency
          example: '1000.00'
        currency:
          type: string
          description: Bill currency
          example: NGN
        source_amount:
          type: string
          description: Amount charged to customer (may differ if cross-currency)
          example: '1000.00'
        source_currency:
          type: string
          description: Currency charged to customer
          example: NGN
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - cancelled
          description: Current order status
        fee:
          type: string
          description: Platform fee charged (0 if no fee)
          example: '50.00'
        provider_amount:
          type: string
          nullable: true
          description: Amount delivered to the recipient by the provider
          example: '200.00'
        failure_reason:
          type: string
          nullable: true
          description: Human-readable reason if the order failed
        product_name:
          type: string
          description: Product display name
          example: Adam n Eve
        product_code:
          type: string
          description: Product code used for purchase
          example: SGF_1
        logo_url:
          type: string
          description: Product logo URL (when available)
          example: https://example.com/logo.jpg
        voucher:
          $ref: '#/components/schemas/VoucherDetails'
        electricity:
          $ref: '#/components/schemas/ElectricityDetails'
        meta:
          $ref: '#/components/schemas/BillOrderMeta'
        created_at:
          $ref: '#/components/schemas/TimeStamp'
        updated_at:
          $ref: '#/components/schemas/TimeStamp'
    VoucherStatus:
      type: string
      enum:
        - active
        - fully_used
        - expired
        - inactive
        - unknown
      description: Voucher lifecycle status derived from Suregifts state and local expiry.
    VoucherTransaction:
      type: object
      required:
        - amount
        - occurred_at
      description: A single redemption (or adjustment) reported by the provider.
      properties:
        amount:
          type: string
          description: Transaction amount in the voucher's currency
          example: '200.00'
        type:
          type: string
          description: Provider transaction type (e.g. Redemption)
          example: Redemption
        narration:
          type: string
          description: Provider-supplied description
          example: POS redemption at Partner Store
        occurred_at:
          type: string
          format: date-time
          description: When the transaction occurred
    VoucherDetails:
      type: object
      nullable: true
      description: Voucher delivery artifacts and lifecycle state. Present for completed voucher orders; lifecycle fields populate after first sync with the provider.
      properties:
        pin:
          type: string
          description: Voucher PIN
          example: '1234'
        code:
          type: string
          description: Voucher redemption code
          example: '421925411392'
        expires_at:
          type: string
          description: Voucher expiry date (ISO 8601)
          example: '2027-04-13T20:50:52Z'
        value:
          type: string
          description: Voucher face value
          example: '1000.00'
        balance:
          type: string
          description: Remaining redeemable balance
          example: '300.00'
        amount_used:
          type: string
          description: Amount redeemed so far (value - balance)
          example: '700.00'
        status:
          $ref: '#/components/schemas/VoucherStatus'
        last_synced_at:
          type: string
          format: date-time
          description: When this voucher state was last refreshed from the provider
        transactions:
          type: array
          description: Redemption history from the provider
          items:
            $ref: '#/components/schemas/VoucherTransaction'
    ElectricityDetails:
      type: object
      nullable: true
      description: Electricity delivery artifacts. Present for completed electricity orders.
      properties:
        token:
          type: string
          description: Prepaid token delivered to the meter
          example: 0123-4567-8901-2345-6789
        units:
          type: string
          description: Units purchased
          example: '25.3'
    BillOrderMeta:
      type: object
      nullable: true
      description: Cross-cutting order metadata (rate for cross-currency purchases, quote ID, category-specific display fields). Category-specific delivery artifacts live on `voucher` / `electricity`.
      properties:
        rate:
          type: object
          nullable: true
          description: Exchange rate details (present for cross-currency purchases)
          properties:
            rate:
              type: string
              description: Exchange rate value
            from:
              type: string
              description: Source currency
            to:
              type: string
              description: Destination currency
        quote_id:
          type: string
          description: Quote ID used for cross-currency conversion
        bill:
          type: object
          nullable: true
          description: Category-specific display fields populated at purchase time. Mirrors what ships to the ledger transaction's `service` object so mobile can render the same labels from either source.
          properties:
            merchant:
              type: string
              description: Biller-of-record display name (disco, cable provider, betting platform, voucher brand, airtime/data network)
            meter_no:
              type: string
              description: Electricity meter number
            account_type:
              type: string
              description: Electricity account type (prepaid or postpaid)
            smartcard_no:
              type: string
              description: Cable smartcard number
            plan_name:
              type: string
              description: Cable bouquet / plan name
            bundle:
              type: string
              description: Data bundle name
            customer_no:
              type: string
              description: Betting customer / account number
            recipient_email:
              type: string
              description: Voucher recipient email (if captured)
    PurchaseRequest:
      type: object
      required:
        - category
        - product_code
        - amount
        - recipient
      properties:
        product_code:
          type: string
          description: Product code to purchase
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:100
            filter: trim
        amount:
          type: string
          description: Amount in bill currency
          x-oapi-codegen-extra-tags:
            validate: required
        recipient:
          type: string
          description: Meter number, smartcard, customer ID, etc.
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:50
            filter: trim
        phone_number:
          type: string
          description: Phone number (required for airtime, data, electricity, cable, betting)
          x-oapi-codegen-extra-tags:
            validate: min_len:10|max_len:15
            filter: trim
        account_type:
          type: string
          enum:
            - prepaid
            - postpaid
          description: Meter type (required for electricity, ignored otherwise)
        source_currency:
          type: string
          description: Currency to charge from (defaults to bill currency if omitted)
          x-oapi-codegen-extra-tags:
            filter: trim|upper
    PurchaseQuoteRequest:
      type: object
      required:
        - category
        - product_code
        - amount
        - recipient
      properties:
        product_code:
          type: string
          description: Product code to purchase
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:100
            filter: trim
        amount:
          type: string
          description: Amount in bill currency
          x-oapi-codegen-extra-tags:
            validate: required
        recipient:
          type: string
          description: Meter number, smartcard, customer ID, etc.
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:50
            filter: trim
        source_currency:
          type: string
          description: Currency to charge from (defaults to bill currency if omitted)
          x-oapi-codegen-extra-tags:
            filter: trim|upper
    PurchaseQuoteResponse:
      type: object
      required:
        - product_name
        - product_code
        - category
        - recipient
        - amount
        - currency
        - source_amount
        - source_currency
        - fee
        - fee_currency
        - total
        - total_currency
      properties:
        product_name:
          type: string
          description: Product display name
        product_code:
          type: string
          description: Product code
        recipient:
          type: string
          description: Recipient identifier
        amount:
          type: string
          description: Amount in bill currency (sent to provider)
          example: '1000.00'
        currency:
          type: string
          description: Bill currency
          example: NGN
        source_amount:
          type: string
          description: Grand total (amount + fee) converted to source currency; amount to charge customer
          example: '0.68'
        source_currency:
          type: string
          description: Customer's payment currency
          example: USD
        rate:
          type: string
          description: Human-readable rate (present only for cross-currency)
          example: 1 USD = 1,478.24 NGN
        fee:
          type: string
          description: Platform fee in bill currency
          example: '10.00'
        fee_currency:
          type: string
          description: Fee currency (same as bill currency)
          example: NGN
        total:
          type: string
          description: Grand total charged to the customer in source currency (equal to source_amount)
          example: '0.68'
        total_currency:
          type: string
          description: Total currency (same as source)
          example: USD
    ResourceID:
      type: string
      x-order: 1
      example: bus_123456789
      format: string
      description: A valid id
      x-oapi-codegen-extra-tags:
        validate: required|nanoid
    TimeStamp:
      type: string
      format: date-time
      example: '2023-10-15T12:15:30Z'
      x-go-type: time.Time
    CountryID:
      type: string
      example: NG
      format: alpha2
      description: A valid country id
      minLength: 2
      maxLength: 2
      x-oapi-codegen-extra-tags:
        validate: alpha2
    NanoID:
      type: string
      x-order: 2
      example: bus_123456789
      format: nanoid
      description: A valid id
      x-oapi-codegen-extra-tags:
        validate: required|nanoid
    QuoteRate:
      type: object
      properties:
        product:
          type: string
          example: BTCUSDT
        rate_explained:
          type: string
          example: 1 BTC = 1000 USDT
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_currency:
          $ref: '#/components/schemas/Currency'
        rate:
          $ref: '#/components/schemas/Decimal'
        side:
          type: string
          enum:
            - buy
            - sell
          example: sell
        type:
          type: string
          enum:
            - FIXED
          example: FIXED
    PhoneField:
      type: string
      example: '+2348012345678'
      format: phone
      description: A valid phone number. format `{{calling_code}}{{number}}`
      x-oapi-codegen-extra-tags:
        validate: phone
        filter: phone
        mapstructure: phone_number,omitempty
    FeeType:
      type: string
      enum:
        - FIXED
        - PERCENTAGE
        - TIERED
      example: FIXED
    Fee:
      type: object
      x-order: 40
      required:
        - name
        - amount
        - type
      properties:
        name:
          type: string
          example: processing_fee
        amount:
          $ref: '#/components/schemas/AmountWithCurrency'
        converted_amount:
          $ref: '#/components/schemas/AmountWithCurrency'
        type:
          $ref: '#/components/schemas/FeeType'
    Address:
      type: object
      description: Address of the business.
      required:
        - address_line_1
        - country_id
      properties:
        city:
          type: string
          example: Lekki
          x-oapi-codegen-extra-tags:
            mapstructure: city
        state:
          type: string
          example: Lagos
          x-oapi-codegen-extra-tags:
            mapstructure: state
        county:
          type: string
          example: Mombasa
          x-oapi-codegen-extra-tags:
            mapstructure: county
        country_id:
          type: string
          example: NG
          format: alpha2
          description: A valid country id
          x-oapi-codegen-extra-tags:
            validate: alpha2
            mapstructure: country_id
        address_line_1:
          type: string
          example: RT Lawal
          x-oapi-codegen-extra-tags:
            mapstructure: address_line_1
        address_line_2:
          type: string
          example: ''
          x-oapi-codegen-extra-tags:
            mapstructure: address_line_2
        province:
          type: string
          example: province
          x-oapi-codegen-extra-tags:
            mapstructure: province
        postal_code:
          type: string
          example: '12345'
          x-oapi-codegen-extra-tags:
            mapstructure: postal_code
    Currencies:
      type: object
      required:
        - name
        - code
        - decimals
        - display_name
        - type
        - is_ramp_buy_supported
        - is_ramp_sell_supported
        - precision
        - default_network
        - supported_networks
        - withdrawal
        - deposit
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 1
        description:
          type: string
          description: Extra information about the currency
        name:
          type: string
          x-order: 5
          example: Bitcoin
          description: The official name of the cryptocurrency.
        display_name:
          type: string
          x-order: 6
          example: Bitcoin (BTC)
          description: The formatted display name of the cryptocurrency.
        type:
          type: string
          x-order: 7
          enum:
            - fiat
            - crypto
            - stablecoin
          description: Indicates whether the cryptocurrency is a stablecoin.
        decimals:
          type: string
          x-order: 8
          example: '8'
          description: |
            The number of decimal places supported by the blockchain. Defines how the currency value is divided.
        default_network:
          type: string
          x-order: 9
          description: The identifier of the default network for this currency.
          example: ethereum
        deposit:
          type: boolean
          x-order: 10
          description: Indicates if deposits are supported for this currency.
        icon:
          allOf:
            - $ref: '#/components/schemas/UrlField'
          x-order: 11
        withdrawal:
          type: boolean
          x-order: 12
          description: Indicates if withdrawals are supported for this currency.
        precision:
          type: string
          x-order: 13
          example: '8'
          description: |
            The level of precision supported by this service. This may differ from blockchain-level precision in some cases.
        supported_networks:
          type: array
          x-order: 14
          description: A list of networks supported by the currency, including details for each.
          items:
            $ref: '#/components/schemas/Network'
        is_ramp_sell_supported:
          type: boolean
          x-order: 15
          description: Indicates if ramp sell is supported for this currency.
          example: true
        is_ramp_buy_supported:
          type: boolean
          x-order: 16
          description: Indicates if ramp buy is supported for this currency.
          example: true
        maximum_ramp_buy:
          type: string
          x-order: 17
          description: The maximum amount that can be purchased through the ramp process for this currency.
          example: '1000'
        maximum_ramp_sell:
          type: string
          x-order: 18
          description: The maximum amount that can be sold through the ramp process for this currency.
          example: '1000'
    Network:
      type: object
      required:
        - id
        - name
        - status
        - deposit
        - withdrawal
      properties:
        id:
          type: string
          x-order: 1
          example: ethereum
          description: The unique identifier for the blockchain network.
        name:
          type: string
          example: Ethereum
          description: The descriptive name of the network.
        status:
          type: string
          example: active
          description: The current operational status of the network.
        withdrawal:
          type: boolean
          description: Indicates if withdrawals are supported for this network.
        deposit:
          type: boolean
          description: Indicates if deposits are supported for this network.
        transaction_link:
          $ref: '#/components/schemas/UrlField'
        address_link:
          $ref: '#/components/schemas/UrlField'
        max_withdrawal_amount:
          type: string
          example: '100.00'
          description: Maximum withdrawal amount for this network in the currency.
        min_withdrawal_amount:
          type: string
          example: '0.01'
          description: Minimum withdrawal amount for this network in the currency.
        min_deposit_amount:
          type: string
          example: '0.001'
          description: Minimum deposit amount for this network in the currency.
        confirmations_required:
          type: string
          example: '12'
          description: Number of confirmations required for deposits to be recognized.
        network:
          type: string
          example: ETH
          description: The blockchain network for the currency.
        withdrawal_fee:
          type: string
          example: '0.0001'
          description: The withdrawal fee for the network in the currency.
        address_regex:
          $ref: '#/components/schemas/AddressRegexField'
        testnet_address_regex:
          $ref: '#/components/schemas/AddressRegexField'
        contract_address:
          type: string
          example: '0xdac17f958d2ee523a2206206994597c13d831ec7'
          description: The contract address for tokens on this network.
        is_ramp_sell_supported:
          type: boolean
          description: Indicates if ramp sell is supported for this currency.
          example: true
        is_ramp_buy_supported:
          type: boolean
          description: Indicates if ramp buy is supported for this currency.
          example: true
    CurrenciesListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Currencies'
    UrlField:
      type: string
      example: https://example.com
      format: url
      description: A valid url
      x-oapi-codegen-extra-tags:
        validate: required|url
    AddressRegexField:
      type: string
      example: ^0x[a-fA-F0-9]{40}$
      format: address
      x-oapi-codegen-extra-tags:
        validate: required|regex
    BaseCustomerRequest:
      allOf:
        - type: object
          properties:
            phone:
              $ref: '#/components/schemas/PhoneField'
            birth_date:
              type: string
              example: 24-12-2000
              description: date of birth of the user
            address:
              $ref: '#/components/schemas/Address'
            identifying_information:
              type: array
              description: List of identification documents provided by the customer
              minItems: 0
              maxItems: 5
              items:
                $ref: '#/components/schemas/CustomerIdentifyingInformation'
            documents:
              type: array
              description: Additional supporting documents provided by the customer
              minItems: 0
              maxItems: 10
              uniqueItems: true
              items:
                $ref: '#/components/schemas/CustomerDocument'
    UpdateCustomerRequest:
      allOf:
        - $ref: '#/components/schemas/BaseCustomerRequest'
        - oneOf:
            - $ref: '#/components/schemas/CustomerCreateIndividual'
            - $ref: '#/components/schemas/CustomerCreateBusiness'
    CreateCustomerRequest:
      allOf:
        - type: object
          required:
            - email
            - has_accepted_terms
            - country_id
            - phone
            - address
            - birth_date
            - type
          properties:
            email:
              $ref: '#/components/schemas/EmailField'
            has_accepted_terms:
              type: boolean
              description: Indicates whether the customer has explicitly accepted the terms and conditions
            type:
              $ref: '#/components/schemas/BusinessCustomerType'
            country_id:
              $ref: '#/components/schemas/CountryID'
        - $ref: '#/components/schemas/BaseCustomerRequest'
        - oneOf:
            - $ref: '#/components/schemas/CustomerCreateIndividual'
            - $ref: '#/components/schemas/CustomerCreateBusiness'
    CustomerIdentifyingInformation:
      type: object
      required:
        - type
        - number
        - country
      description: Contains identification document details and related images for customer verification
      properties:
        type:
          type: string
          enum:
            - passport
            - national-id
            - drivers-license
            - selfie_video
            - selfie
            - bvn
          description: The category of identification document provided by the customer
        number:
          type: string
          maxLength: 50
          description: The unique identifier or serial number on the identification document
        country:
          $ref: '#/components/schemas/CountryID'
        expiry_date:
          type: string
          format: date
          description: The date when the identification document becomes invalid or expires
        image_front:
          type: string
          format: base64
          description: URL or Base64 encoded image of the front side of the identification document. The maximum file size is 4MB.
        image_back:
          type: string
          format: base64
          description: URL or Base64 encoded image of the reverse side of the identification document. The maximum file size is 4MB.
    CustomerDocument:
      type: object
      required:
        - purposes
        - file
      properties:
        purposes:
          type: array
          items:
            type: string
            enum:
              - certificate_of_incorporation
              - corporate_registry_extract
              - memart
              - corporate_structure_chart
              - board_resolution
              - aml_policy
              - regulatory_licenses
              - proof_of_funds
              - proof_of_wealth
              - proof_of_address
              - selfie_video
              - selfie
              - others
          description: Purposes for which the document is being submitted
        file:
          type: string
          description: URL or Document file content in base64 format. The maximum file size is 4MB.
    CustomerBusinessOwner:
      type: object
      required:
        - first_name
        - last_name
        - role
        - nationality
        - percentage_ownership
        - is_pep
      properties:
        first_name:
          type: string
          maxLength: 100
        last_name:
          type: string
          maxLength: 100
        role:
          type: array
          items:
            type: string
            enum:
              - director
              - owner
              - shareholder
        percentage_ownership:
          type: number
          minimum: 0
          maximum: 100
        is_pep:
          type: boolean
          default: false
        pep_type:
          type: string
        nationality:
          $ref: '#/components/schemas/CountryID'
        address:
          $ref: '#/components/schemas/Address'
        proof_of_address:
          type: string
          x-oapi-codegen-extra-tag: null
        bvn:
          $ref: '#/components/schemas/BVNField'
        proof_of_id:
          type: string
          x-oapi-codegen-extra-tag: null
    CustomerBusinessTransaction:
      type: object
      required:
        - purpose
        - monthly_transaction_value
        - monthly_transaction_count
        - client_transaction_status
        - api_access_needed
      properties:
        purpose:
          type: string
          minLength: 3
          maxLength: 100
          description: The purpose of the customer's transactions
        monthly_transaction_value:
          type: string
          enum:
            - 100_usd_or_less
            - 100_usd_to_500_usd
            - 500_usd_to_1m_usd
            - above_1m_usd
          description: Expected monthly value of transactions in USD
        monthly_transaction_count:
          type: string
          enum:
            - 10_or_less
            - 10_to_50
            - 50_to_100
            - 100_to_200
            - above_200
          description: Expected number of transactions per month
        client_transaction_status:
          type: string
          enum:
            - self-owned
            - on-behalf
          description: Whether transactions are self-owned or on behalf of clients
        api_access_needed:
          type: boolean
          description: Whether API access is required for transactions
        api_integration_url:
          type: string
          format: uri
          description: Required when api_access_needed is true. URL for API integration
    CustomerBusinessRegistration:
      type: object
      required:
        - business_type
        - business_structure
        - business_regulation_status
        - registration_number
        - tax_identification_number
        - corporate_group_status
        - exchange_listing_status
        - license_number
      properties:
        business_type:
          type: string
          enum:
            - type_registered_company
            - type_sole_proprietorship
          description: Type of business organization
        business_structure:
          type: string
          enum:
            - public_limited_company
            - registered_business_name
            - other
            - limited_liability_company
            - limited_liability_partnership
          description: Legal structure of the business
        business_regulation_status:
          type: string
          enum:
            - regulated
            - unregulated
          description: Whether business is regulated or not
        registration_number:
          type: string
          maxLength: 20
          description: Business registration number
        tax_identification_number:
          type: string
          maxLength: 20
          description: Tax ID number of business
        corporate_group_status:
          type: string
          enum:
            - standalone_company
            - subsidiary
            - holding_company
          description: Status within corporate group structure
        exchange_listing_status:
          type: string
          enum:
            - listed_on_exchange
            - not_listed_on_exchange
            - owned_by_listed_company
          description: Whether business is listed on stock exchange
        license_number:
          type: string
          maxLength: 30
          description: Business license number if applicable
    CustomerCreateIndividual:
      type: object
      x-order: 2
      required:
        - first_name
        - last_name
      description: Individual name requirements
      properties:
        first_name:
          $ref: '#/components/schemas/NameField'
        middle_name:
          $ref: '#/components/schemas/NullableNameField'
        last_name:
          $ref: '#/components/schemas/NameField'
    CustomerCreateBusiness:
      allOf:
        - $ref: '#/components/schemas/CustomerBusinessBase'
        - type: object
          required:
            - business_name
            - business_industry
          description: Business name requirements
          x-order: 2
          properties:
            business_owners:
              type: array
              items:
                $ref: '#/components/schemas/CustomerBusinessOwner'
            business_transaction:
              $ref: '#/components/schemas/CustomerBusinessTransaction'
            business_registration:
              $ref: '#/components/schemas/CustomerBusinessRegistration'
    CustomerBusinessIndustry:
      type: object
      required:
        - id
        - name
        - description
        - category
        - sector
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/NanoID'
          x-order: 1
        name:
          type: string
          description: Name of the industry
          x-order: 2
        description:
          type: string
          description: Description of the industry
          x-order: 3
        category:
          type: string
          description: Category of the industry
          x-order: 4
        sector:
          type: string
          description: Sector of the industry
          x-order: 5
    CustomerBusinessBase:
      type: object
      required:
        - business_name
        - business_industry
        - business_incorporation_date
      description: Business name requirements
      x-order: 2
      properties:
        business_name:
          type: string
          description: Name of the business
          maxLength: 100
          x-oapi-codegen-extra-tags:
            validate: required|maxlen:100
            filter: trim|lower|ucFirst
        business_industry:
          type: string
          minLength: 16
          maxLength: 24
          description: ID Industry or sector the business operates in
        business_incorporation_date:
          type: string
          format: date
          description: Business incorporation date
    Customer:
      allOf:
        - oneOf:
            - $ref: '#/components/schemas/CustomerCreateIndividual'
            - $ref: '#/components/schemas/CustomerBusinessBase'
        - type: object
          x-order: 1
          required:
            - id
            - status
            - type
            - email
            - country_id
            - business_id
            - has_accepted_terms_of_service
            - display_currency
            - deposit
            - payout
            - phone
            - address
            - level
            - created_at
            - updated_at
          properties:
            id:
              allOf:
                - $ref: '#/components/schemas/NanoID'
              x-order: 1
            business_id:
              allOf:
                - $ref: '#/components/schemas/NanoID'
              x-order: 2
            email:
              allOf:
                - $ref: '#/components/schemas/EmailField'
              x-order: 3
            status:
              type: string
              enum:
                - active
                - inactive
                - submitted
                - in_review
                - rejected
              x-order: 9
            kyc_status:
              type: string
              enum:
                - pending
                - unverified
                - verified
                - expiry_soon
                - expired
              x-order: 9
            country_id:
              $ref: '#/components/schemas/CountryID'
            type:
              allOf:
                - $ref: '#/components/schemas/BusinessCustomerType'
              x-order: 8
            phone:
              allOf:
                - $ref: '#/components/schemas/PhoneField'
              x-order: 8
            address:
              allOf:
                - $ref: '#/components/schemas/Address'
              x-order: 7
            display_currency:
              allOf:
                - $ref: '#/components/schemas/Currency'
              x-order: 7
            deposit:
              type: boolean
              description: User can deposit
              x-order: 8
            payout:
              type: boolean
              description: User can payout
              x-order: 8
            has_accepted_terms_of_service:
              type: boolean
              x-order: 10
            rejection_reasons:
              type: array
              items:
                type: string
              x-order: 11
            requirements_due:
              type: array
              items:
                type: string
              x-order: 12
            future_requirements_due:
              type: array
              items:
                type: string
              x-order: 13
            beneficial_owners:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    $ref: '#/components/schemas/EmailField'
              x-order: 14
            level:
              type: string
              x-order: 15
            created_at:
              type: string
              format: date-time
              x-order: 16
            updated_at:
              type: string
              format: date-time
              x-order: 17
    BusinessCustomerType:
      type: string
      enum:
        - individual
        - business
    CustomerTokenShareRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: JWT token
    NameField:
      type: string
      example: John
      description: A valid name
    NullableNameField:
      type: string
      nullable: true
      description: A field representing a name that can be null or absent.
      example: Smith
    EmailField:
      type: string
      example: bCnW7@example.com
      format: email
      description: A valid email address
      x-oapi-codegen-extra-tags:
        validate: required|email|check_temp_email
        filter: trim|lower
      x-go-type: string
    BVNField:
      type: string
      description: Bank Verification Number (BVN)
      format: number
      example: '12345678901'
      minLength: 11
      maxLength: 11
      x-oapi-codegen-extra-tags:
        validate: num|len:11
    PresignedUrlRequest:
      type: object
      required:
        - category
      properties:
        category:
          type: string
          enum:
            - generic
            - avatar
            - document
            - usd_payment_proof
            - checkout-logo
            - business-logo
            - compliance-docs
            - index
          default: generic
        file_type:
          type: string
          example: application/pdf
        file_name:
          type: string
          example: document.pdf
        document_id:
          type: string
          example: '123'
        key_only:
          type: boolean
          default: false
    PresignedUrlResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/PresignedUrlResponseObject'
    PresignedUrlResponseObject:
      type: object
      required:
        - upload_url
        - public_link
        - expires_at
      properties:
        upload_url:
          type: string
          example: https://s3.amazonaws.com/bucket/key?signature=...
        public_link:
          type: string
          example: https://cdn.busha.co/generic/123/document.pdf
        expires_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
    VirtualBankAccount:
      type: object
      required:
        - id
        - profile_id
        - currency_code
        - account_name
        - account_number
        - bank_name
        - bank_code
        - status
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/NanoID'
        profile_id:
          $ref: '#/components/schemas/NanoID'
        currency_code:
          $ref: '#/components/schemas/Currency'
        account_name:
          type: string
          example: John Doe - Busha
        account_number:
          type: string
          example: '1234567890'
        bank_name:
          type: string
          example: Wema Bank
        bank_code:
          type: string
          example: '035'
        status:
          type: string
          example: active
        reference:
          type: string
          example: '1234567890'
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
        fee:
          $ref: '#/components/schemas/Decimal'
        meta:
          $ref: '#/components/schemas/VirtualBankAccountMeta'
    VirtualBankAccountMeta:
      type: object
      description: Additional metadata for the virtual bank account
      required:
        - methods
      properties:
        methods:
          type: array
          items:
            type: string
            enum:
              - ACH
              - WIRE
          example:
            - ACH
          description: The payment methods for this virtual bank account
        address:
          type: string
          example: 1800 North Pole St., Orlando, FL 32801
        sort_code:
          type: string
          example: 26-74-90
    VirtualBankAccountTerms:
      type: object
      description: Terms and conditions for a virtual bank account
      required:
        - title
        - subtitle
        - setup_and_fees
        - payment_methods
        - processing_time
        - limits
        - accepted_payments
      properties:
        title:
          type: string
          example: Account terms of use
          description: The main title for the terms screen
        subtitle:
          type: string
          example: To create a USD account, review & accept these usage terms
          description: The subtitle explaining the purpose
        setup_and_fees:
          $ref: '#/components/schemas/SetupAndFees'
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodFee'
          description: List of payment methods and their associated fees
        processing_time:
          $ref: '#/components/schemas/ProcessingTime'
        limits:
          $ref: '#/components/schemas/DepositLimits'
        accepted_payments:
          type: array
          items:
            type: string
          description: List of accepted payment descriptions
          example:
            - Receive unlimited deposit from accounts in your name, from registered business entities or from family members who share your surname.
            - Payments from sources other than those listed above (3rd party deposits) are also accepted, subject to limits.
    SetupAndFees:
      type: object
      description: Setup and fees information for the virtual bank account
      required:
        - setup_time
        - activation_fee
        - monthly_maintenance_fee
        - minimum_deposit
      properties:
        setup_time:
          $ref: '#/components/schemas/FeeItem'
        activation_fee:
          $ref: '#/components/schemas/FeeItem'
        monthly_maintenance_fee:
          $ref: '#/components/schemas/FeeItem'
        minimum_deposit:
          $ref: '#/components/schemas/FeeItem'
    FeeItem:
      type: object
      description: A fee or setup item with label, value and optional description
      required:
        - label
        - value
      properties:
        label:
          type: string
          example: Setup time
          description: The display label for the item
        value:
          type: string
          example: 1-2 days
          description: The value or amount for the item
        description:
          type: string
          example: Getting your account takes
          description: Additional description for the item
        is_free:
          type: boolean
          default: false
          description: Whether this item is free (for badge display)
    PaymentMethodFee:
      type: object
      description: Payment method and its associated fee
      required:
        - method
        - fee
      properties:
        method:
          type: string
          example: ACH
          description: The payment method name
        fee:
          type: string
          example: 1% of deposit
          description: The fee description for this payment method
        supported:
          type: boolean
          default: true
          description: Whether this payment method is supported
    ProcessingTime:
      type: object
      description: Processing time information
      required:
        - description
      properties:
        title:
          type: string
          example: Processing time
          description: The section title
        description:
          type: string
          example: Incoming deposits take 1-3 business days to arrive, depending on the payment method used
          description: Detailed processing time description
    DepositLimits:
      type: object
      description: Deposit limits for different party types
      required:
        - first_party
        - third_party
      properties:
        first_party:
          $ref: '#/components/schemas/LimitItem'
        third_party:
          $ref: '#/components/schemas/LimitItem'
    LimitItem:
      type: object
      description: A limit item with label and value
      required:
        - label
        - value
      properties:
        label:
          type: string
          example: 1st party deposits
          description: The limit type label
        value:
          type: string
          example: $100,000 max/deposit
          description: The limit value description
    LookUpResponseObject:
      type: object
      required:
        - username
        - currency
        - network
        - address
        - country_id
      properties:
        username:
          type: string
          example: john_doe@busha
        currency:
          type: string
          example: BTC
        country_id:
          $ref: '#/components/schemas/CountryID'
        network:
          type: string
          example: BTC
        address:
          type: string
          example: tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr
        memo:
          type: string
          example: memo123
        auto_convert_currency:
          type: string
          example: NGN
    SearchResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/SearchResponseObject'
    SearchResponseObject:
      type: object
      properties:
        assets:
          type: array
          description: Returns all available assets
          x-order: 1
          items:
            type: object
            required:
              - type
              - symbol
              - name
              - price
              - change
            properties:
              type:
                type: string
                example: asset
                description: Type of the result
              asset_type:
                type: string
                enum:
                  - fiat
                  - crypto
                example: crypto
                description: Asset class for the returned asset
              symbol:
                type: string
                example: ADA
                x-order: 1
              name:
                type: string
                example: Cardano
                x-order: 2
              price:
                $ref: '#/components/schemas/AmountWithCurrency'
              change:
                $ref: '#/components/schemas/Decimal'
        wallets:
          type: array
          description: List of wallets containing assets
          x-order: 2
          items:
            type: object
            required:
              - type
              - balance
              - last_activity
            properties:
              type:
                type: string
                example: wallet
              balance:
                $ref: '#/components/schemas/AmountWithCurrency'
              last_activity:
                type: string
                format: date
                example: '2025-08-14'
        transactions:
          type: array
          description: List of transactions related to assets
          x-order: 3
          items:
            type: object
            required:
              - id
              - type
              - symbol
              - amount
              - status
              - description
              - date
              - transaction_category
              - is_credit
              - is_fiat
            properties:
              id:
                $ref: '#/components/schemas/ID'
              type:
                type: string
                example: transaction
              symbol:
                type: string
                example: ADA
              amount:
                $ref: '#/components/schemas/AmountWithCurrency'
              status:
                type: string
                example: completed
              description:
                type: string
                example: Transaction description
              date:
                type: string
                format: date-time
                example: '2025-08-14T15:30:00Z'
              transaction_category:
                type: string
              is_credit:
                type: boolean
                example: true
              is_fiat:
                type: boolean
                example: true
        total_results:
          type: integer
          x-order: 4
          description: Total number of search results
          example: 15
    ValidateDestinationResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/ValidateDestinationResponseObject'
    ValidateDestinationResponseObject:
      allOf:
        - $ref: '#/components/schemas/ValidateDestinationRequest'
        - type: object
          properties:
            valid:
              type: boolean
              example: true
    ValidateDestinationRequest:
      type: object
      required:
        - type
        - currency
      properties:
        type:
          type: string
          example: address
          enum:
            - address
        address:
          type: string
          example: tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr
          description: |
            This is the address for type `address`
        currency:
          $ref: '#/components/schemas/Currency'
        network:
          type: string
          example: BTC
          description: |
            This specifies the blockchain network associated with the address receiving the payment, typically used with address type payouts.
        memo:
          type: string
          example: memo
          description: |
            This refers to the memo required for blockchain networks that mandate a memo for cryptocurrency transactions.
    RegenerateDepositAddressReq:
      type: object
      required:
        - network
        - currency
      properties:
        network:
          $ref: '#/components/schemas/Currency'
        currency:
          $ref: '#/components/schemas/Currency'
    ListBankResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Bank'
    Bank:
      type: object
      required:
        - name
        - code
        - currency
      properties:
        name:
          type: string
          x-order: 1
          example: Wema Bank
        code:
          type: string
          example: '000017'
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          example: NGN
    CountriesListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              description: List of recipients
              items:
                $ref: '#/components/schemas/Country'
          required:
            - data
    Country:
      type: object
      required:
        - id
        - name
        - currency
        - payment_methods
        - payout_methods
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/CountryID'
          x-order: 1
        name:
          type: string
          x-order: 2
          example: Bitcoin
          description: The official name of the cryptocurrency.
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyMini'
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PayObj'
        payout_methods:
          type: array
          items:
            $ref: '#/components/schemas/PayObj'
    CurrencyMini:
      type: object
      required:
        - code
        - name
        - symbol
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/Currency'
        name:
          type: string
          example: Bitcoin
          description: The official name of the cryptocurrency.
        symbol:
          type: string
          example: $
          description: The official symbol of the cryptocurrency.\
    PayObj:
      type: object
      required:
        - channel
        - name
        - min
        - max
        - currency
        - processing_time
      properties:
        channel:
          type: string
          example: bank-transfer
          description: The channel of the payment option.
        name:
          type: string
          example: Bitcoin
          description: The name of the payment option.
        min:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        max:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        processing_time:
          type: string
          example: 0-15 minutes
          description: The average time to process via the payment option.
    PaymentMethodLimitObj:
      type: object
      properties:
        max_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: The maximum allowed amount for this payment method.
    FieldRequirement:
      type: object
      description: Describes the requirement condition for a field.
      properties:
        required:
          type: boolean
          description: Whether this field is always required.
        required_above:
          type: string
          description: The field is required when the amount exceeds this threshold.
          example: '10000'
    PaymentOptionMeta:
      type: object
      description: |
        Optional metadata for the payment option. Contains additional context-specific
        information such as per-payment-method limits resolved based on the requesting
        profile type (personal or business).
      properties:
        payment_method_limits:
          type: object
          description: |
            Maximum amount limits keyed by payment method ID. The limits returned
            are resolved server-side based on the requesting profile type.
          additionalProperties:
            $ref: '#/components/schemas/PaymentMethodLimitObj'
        field_requirements:
          type: object
          description: |
            Describes which additional fields are required when creating a withdrawal
            for this payment option. Keyed by field name.
          additionalProperties:
            $ref: '#/components/schemas/FieldRequirement'
    PaymentOptionObj:
      type: object
      required:
        - channel
        - name
        - description
        - currency
        - payment_method_ids
        - minimum_fee
        - maximum_fee
        - minimum_amount
        - maximum_amount
        - recommended
        - new
        - support_conversion
      properties:
        channel:
          type: string
        name:
          type: string
        description:
          type: string
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        payment_method_ids:
          type: array
          items:
            $ref: '#/components/schemas/NanoID'
        maximum_fee:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        minimum_fee:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        maximum_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        minimum_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        recommended:
          type: boolean
        new:
          type: boolean
        support_conversion:
          type: boolean
        meta:
          $ref: '#/components/schemas/PaymentOptionMeta'
    PayOutObj:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          example: address
          description: |
            The payout type. NOTE: `sweep` is reserved for Busha Business
            dashboard sessions (master <-> sub-account internal transfers)
            and is rejected on public API-key requests.
          enum:
            - address
            - bank_transfer
            - mobile_money
            - paybill
            - till
            - balance
            - savings
            - direct_debit
            - sweep
        recipient_id:
          type: string
          example: 64ae8c26ea1033204c805a8a
          description: |
            This represents the recipient ID, used for `mobile_money` and `bank_transfer` types.
        address:
          type: string
          example: tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr
          description: |
            This could be the address, user email or username for type `address`. For type `sweep`, this is the email of the destination account. Required when the sender is the master (master -> sub); optional when the sender is a sub-account (the destination master is resolved automatically from the sub's parent business).
        network:
          type: string
          example: BTC
          description: |
            This specifies the blockchain network associated with the address receiving the payment, typically used with address type payouts.
        memo:
          type: string
          example: memo
          description: |
            This refers to the memo required for blockchain networks that mandate a memo for cryptocurrency transactions.
        narration:
          type: string
          example: Payment for services
          description: |
            A narration or description for the withdrawal. Required for USD bank transfer withdrawals.
        payment_invoice_url:
          type: string
          example: https://example.com/invoice.pdf
          description: |
            URL of the payment invoice or supporting document. Required for business account USD withdrawals
            and personal account USD withdrawals exceeding $10,000.
    RecipientDetails:
      type: object
      properties:
        account_name:
          type: string
        bank_name:
          type: string
        account_number:
          type: string
        country_code:
          type: string
          example: NG
        provider:
          type: string
        iban:
          type: string
          example: NG12345678901234567890
        currency:
          type: string
        phone_number:
          type: string
        name:
          type: string
        email:
          type: string
          example: sbsbs@busha.co
        bank_code:
          type: string
          example: '100020'
    PaymentObj:
      allOf:
        - $ref: '#/components/schemas/PayOutObj'
        - type: object
          properties:
            profile_id:
              type: string
              example: profile-id-1234
            memo:
              type: string
              example: address memo
            recipient_details:
              $ref: '#/components/schemas/RecipientDetails'
            blockchain_hash:
              type: string
              x-order: 16
              example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            blockchain_url:
              type: string
              x-order: 16
              example: https://explorer.com/tx/31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            session_id:
              type: string
              x-order: 16
              example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            from_address:
              type: string
              x-order: 16
              example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            expires_at:
              type: string
              format: date-time
              example: '2023-10-15T12:15:30Z'
    UnAuthPayInObj:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          example: address
          enum:
            - address
            - mobile_money
            - temporary_bank_account
            - direct_debit
            - balance
        network:
          type: string
          example: BTC
          description: |
            This specifies the blockchain network associated with the address receiving the payment, typically used with address type payouts.
    PayInObj:
      allOf:
        - $ref: '#/components/schemas/UnAuthPayInObj'
        - type: object
          properties:
            phone:
              $ref: '#/components/schemas/PhoneField'
            recipient_id:
              type: string
              example: 64ae8c26ea1033204c805a8a
              description: |
                This represents the recipient ID. Used for `direct_debit` types (mandate ID).
    NullableDecimal:
      type: string
      description: nullable decimal value
      example: '100'
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
        name: decimal
      nullable: true
    Pairs:
      type: object
      required:
        - id
        - base
        - base_currency_name
        - counter
        - counter_currency_name
        - type
        - is_buy_supported
        - is_sell_supported
        - buy_price
        - sell_price
      properties:
        id:
          type: string
          x-order: 1
          example: BTCNGN
        base:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 2
        base_currency_name:
          type: string
          x-order: 2
          example: Bitcoin
        counter:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 3
        counter_currency_name:
          type: string
          x-order: 3
          example: Naira
        type:
          type: string
          x-order: 4
          enum:
            - crypto
            - fiat
            - stablecoin
        buy_price:
          x-order: 5
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
        sell_price:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          x-order: 6
        is_buy_supported:
          x-order: 7
          type: boolean
        is_sell_supported:
          x-order: 8
          type: boolean
        min_buy_amount:
          x-order: 9
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        min_sell_amount:
          x-order: 10
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        max_buy_amount:
          x-order: 11
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        max_sell_amount:
          x-order: 12
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        base_decimal:
          type: string
          x-order: 13
          example: '6'
        counter_decimal:
          type: string
          x-order: 14
          example: '6'
        percentage_change:
          allOf:
            - $ref: '#/components/schemas/Decimal'
    AmountWithCounter:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          $ref: '#/components/schemas/Currency'
        counter:
          $ref: '#/components/schemas/AmountWithCurrency'
    PairsListResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          properties:
            data:
              type: array
              maxItems: 100
              items:
                $ref: '#/components/schemas/Pairs'
    PaymentLinkType:
      type: string
      enum:
        - payment_link
        - invoice
    UpdatePaymentLinkReq:
      type: object
      properties:
        quote_amount:
          $ref: '#/components/schemas/NullableDecimal'
        quote_currency:
          $ref: '#/components/schemas/NullableCurrency'
        target_amount:
          $ref: '#/components/schemas/NullableDecimal'
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        name:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - pending
            - active
        require_extra_info:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLinkExtraInfo'
        images:
          type: array
          items:
            type: string
            format: url
        allow_customer_amount:
          type: boolean
        amount_limit:
          $ref: '#/components/schemas/AmountLimit'
        allow_quantity_selection:
          type: boolean
        customer_email:
          type: string
          format: email
          description: Can update customer email for existing invoices
        customer_name:
          type: string
          description: Can update customer name for existing invoices
        due_date:
          type: string
          format: date-time
          description: Can update due date for existing invoices (must be in the future)
        note:
          type: string
          maxLength: 250
          description: Can update note for existing invoices (max 250 characters)
        items:
          type: array
          description: Update line items for existing invoices
          items:
            $ref: '#/components/schemas/InvoiceItem'
    CreatePaymentLinkReq:
      type: object
      required:
        - fixed
        - one_time
        - name
        - description
        - title
        - target_currency
      properties:
        type:
          $ref: '#/components/schemas/PaymentLinkType'
          description: Optional. Derived from fixed/one_time if not provided
        fixed:
          type: boolean
        one_time:
          type: boolean
        name:
          type: string
        title:
          type: string
        description:
          type: string
        quote_amount:
          $ref: '#/components/schemas/Decimal'
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        require_extra_info:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLinkExtraInfo'
        images:
          type: array
          items:
            type: string
            format: url
        allow_customer_amount:
          type: boolean
        amount_limit:
          $ref: '#/components/schemas/AmountLimit'
        allow_quantity_selection:
          type: boolean
        customer_email:
          type: string
          format: email
          description: Required when type is invoice
        customer_name:
          type: string
          description: Required when type is invoice
        due_date:
          type: string
          format: date-time
          description: Optional due date for invoice (must be in the future)
        note:
          type: string
          maxLength: 250
          description: Optional note for invoice (max 250 characters)
        items:
          type: array
          description: Line items for invoice type payment links
          items:
            $ref: '#/components/schemas/InvoiceItem'
        dry_run:
          type: boolean
          description: if true, will not create a payment transfer
    PaymentLink:
      type: object
      required:
        - id
        - profile_id
        - type
        - fixed
        - one_time
        - name
        - link
        - title
        - description
        - target_currency
        - status
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/NanoID'
        profile_id:
          $ref: '#/components/schemas/NanoID'
        type:
          x-order: 2
          $ref: '#/components/schemas/PaymentLinkType'
        fixed:
          x-order: 3
          type: boolean
          example: false
          description: |
            If true it will use the fixed amount, otherwise it will use the dynamic amount
        one_time:
          x-order: 4
          type: boolean
          example: false
          description: |
            If true it is a one-time link, otherwise it is a reusable link
        link:
          type: string
          format: url
          example: https://pay.busha.io/charges/123456789
        name:
          x-order: 5
          type: string
          example: Payment Link
        title:
          x-order: 6
          type: string
          description: |
            The display title shown to customers
        description:
          x-order: 7
          type: string
          description: |
            The display description shown to customers
        quote_amount:
          x-order: 8
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: |
            The amount to be paid for the product/service pegged to a fiat currency (quote currency)
        quote_currency:
          x-order: 9
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: |
            The fiat currency to display amounts in, which is converted from the source amount
        target_amount:
          x-order: 10
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: |
            The amount to be paid for the product/service in a crypto currency (target currency)
        target_currency:
          x-order: 11
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: |
            The crypto currency to which payment is to be received in
        meta:
          x-order: 12
          allOf:
            - $ref: '#/components/schemas/PaymentLinkMeta'
        status:
          x-order: 13
          allOf:
            - $ref: '#/components/schemas/PaymentLinkStatus'
        pub_key:
          type: string
        created_at:
          x-order: 14
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
        updated_at:
          x-order: 15
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
        expires_at:
          x-order: 16
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
    PaymentLinkStatus:
      type: string
      enum:
        - draft
        - pending
        - active
        - expired
        - deleted
    PaymentLinkMeta:
      type: object
      properties:
        images:
          type: array
          items:
            type: string
            format: url
        allow_customer_amount:
          type: boolean
        amount_limit:
          $ref: '#/components/schemas/AmountLimit'
        allow_quantity_selection:
          type: boolean
        require_extra_info:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLinkExtraInfo'
        customer_email:
          type: string
          format: email
          description: Customer email for invoices
        customer_name:
          type: string
          description: Customer name for invoices
        due_date:
          type: string
          format: date-time
          description: Due date for invoices
        note:
          type: string
          maxLength: 250
          description: Optional note for invoices
        items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceItem'
    InvoiceItem:
      type: object
      required:
        - item
        - quantity
        - amount
      properties:
        item:
          type: string
          description: Name/description of the item
          maxLength: 255
        quantity:
          type: integer
          description: Quantity of the item
          minimum: 1
        amount:
          $ref: '#/components/schemas/Decimal'
          description: Unit price of the item
    AmountLimit:
      type: object
      required:
        - min_amount
        - max_amount
      properties:
        min_amount:
          $ref: '#/components/schemas/Decimal'
        max_amount:
          $ref: '#/components/schemas/Decimal'
    PaymentLinkExtraInfo:
      type: object
      required:
        - field_name
        - required
      properties:
        field_name:
          type: string
        required:
          type: boolean
    PaymentLinkListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PaymentLink'
    NullableCurrency:
      type: string
      x-order: 20
      example: BTC
      format: string
      maxLength: 10
      minLength: 1
      nullable: true
    PaymentRequestStatus:
      type: string
      enum:
        - pending
        - expired
        - cancelled
        - completed
        - failed
        - multiple_deposits
        - under_payment
        - over_payment
    PaymentRequestType:
      type: string
      enum:
        - donation
        - checkout
        - invoice
    TwoStep:
      type: object
      required:
        - type
        - message
        - resend_allowed
      x-order: 17
      properties:
        type:
          type: string
          enum:
            - authenticator
          example: authenticator
          description: the type of two step verification required
        message:
          type: string
          example: Enter your 2FA code to continue
        resend_allowed:
          type: boolean
          example: false
          description: If the code can be resent
    AdditionalInfo:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: email address for the payment request
        phone_number:
          $ref: '#/components/schemas/PhoneField'
        name:
          $ref: '#/components/schemas/NameField'
        source:
          type: string
          description: The source of the payment request
          example: web
    MerchantInfo:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: name of the business
          example: busha
        email:
          type: string
          format: email
          description: email of the business
          example: busha@me.com
    Timeline:
      type: object
      required:
        - step
        - done
        - status
        - title
        - description
      properties:
        step:
          type: integer
          x-order: 1
          example: 1
        done:
          type: boolean
          x-order: 2
          example: true
        status:
          type: string
          x-order: 3
          enum:
            - pending
            - processing
            - funds_converted
            - funds_received
            - outgoing_payment_sent
            - funds_delivered
            - reverse_fund_conversion
            - failed
            - completed
        title:
          type: string
          x-order: 4
          example: Transfer started
        description:
          type: string
          x-order: 5
          example: Transfer started
          description: Waiting for payment
        timestamp:
          type: string
          x-order: 6
          format: date-time
          example: '2023-10-15T12:15:30Z'
    TransferTimeline:
      type: object
      required:
        - total_steps
        - current_step
        - transfer_status
        - events
      properties:
        total_steps:
          type: integer
          x-order: 1
        current_step:
          type: integer
          x-order: 2
        transfer_status:
          type: string
          x-order: 3
        events:
          type: array
          items:
            $ref: '#/components/schemas/Timeline'
    PaymentRequest:
      type: object
      required:
        - id
        - source_amount
        - source_currency
        - target_amount
        - target_currency
        - requested_amount
        - currency
        - rate
        - fees
        - reference
        - additional_info
        - merchant_info
        - status
        - type
        - created_at
        - updated_at
        - expires_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/NanoID'
          x-order: 1
        type:
          allOf:
            - $ref: '#/components/schemas/PaymentRequestType'
          x-order: 2
        status:
          allOf:
            - $ref: '#/components/schemas/PaymentRequestStatus'
          x-order: 3
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 4
        source_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 5
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 6
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 7
        requested_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: The amount requested by the merchant
          x-order: 8
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: The currency it was requested in
          x-order: 9
        rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 10
        fees:
          type: array
          items:
            $ref: '#/components/schemas/Fee'
          x-order: 11
        pay_in:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 12
        two_step:
          allOf:
            - $ref: '#/components/schemas/TwoStep'
          x-order: 13
        reference:
          type: string
          x-order: 14
        additional_info:
          allOf:
            - $ref: '#/components/schemas/AdditionalInfo'
          x-order: 15
        merchant_info:
          allOf:
            - $ref: '#/components/schemas/MerchantInfo'
          x-order: 16
        source:
          type: string
          description: The source of the payment request
          x-order: 17
        source_id:
          type: string
          description: The source id of the payment request
          x-order: 18
        timeline:
          allOf:
            - $ref: '#/components/schemas/TransferTimeline'
          x-order: 19
        created_at:
          type: string
          format: date-time
          example: '2023-10-15T12:15:30Z'
          x-order: 20
        updated_at:
          type: string
          format: date-time
          example: '2023-10-15T12:15:30Z'
          x-order: 21
        expires_at:
          type: string
          format: date-time
          example: '2023-10-15T12:15:30Z'
          x-order: 22
        quote_rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 23
          description: This shows the rate of quote currency to source currency if quote currency is provided.
    CreatePaymentRequestForLinkReq:
      type: object
      required:
        - source_currency
      properties:
        quote_amount:
          $ref: '#/components/schemas/Decimal'
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        source_currency:
          $ref: '#/components/schemas/Currency'
        source_amount:
          $ref: '#/components/schemas/Decimal'
        target_amount:
          $ref: '#/components/schemas/Decimal'
        pay_in:
          $ref: '#/components/schemas/PayInObj'
        requested_info:
          type: object
          additionalProperties:
            type: string
        reference:
          type: string
    PaymentRequestResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/PaymentRequest'
    PaymentRequestListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              description: List of payment requests
              items:
                $ref: '#/components/schemas/PaymentRequest'
    CreatePaymentRequest:
      type: object
      required:
        - additional_info
        - source_currency
        - target_currency
      properties:
        additional_info:
          $ref: '#/components/schemas/AdditionalInfo'
        quote_amount:
          $ref: '#/components/schemas/Decimal'
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: This optional field specifies the fiat currency to display amounts in, which is converted from the source amount
          example: NGN
        source_amount:
          $ref: '#/components/schemas/Decimal'
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_amount:
          $ref: '#/components/schemas/Decimal'
        target_currency:
          $ref: '#/components/schemas/Currency'
        pay_in:
          $ref: '#/components/schemas/PayInObj'
        dry_run:
          type: boolean
          description: if true, validate and preview without creating quote/payment request records
        reference:
          type: string
          description: reference for the payment request
          example: busha-123
    FinalizePaymentRequest:
      type: object
      properties:
        code:
          type: string
          maxLength: 6
          description: Optional auth code required for MFA
    PriceAlert:
      type: object
      required:
        - id
        - product
        - target_price
        - status
        - alert_type
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: ID
          example: 507f1f77bcf86cd799439011
        product:
          type: string
          description: Trading pair product code
          example: BTCUSDT
        target_price:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Target price for the alert
        status:
          allOf:
            - $ref: '#/components/schemas/PriceAlertStatus'
        alert_type:
          type: string
          enum:
            - ABOVE
            - BELOW
          description: Type of alert
          example: ABOVE
        created_at:
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
        updated_at:
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
    PriceAlertStatus:
      type: string
      enum:
        - active
        - triggered
      description: Current status of the price alert
    PriceAlertListResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PriceAlert'
    ExampleQuoteResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          properties:
            data:
              type: object
              properties:
                greeting:
                  type: string
                  example: Welcome to the quote service!
    QuoteReference:
      type: string
      x-order: 2
      example: QUO_123456abc
      maxLength: 64
      minLength: 12
    UnauthenticatedCreateQuote:
      type: object
      required:
        - source_currency
        - target_currency
      properties:
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_currency:
          $ref: '#/components/schemas/Currency'
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: This optional field specifies the fiat currency to display amounts in, which is converted from the source amount
          example: NGN
        quote_amount:
          type: string
          description: The amount in the quote currency. Required when quote_currency is provided
          example: '100'
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
            x-oapi-codegen-extra-tags:
              validate: requiredWith:quote_currency|num
        source_amount:
          type: string
          description: Source Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
            x-oapi-codegen-extra-tags:
              validate: requiredWithout:target_amount|num
        target_amount:
          type: string
          description: Target Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
            x-oapi-codegen-extra-tags:
              validate: requiredWithout:source_amount|num
        pay_in:
          $ref: '#/components/schemas/UnAuthPayInObj'
        pay_out:
          $ref: '#/components/schemas/PayOutObj'
    CreateQuoteRequest:
      type: object
      required:
        - source_currency
        - target_currency
      properties:
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_currency:
          $ref: '#/components/schemas/Currency'
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: This optional field specifies the fiat currency to display amounts in, which is converted from the source amount
          example: NGN
        quote_amount:
          type: string
          description: The amount in the quote currency. Required when quote_currency is provided
          example: '100'
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
            x-oapi-codegen-extra-tags:
              validate: requiredWith:quote_currency|num
        reversal_policy:
          type: string
          description: This optional field specifies the reversal policy for the conversion. Allowed values are 'conversion_only'.
          enum:
            - conversion_only
        reference:
          $ref: '#/components/schemas/QuoteReference'
        source_amount:
          type: string
          description: Source Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
            x-oapi-codegen-extra-tags:
              validate: requiredWithout:target_amount|num
        target_amount:
          type: string
          description: Target Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
            x-oapi-codegen-extra-tags:
              validate: requiredWithout:source_amount|num
        pay_in:
          allOf:
            - $ref: '#/components/schemas/PayInObj'
            - type: object
              properties:
                phone:
                  $ref: '#/components/schemas/PhoneField'
        pay_out:
          $ref: '#/components/schemas/PayOutObj'
    Quote:
      type: object
      required:
        - id
        - source_currency
        - target_currency
        - source_amount
        - target_amount
        - profile_id
        - reference
        - created_at
        - updated_at
        - status
        - rate
        - fees
      properties:
        id:
          $ref: '#/components/schemas/ResourceID'
        source_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 5
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 6
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 7
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 8
        profile_id:
          $ref: '#/components/schemas/NanoID'
        rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 9
        fees:
          type: array
          x-order: 10
          items:
            $ref: '#/components/schemas/Fee'
        pay_in:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 11
        pay_out:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 12
        reference:
          allOf:
            - $ref: '#/components/schemas/QuoteReference'
          x-order: 12
        status:
          type: string
          x-order: 13
          enum:
            - pending
            - accepted
            - expired
          example: pending
        expires_at:
          type: string
          x-order: 14
          format: date-time
          example: '2023-12-01T15:04:05Z'
        created_at:
          type: string
          x-order: 15
          format: date-time
          example: '2023-10-15T12:15:30Z'
        updated_at:
          type: string
          x-order: 16
          format: date-time
          example: '2023-10-15T12:20:45Z'
        two_step:
          $ref: '#/components/schemas/TwoStep'
        quote_rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 17
          description: This shows the rate of quote currency to source currency if quote currency is provided.
    CreateRecipientRequest:
      oneOf:
        - $ref: '#/components/schemas/RecipientCreate-2025-07-11'
        - type: object
          deprecated: true
          required:
            - currency_id
            - country_id
            - type
            - legal_entity_type
            - fields
          properties:
            currency_id:
              $ref: '#/components/schemas/Currency'
            country_id:
              $ref: '#/components/schemas/CountryID'
            type:
              type: string
              description: Type of recipient account
              example: ngn_bank_transfer
            legal_entity_type:
              type: string
              description: Type of legal entity
              enum:
                - business
                - personal
              example: business
            fields:
              type: array
              description: List of fields containing recipient details
              items:
                type: object
                required:
                  - name
                  - value
                properties:
                  name:
                    type: string
                    description: Field identifier
                    example: bank_name
                  value:
                    type: string
                    description: Field value
                    example: Access Bank Nigeria
    RecipientField:
      type: object
      required:
        - value
        - display_name
        - name
        - is_copyable
        - is_visible
        - required
      properties:
        value:
          type: string
          description: The value of the recipient field
          example: Access Bank Nigeria
        display_name:
          type: string
          description: Human-readable name of the field
          example: Bank Name
        name:
          type: string
          description: System identifier for the field
          example: bank_name
        is_copyable:
          type: boolean
          description: Whether the field value can be copied
          example: false
        is_visible:
          type: boolean
          description: Whether the field should be displayed
          example: true
        required:
          type: boolean
          description: Whether the field is required
          example: true
    ResolveBankAccountRequest:
      type: object
      required:
        - country_id
        - currency_id
        - channel
        - account_number
      properties:
        currency_id:
          $ref: '#/components/schemas/Currency'
        country_id:
          $ref: '#/components/schemas/CountryID'
        channel:
          $ref: '#/components/schemas/Channel'
        bank_code:
          type: string
          description: Bank sort code
          example: '000013'
        account_number:
          type: string
          description: Account number for receiving bank
          example: '0123456789'
      example:
        currency_id: NGN
        country_id: NG
        channel: mobile_money
        bank_code: '000013'
        account_number: '0123456789'
    Channel:
      type: string
      description: Channel for the transfer
      enum:
        - mobile_money
        - bank_transfer
        - pay_bill
        - till
      example: bank_transfer
    Recipient:
      deprecated: true
      type: object
      required:
        - object
        - id
        - user_id
        - profile_id
        - type
        - legal_entity_type
        - owned_by_customer
        - active
        - created_at
        - updated_at
        - fields
      properties:
        object:
          type: string
          description: Type of the object
          example: recipient
        id:
          $ref: '#/components/schemas/ID'
        user_id:
          $ref: '#/components/schemas/ID'
        profile_id:
          $ref: '#/components/schemas/ID'
        currency_id:
          $ref: '#/components/schemas/Currency'
        country_id:
          $ref: '#/components/schemas/CountryID'
        type:
          type: string
          description: Type of recipient account
          example: ngn_bank_transfer
        legal_entity_type:
          type: string
          description: Type of legal entity
          enum:
            - business
            - personal
          example: business
        owned_by_customer:
          type: boolean
          description: Whether the recipient is owned by the customer
          example: true
        active:
          type: boolean
          description: Whether the recipient is active
          example: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the recipient was created
          example: '2024-05-16T13:06:31.409336+01:00'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the recipient was last updated
          example: '2024-05-16T13:06:31.409336+01:00'
        fields:
          type: array
          description: List of fields containing recipient details
          items:
            $ref: '#/components/schemas/RecipientField'
    RecipientBase-2025-07-11:
      type: object
      required:
        - type
      properties:
        channel:
          type: string
          description: Channel for the transfer (business_mobile_money only)
          x-oapi-codegen-extra-tags:
            mapstructure: channel,omitempty
        currency:
          type: string
          description: Currency code for the recipient
          x-oapi-codegen-extra-tags:
            mapstructure: currency,omitempty
        country_code:
          type: string
          description: Country code for the recipient
          x-oapi-codegen-extra-tags:
            mapstructure: country_code,omitempty
        type:
          type: string
          description: Type of recipient account
          enum:
            - ngn_bank
            - kes_bank
            - usd_bank
            - gbp_bank
            - mpesa_mobile_money
            - mtn_mobile_money
            - crypto
            - paybill
            - till
          x-oapi-codegen-extra-tags:
            mapstructure: ',omitempty'
        entity_type:
          type: string
          additionalProperties: true
          description: Type of legal entity (for US, GB)
          enum:
            - personal
            - business
          x-oapi-codegen-extra-tags:
            mapstructure: entity_type,omitempty
        transfer_type:
          type: string
          additionalProperties: true
          description: Type of transfer (for US)
          enum:
            - ach
            - wire
            - swift
          x-oapi-codegen-extra-tags:
            mapstructure: transfer_type,omitempty
        address_label:
          type: string
          description: Name of the wallet (for crypto)
          x-oapi-codegen-extra-tags:
            mapstructure: wallet_name,omitempty
        account_name:
          type: string
          description: Name on the account
          x-oapi-codegen-extra-tags:
            mapstructure: account_name,omitempty
        bank_name:
          type: string
          description: Name of the bank (for NG, US, GB)
          x-oapi-codegen-extra-tags:
            mapstructure: bank_name,omitempty
        bank_code:
          type: string
          description: Bank code (for NG only)
          x-oapi-codegen-extra-tags:
            mapstructure: bank_code,omitempty
        sort_code:
          type: string
          description: Sort code (for GB only)
          x-oapi-codegen-extra-tags:
            mapstructure: sort_code,omitempty
        routing_number:
          type: string
          description: Routing number (for US domestic ACH/Wire)
          x-oapi-codegen-extra-tags:
            mapstructure: routing_number,omitempty
        swift_code:
          type: string
          description: SWIFT/BIC code (for international transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: swift_code,omitempty
        account_number:
          type: string
          description: Account number (for domestic transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: account_number,omitempty
        till_number:
          type: string
          description: Till number (for domestic transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: till_number,omitempty
        paybill:
          type: string
          description: Paybill (for domestic transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: paybill,omitempty
        iban:
          type: string
          description: IBAN (for international transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: iban,omitempty
        phone_number:
          $ref: '#/components/schemas/PhoneField'
        network:
          type: string
          description: Blockchain network (for crypto transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: network,omitempty
        address:
          type: string
          description: Wallet address (for crypto transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: address,omitempty
        memo:
          type: string
          description: Tag/memo (for crypto transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: memo,omitempty
        recipient_address:
          type: string
          description: Address details (for international transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: recipient_address,omitempty
        intermediary_bank_name:
          type: string
          example: JPMorgan Chase Bank
          x-oapi-codegen-extra-tags:
            mapstructure: intermediary_bank_name,omitempty
        intermediary_bank_address:
          type: string
          example: 270 Park Avenue, New York, NY 10017
          x-oapi-codegen-extra-tags:
            mapstructure: intermediary_bank_address,omitempty
        intermediary_swift_code:
          type: string
          example: CHASUS33
          x-oapi-codegen-extra-tags:
            mapstructure: intermediary_swift_code,omitempty
        busha_wallet:
          type: boolean
          description: Whether the recipient is a a busha wallet
          x-oapi-codegen-extra-tags:
            mapstructure: busha_wallet,omitempty
    RecipientCreate-2025-07-11:
      allOf:
        - $ref: '#/components/schemas/RecipientBase-2025-07-11'
        - type: object
          properties:
            one_time:
              type: boolean
              description: Whether the recipient is a one-time recipient. One-time recipients are stored but not returned in list or get responses.
    Recipient-2025-07-11:
      allOf:
        - $ref: '#/components/schemas/RecipientBase-2025-07-11'
        - type: object
          required:
            - object
            - id
            - profile_id
            - active
            - owned_by_customer
            - type
            - category
          properties:
            object:
              type: string
              description: Type of object
              example: recipient
            id:
              $ref: '#/components/schemas/ResourceID'
            profile_id:
              $ref: '#/components/schemas/NanoID'
            active:
              type: boolean
              description: Whether the recipient is active
            owned_by_customer:
              type: boolean
              description: Whether the recipient is owned by the customer
            category:
              type: string
              description: Category of recipient
              enum:
                - bank
                - mobile_money
                - crypto
    RecipientResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              oneOf:
                - $ref: '#/components/schemas/Recipient'
                - $ref: '#/components/schemas/Recipient-2025-07-11'
    RecipientListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              description: List of recipients
              items:
                oneOf:
                  - $ref: '#/components/schemas/Recipient-2025-07-11'
                  - $ref: '#/components/schemas/Recipient'
          required:
            - data
    RecipientRequirementListResponse:
      x-interal: true
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/RecipientRequirement'
    RecipientRequirement:
      x-interal: true
      type: object
      required:
        - id
        - countries
        - currencies
        - name
        - description
        - type
        - fields
        - active
        - created_at
        - entity_type
      properties:
        id:
          type: string
          x-order: 1
        currencies:
          type: array
          x-order: 5
          items:
            $ref: '#/components/schemas/Currency'
        countries:
          type: array
          x-order: 6
          items:
            $ref: '#/components/schemas/CountryID'
        name:
          type: string
          x-order: 2
        description:
          type: string
          x-order: 7
        type:
          type: string
          x-order: 3
        fields:
          type: array
          x-order: 9
        active:
          type: boolean
          x-order: 4
        entity_type:
          type: boolean
          x-order: 8
        created_at:
          type: string
          format: date-time
    ResolveBankAccountResp:
      type: object
      required:
        - country_id
        - currency_id
        - channel
        - account_number
        - account_name
      properties:
        country_id:
          $ref: '#/components/schemas/CountryID'
        currency_id:
          $ref: '#/components/schemas/Currency'
        channel:
          $ref: '#/components/schemas/Channel'
        bank_code:
          type: string
          description: Bank sort code
          example: '000013'
        account_number:
          type: string
          description: Account number for receiving bank
          example: '0123456789'
        account_name:
          type: string
          description: Name on receiving account
          example: John Doe
        bank_name:
          type: string
          description: Name of receiving bank
          example: Trust Bank
    EarnAmountType:
      allOf:
        - $ref: '#/components/schemas/AmountWithCurrency'
        - type: object
          properties:
            fiat:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
              description: amount in fiat
              x-order: 3
    TransactionsListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              description: List of recipients
              items:
                $ref: '#/components/schemas/Transaction'
          required:
            - data
    TransactionTypes:
      type: string
      description: transaction type
      enum:
        - buys
        - sells
        - converts
        - utilities
        - rewards
        - loans
        - savings
        - savings.withdrawals
        - savings.deposit
        - savings.interests
        - deposits
        - withdrawals
        - sends
        - receives
    Transaction:
      type: object
      required:
        - id
        - object
        - status
        - created_at
        - reference
        - user_id
        - profile_id
        - type
        - description
        - sub_description
        - amount
        - currency
        - is_fiat
        - is_credit
        - status_description
      properties:
        id:
          x-order: 1
          allOf:
            - $ref: '#/components/schemas/ID'
        object:
          x-order: 2
          type: string
          description: Type of the object
          example: transaction
        status:
          x-order: 3
          type: string
          description: transaction status
          enum:
            - pending
            - completed
            - failed
            - cancelled
            - processing
          example: completed
        created_at:
          x-order: 4
          type: string
          format: date-time
          description: Timestamp when the transaction was created
          example: '2024-05-16T13:06:31.409336+01:00'
        reference:
          x-order: 5
          type: string
          description: transaction reference
          example: ORD_7ain6FEDWB
        user_id:
          x-order: 6
          allOf:
            - $ref: '#/components/schemas/ID'
        profile_id:
          x-order: 7
          allOf:
            - $ref: '#/components/schemas/ID'
        type:
          x-order: 8
          allOf:
            - $ref: '#/components/schemas/TransactionTypes'
          example: buys
        description:
          x-order: 9
          type: string
          description: transaction description
          example: Bought US Dollar
        sub_description:
          x-order: 10
          type: string
          description: transaction sub_description
          example: With USD Token
        amount:
          x-order: 11
          allOf:
            - $ref: '#/components/schemas/Decimal'
        currency:
          x-order: 12
          allOf:
            - $ref: '#/components/schemas/Currency'
        is_fiat:
          x-order: 13
          type: boolean
          description: tells if transaction is in a fiat currency
        is_credit:
          x-order: 14
          type: boolean
          description: tells if transaction is a credit
        meta:
          x-order: 15
          allOf:
            - $ref: '#/components/schemas/TransactionMeta'
        status_description:
          x-order: 16
          type: string
          description: transaction status_description
          example: This has been processed by Busha
    TransactionMeta:
      type: object
      description: Additional transaction metadata
      required:
        - price
        - balance
      properties:
        conversion:
          $ref: '#/components/schemas/TxnMetaConversion'
        price:
          type: object
          properties:
            amount:
              $ref: '#/components/schemas/Decimal'
            currency:
              type: string
              description: Fiat currency of user
        balance:
          type: object
          properties:
            total:
              $ref: '#/components/schemas/Decimal'
            available:
              $ref: '#/components/schemas/Decimal'
        source:
          type: object
          description: Source details (for deposits, receives)
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - bank_transfer
                    - mobile_money
                    - username
                    - email
                    - wallet
            - oneOf:
                - $ref: '#/components/schemas/TxnMetaBankTransferSource'
                - $ref: '#/components/schemas/TxnMetaMobileMoneySource'
                - $ref: '#/components/schemas/TxnMetaUsernameSource'
                - $ref: '#/components/schemas/TxnMetaEmailSource'
                - $ref: '#/components/schemas/TxnMetaCryptoWalletSource'
        destination:
          type: object
          description: Destination details (for withdraws, sends)
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - bank_transfer
                    - wire_transfer
                    - mobile_money
                    - username
                    - email
                    - wallet
            - oneOf:
                - $ref: '#/components/schemas/TxnMetaBankTransferDestination'
                - $ref: '#/components/schemas/TxnMetaWireTransferDestination'
                - $ref: '#/components/schemas/TxnMetaMobileMoneyDestination'
                - $ref: '#/components/schemas/TxnMetaUsernameDestination'
                - $ref: '#/components/schemas/TxnMetaEmailDestination'
                - $ref: '#/components/schemas/TxnMetaCryptoWalletDestination'
        savings:
          $ref: '#/components/schemas/TxnMetaSaving'
        service:
          $ref: '#/components/schemas/TxnMetaService'
        third_party_reference:
          type: string
          description: Reference from external payment service i.e till, paybill, mobile_money
        fee:
          $ref: '#/components/schemas/TxnMetaFee'
        amounts:
          $ref: '#/components/schemas/TxnMetaAmounts'
    TxnMetaAmounts:
      description: Transactions amounts explained
      allOf:
        - type: object
          properties:
            fee:
              $ref: '#/components/schemas/Decimal'
        - oneOf:
            - $ref: '#/components/schemas/TxnMetaDepositAmounts'
            - $ref: '#/components/schemas/TxnMetaPayoutAmounts'
    TxnMetaDepositAmounts:
      type: object
      properties:
        amount_paid:
          $ref: '#/components/schemas/Decimal'
        amount_added:
          $ref: '#/components/schemas/Decimal'
    TxnMetaPayoutAmounts:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        total:
          $ref: '#/components/schemas/Decimal'
    TxnMetaFee:
      type: object
      description: Fee details
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
          description: Currency of fee
    TxnMetaSaving:
      type: object
      description: Savings details
      properties:
        action:
          type: string
          description: Savings action type
          enum:
            - deposit
            - withdrawal
            - interest
        id:
          type: string
          description: Savings plan identifier
    TxnMetaService:
      type: object
      description: Service details (for utility transactions)
      properties:
        type:
          type: string
          description: Service type
          enum:
            - airtime
            - data
            - bills
            - voucher
            - betting
            - electricity
            - cable
        phone_number:
          type: string
          description: Phone number (for airtime)
        network:
          type: string
          description: Network provider
        merchant:
          type: string
          description: Merchant name (for vouchers)
        amount:
          $ref: '#/components/schemas/Decimal'
        logo_url:
          type: string
          format: uri
          description: Logo URL for the service provider
        meter_no:
          type: string
          description: Meter number (for electricity)
        account_type:
          type: string
          description: Meter account type, e.g. prepaid/postpaid (for electricity)
        smartcard_no:
          type: string
          description: Smartcard number (for cable)
        plan_name:
          type: string
          description: Subscription plan name (for cable)
        bundle:
          type: string
          description: Data bundle name (for data)
        customer_no:
          type: string
          description: Customer/account number on the biller platform (for betting)
        recipient_email:
          type: string
          description: Recipient email address (for voucher delivery)
    TxnMetaConversion:
      type: object
      properties:
        source_currency:
          type: string
          description: Currency being converted from
        source_amount:
          $ref: '#/components/schemas/Decimal'
        target_currency:
          type: string
          description: Currency being converted to
        target_amount:
          $ref: '#/components/schemas/Decimal'
        rate:
          $ref: '#/components/schemas/Decimal'
        rate_explained:
          type: string
          description: Human readable rate explanation
    TxnMetaBankTransferSource:
      type: object
      description: Bank Transfer Source
      properties:
        bank_name:
          type: string
          description: Bank name
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        session_id:
          type: string
          description: Session ID
    TxnMetaMobileMoneySource:
      type: object
      description: Mobile Money Source
      properties:
        provider:
          type: string
          description: Provider Name
        phone_number:
          type: string
          description: Phone number
        account_name:
          type: string
          description: Account name
    TxnMetaUsernameSource:
      type: object
      description: Username Source
      properties:
        username:
          type: string
          description: Username
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaEmailSource:
      type: object
      description: Email Source
      properties:
        email:
          type: string
          description: Email
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaCryptoWalletSource:
      type: object
      description: Crypto Wallet Source
      properties:
        network_name:
          type: string
          description: Network name
        network_currency:
          type: string
          description: Network currency
        address:
          type: string
          description: Wallet address
        destination_tag:
          type: string
          description: Destination tag
        confirmations:
          type: string
          format: integer
          description: Number of confirmations
        hash:
          type: string
          description: Transaction hash
        blockchain_url:
          type: string
          description: Blockchain URL
        address_url:
          type: string
          description: Address URL
    TxnMetaBankTransferDestination:
      type: object
      description: Bank Transfer Destination
      properties:
        bank_name:
          type: string
          description: Bank name
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        session_id:
          type: string
          description: Session ID
    TxnMetaWireTransferDestination:
      type: object
      description: Wire transfer Destination
      properties:
        bank_name:
          type: string
          description: Bank name
        swift_code:
          type: string
          description: SWIFT code
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        imad:
          type: string
          description: IMAD
        routing_number:
          type: string
          description: Routing number
        address:
          type: string
          description: Address
    TxnMetaMobileMoneyDestination:
      type: object
      description: Mobile Money Destination
      properties:
        provider:
          type: string
          description: Provider Name
        phone_number:
          type: string
          description: Phone number
        account_name:
          type: string
          description: Account name
    TxnMetaUsernameDestination:
      type: object
      description: Username Destination
      properties:
        username:
          type: string
          description: Username
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaEmailDestination:
      type: object
      description: Email Destination
      properties:
        email:
          type: string
          description: Email
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaCryptoWalletDestination:
      type: object
      description: Crypto Wallet Destination
      properties:
        network_name:
          type: string
          description: Network name
        network_currency:
          type: string
          description: Network currency
        address:
          type: string
          description: Wallet address
        destination_tag:
          type: string
          description: Destination tag
        hash:
          type: string
          description: Transaction hash
        blockchain_url:
          type: string
          description: Blockchain URL
        address_url:
          type: string
          description: Address URL
    Transfer:
      type: object
      required:
        - id
        - quote_id
        - description
        - sub_description
        - source_currency
        - target_currency
        - source_amount
        - target_amount
        - profile_id
        - created_at
        - updated_at
        - status
        - rate
        - fees
      properties:
        id:
          $ref: '#/components/schemas/ResourceID'
        quote_id:
          $ref: '#/components/schemas/NanoID'
        stages:
          type: array
          description: Ordered pipeline steps included in the transfer flow.
          example:
            - deposit
            - conversion
          items:
            type: string
            enum:
              - deposit
              - conversion
              - withdrawal
          x-order: 2
        category:
          type: string
          description: Computed shorthand derived from the transfer stages.
          example: buy
          enum:
            - deposit
            - withdrawal
            - conversion
            - buy
            - sell
            - send
            - exchange
          x-order: 3
        description:
          type: string
          example: Bought Bitcoin
          x-order: 4
        sub_description:
          type: string
          example: With Naira
          x-order: 5
        source_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 6
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 7
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 8
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 9
        trade:
          type: string
          example: buy
          x-order: 10
        profile_id:
          $ref: '#/components/schemas/NanoID'
        rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 11
        fees:
          type: array
          x-order: 12
          items:
            $ref: '#/components/schemas/Fee'
        pay_in:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 13
        pay_out:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 14
        status:
          allOf:
            - $ref: '#/components/schemas/TransferStatus'
          x-order: 15
        timeline:
          allOf:
            - $ref: '#/components/schemas/TransferTimeline'
          x-order: 16
        expires_at:
          type: string
          x-order: 17
          format: date-time
          example: '2023-12-01T15:04:05Z'
        created_at:
          type: string
          x-order: 18
          format: date-time
          example: '2023-10-15T12:15:30Z'
        updated_at:
          type: string
          x-order: 19
          format: date-time
          example: '2023-10-15T12:20:45Z'
    CreateTransferRequest:
      type: object
      required:
        - quote_id
      properties:
        quote_id:
          $ref: '#/components/schemas/NanoID'
    TransferStatus:
      type: string
      description: Status of a transfer
      enum:
        - pending
        - processing
        - cancelled
        - funds_converted
        - funds_received
        - outgoing_payment_sent
        - funds_delivered
        - funds_not_delivered
        - funds_refunded
        - reverse_fund_conversion
    WebhookAction:
      type: object
      required:
        - id
        - status
        - category
        - event
        - created_at
      properties:
        id:
          x-order: 1
          type: string
          description: Webhook action ID
        status:
          x-order: 2
          type: string
          description: Whether the event was successfully sent to the provider
          enum:
            - success
            - pending
        category:
          x-order: 3
          type: string
          description: Event category derived from event name
          example: Transfer
        event:
          x-order: 4
          type: string
          description: The event name
          example: transfer.pending
        created_at:
          x-order: 5
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
          description: Timestamp when the event was created
    WebhookActionListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/WebhookAction'
  responses:
    BalanceError4XX:
      description: 409 error when a balance with the same currency already exists for a user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    BalanceError5XX:
      description: Server error when processing the balance request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    CurrenciesError4XX:
      description: Error from customer resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    CurrenciesError5XX:
      description: Server error when processing the currencies request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    CustomerError4XX:
      description: Something went wrong in Customer resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    CustomerError5XX:
      description: Server error when processing the customers request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    CustomerResponse:
      description: Successful response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
    CustomerBusinessIndustries:
      description: Successful response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerBusinessIndustry'
    CustomerListResponse:
      description: Customer List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CursorPagination'
              - type: object
                required:
                  - pagination
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
    GeneralResponse:
      description: A general response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
    FilesError5XX:
      description: Server error when processing the miscellaneous request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    FilesError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    VirtualBankAccountResponse:
      description: Successful Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualBankAccount'
    VirtualBankAccountTermsResponse:
      description: Successful Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualBankAccountTerms'
    LookupResponses:
      description: Successful Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: List of Plans
                    items:
                      $ref: '#/components/schemas/LookUpResponseObject'
    MiscellaneousError5XX:
      description: Server error when processing the miscellaneous request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    MiscellaneousError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PaymentOptionsListResponse:
      description: Payment Options List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentOptionObj'
    PairError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PairError5XX:
      description: Server error when processing the pair request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    PaymentLinkError5XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    PaymentLinkError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PaymentRequestError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PaymentRequestError5XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    QuoteError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    QuoteError5XX:
      description: Server error when processing the quote request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    QuoteResponse:
      description: Quote Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Quote'
    QuotesListResponse:
      description: Quotes List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CursorPagination'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Quote'
    RecipientError4XX:
      description: Recipient Error sample
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    RecipientError5XX:
      description: Server error when processing the recipient request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    TransactionsError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    TransactionsError5XX:
      description: Server error when processing the transaction request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    TransferError5XX:
      description: Server error when processing the transfer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    TransferError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    TransferResponse:
      description: Transfer Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Transfer'
    TransferListResponse:
      description: Transfer List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CursorPagination'
              - type: object
                properties:
                  data:
                    type: array
                    description: List of transfers
                    items:
                      $ref: '#/components/schemas/Transfer'
                required:
                  - data
  securitySchemes:
    Auth:
      type: http
      scheme: bearer
      description: Bearer Authentication
    AuthOptional:
      type: http
      scheme: bearer
      description: Bearer Authentication
  examples:
    DefaultError:
      description: Default error
      value:
        error:
          name: bad_request
          message: Invalid request
    NotFoundError:
      description: Not Found error
      value:
        error:
          name: resource_not_found
          message: Resource Not Found
    UnAuthorizedError:
      description: Unauthorized Error
      value:
        error:
          name: unauthorized
          message: Unauthorized request
    RequestValidationError:
      description: Request Validation error example
      value:
        error:
          name: request_validation
          message: Validation error
        fields:
          field1:
            - reason: One of target and source amount must be set
          field2:
            - reason: One of target and source amount must be set
    SchemaValidationError:
      description: Schema validation error example
      value:
        error:
          name: schema_validation
          message: Error Validating Requests
        schema:
          - reason: The request body is defined as an object. However, it does not meet the schema requirements of the specification
            fix: Ensure that the object being submitted, matches the schema correctly
            schema_validation_error:
              - 'minLength: got 3, want 12'
    InternalServerError:
      description: Internal Server Error
      value:
        error:
          name: internal_server_error
          message: Internal Server Error
    ServiceUnavailableError:
      description: Service Unavailable Error
      value:
        error:
          name: service_unavailable
          message: Service Unavailable