openapi: 3.0.1
info:
  title: Bamboo Account Management NG Deposits API
  version: ''
  description: "Account creation enables users to invest on Bamboo. Ensure KYC has been completed and each user’s identity verified before creating a brokerage account.\n\n**Best Practice:** To avoid maintenance fees on inactive accounts, create and fund brokerage accounts **only when users initiate their first trade**. You may collect account details in advance but delay sending the request until they’re ready to buy.\n\n##### Prerequisites\n- **Minimum Age:** 18 years (verified via government-issued ID)\n- **Compliance:** Must meet local investment regulations\n\n##### Document Requirements\n<table>\n  <thead>\n    <tr>\n      <th>Country</th>\n      <th>Primary ID</th>\n      <th>Image Requirements</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <th>Nigeria</th>\n      <td>BVN</td>\n      <td>Passport photo</td>\n    </tr>\n    <tr>\n      <th>Ghana</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n    <tr>\n      <th>South Africa</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n  </tbody>\n</table>\n\n**Note:** Images must be in Base64 format. The `front_id_image` and `back_id_image` fields apply only to Ghana and South Africa.\n\n##### Phone Number Format\n- Must be in international format (e.g., +2347083864023)\n- Country code must match user’s residence\n- Used for notifications and account security\n"
servers:
- url: https://powered-by-bamboo-sandbox.investbamboo.com
tags:
- name: NG Deposits
paths:
  /api/lsx/ng/deposit:
    post:
      tags:
      - NG Deposits
      summary: Create Deposit
      description: "This endpoint is used to send the details needed to create a deposit request for your users. After verification is completed, \nthe user's position will be credited with the value requested. To get statuses about your deposit, head to the [NG Stocks Events](#tag/NG-Stock-Events) section.\n"
      parameters:
      - name: content-type
        in: header
        description: Acceptable content type
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      requestBody:
        description: NGX Deposit request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lsxngdeposit'
        required: true
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngdeposit_response'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '422':
          description: Incomplete Parameters
          content:
            application/json:
              example:
                message: NGX account is not active
              schema:
                $ref: '#/components/schemas/ErrorChangesetResponse'
  /api/lsx/ng/deposit/{reference}:
    get:
      tags:
      - NG Deposits
      summary: Fetch Deposits by Reference
      description: This is used to fetch a deposit by its specific transaction reference number.
      parameters:
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngdeposit_by_reference_response'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
components:
  schemas:
    lsxngdeposit_by_reference_response:
      title: Deposit request
      required:
      - amount
      - currency
      - dollar_amount
      - dollar_fee
      - exchange_rate
      - fee
      - provider
      - provider_txref
      - status
      type: object
      properties:
        amount:
          type: number
          description: Amount to be deposited
          example: 200000
        currency:
          type: string
          description: Currency
          example: NGN
        dollar_amount:
          type: number
          description: Dollar equivalent of amount to be deposited
          example: 230.41
        dollar_fee:
          type: number
          description: Dollar Fee
          example: 0.02
        exchange_rate:
          type: number
          description: Fee
          example: 868
        fee:
          type: number
          description: Fee
          example: 50
        provider:
          type: string
          description: API Consumer Name
          example: invest-bamboo
        provider_txref:
          type: string
          description: Deposit reference
          example: INVcal2VzeVGJkCXNx
        status:
          type: string
          description: Status
          example: Successful
    lsxngdeposit_response:
      title: Deposit response
      required:
      - amount
      - currency
      - dollar_amount
      - dollar_fee
      - exchange_rate
      - fee
      - provider
      - provider_txref
      - status
      type: object
      properties:
        amount:
          type: number
          description: Amount to be deposited
          example: 200000
        currency:
          type: string
          description: Currency
          example: NGN
        dollar_amount:
          type: number
          description: Dollar equivalent of amount to be deposited
          example: 230.41
        dollar_fee:
          type: number
          description: Dollar Fee
          example: 0.02
        exchange_rate:
          type: number
          description: Fee
          example: 868
        fee:
          type: number
          description: Fee
          example: 50
        provider:
          type: string
          description: API Consumer Name
          example: invest-bamboo
        provider_txref:
          type: string
          description: Deposit reference
          example: INVcal2VzeVGJkCXNx
        status:
          type: string
          description: Status
          example: Pending
    Unauthorized:
      title: Unauthorized response
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Unauthorized/Invalid Token/Token has expired
          example: Invalid client token supplied.
      description: Token is invalid or have expired
    ErrorChangesetResponse:
      title: Error changeset response
      required:
      - errors
      - message
      type: object
      properties:
        message:
          type: string
          description: Message why request didn't succeed
          example: Invalid credentials
        errors:
          type: object
          properties: {}
          description: Map of errors
      description: Error response for request which manipulates data
    lsxngdeposit:
      title: Deposit request
      required:
      - amount
      - currency
      - fee
      - provider_txref
      - provider
      type: object
      properties:
        provider_txref:
          type: string
          description: Deposit reference
          example: INVcal2VzeVGJkCXNx
        provider:
          type: string
          description: API Consumer Name
          example: invest-bamboo
        fee:
          type: number
          description: Fee
          example: 20
        currency:
          type: string
          description: Currency
          example: NGN
        amount:
          type: number
          description: Amount to be deposited
          example: 200000
x-logo:
  url: bamboo-logo.png
  altText: bamboo logo
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
  - Account Management
- name: Money Movement
  tags:
  - Overview
  - Deposits
  - Withdrawals
- name: US Brokerage Services
  tags:
  - Portfolio Reporting
  - US Securities
  - US Stock Trading
  - US Stock Events
- name: Utilities
  tags:
  - Dictionaries
  - Market Activity
  - Exchange Rate
  - Featured Themes
  - Financial Documents