Nestcoin Ledger Accounts API

openapi: 3.2.0
info:
  version: 3.0.2
  title: Onboard External API Gateway Ledger Accounts API
  description: '**Introduction**

    API Gateway for Onboard


    This specification describes API endpoints that are available to the public internet via the API gateway.'
  contact:
    name: Nestcoin TechOps
    email: techops@nestcoin.com
  license:
    name: UNLICENSED
servers:
- url: https://external.dev.onboardpay.co
  description: Gateway for external API on staging environment.
tags:
- name: Ledger Accounts
paths:
  /ledger/accounts:
    x-original-path: /accounts
    get:
      summary: Fetch All Customer Account
      description: This operation allows the client to fetch all customer's accounts
      operationId: fetchCustomerAccounts
      x-visibility: external
      tags:
      - Ledger Accounts
      responses:
        '200':
          description: Account fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAccountList'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
  /ledger/accounts/{accountId}:
    x-original-path: /accounts/{accountId}
    get:
      summary: Fetch account details
      description: This operation allows the client to fetch account details by account id. A client can fetch only their own account details.
      operationId: getAccountDetails
      x-visibility: external
      tags:
      - Ledger Accounts
      parameters:
      - $ref: '#/components/parameters/LedgerSvcaccountId'
      responses:
        '200':
          description: Account details fetched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
  /ledger/currency/assets:
    x-original-path: /currency/assets
    get:
      summary: Get list of supported assets for main accounts
      description: 'This operation allows the client to get the Nestcoin supported

        Assets'
      operationId: getSupportedAssets
      x-visibility: external
      tags:
      - Ledger Accounts
      responses:
        '200':
          description: Assets Fetched Successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedAssetsList'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
  /ledger/assets/{assetCode}/network-tokens:
    x-original-path: /assets/{assetCode}/network-tokens
    get:
      summary: Get stablecoin tokens supported for account
      operationId: getAssetNetworkTokens
      parameters:
      - $ref: '#/components/parameters/LedgerSvcassetCode'
      description: 'Get list of stablecoin tokens supported for account by asset code.

        The asset code is the currency code of the main account e.g USD'
      x-visibility: external
      tags:
      - Ledger Accounts
      responses:
        '200':
          description: List of supported stablecoin tokens for the asset code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetBlockchainTokens'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
  /ledger/accounts/{accountId}/account-details:
    parameters:
    - $ref: '#/components/parameters/LedgerSvcaccountId'
    - $ref: '#/components/parameters/LedgerSvcaccountNumberCurrencyQuery'
    x-original-path: /accounts/{accountId}/account-details
    get:
      summary: Get the bank account number for an account
      description: 'Returns the bank account number (and bank details) generated for this account in the given

        currency, if one exists.'
      operationId: getAccountNumber
      x-visibility: external
      tags:
      - Ledger Accounts
      responses:
        '200':
          description: Bank account number details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashDepositPaymentDetails'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        '404':
          $ref: '#/components/responses/LedgerSvcNotFound'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
    post:
      summary: Create a bank account number for an account
      description: 'Generates a bank account number for this account in the given currency through the account-number

        provider. Returns the existing details if one was already generated.'
      operationId: createAccountNumber
      x-visibility: external
      tags:
      - Ledger Accounts
      responses:
        '201':
          description: Bank account number created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashDepositPaymentDetails'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
components:
  parameters:
    LedgerSvcassetCode:
      in: path
      name: assetCode
      description: The assets code of a crypto
      required: true
      schema:
        type: string
    LedgerSvcaccountId:
      in: path
      name: accountId
      description: the unique onboard account ID
      required: true
      schema:
        type: string
        format: uuid
    LedgerSvcaccountNumberCurrencyQuery:
      in: query
      name: currency
      description: Currency of the bank account number to generate or retrieve.
      required: false
      schema:
        type: string
        default: USD
        example: NGN
  schemas:
    LedgerSvcBlockchainNetwork:
      type: object
      description: Details of blockchain network
      required:
      - name
      - id
      - blockTime
      - confirmations
      - coinName
      - coinSymbol
      properties:
        id:
          type: string
          description: Simple identifier to identify the network
          example: ETH
        name:
          type: string
          description: Descriptive name for network
          example: Ethereum
        blockTime:
          type: integer
          format: int32
          description: Average time to generate new blocks in seconds.
          minimum: 1
          example: 15
        confirmations:
          type: number
          description: 'Minimum number of confirmations needed for a transaction to be confirmed.

            Total wait time for an asset can be computed as  blockTime * confirmations.

            '
          minimum: 1
          example: 8
        coinName:
          type: string
          example: Ether
          description: name of the network's native coin
        coinSymbol:
          type: string
          description: symbol of the network's native coin
          example: ETH
        supportsMemo:
          type: boolean
          description: Indicates if the network has memo support.
          default: 'false'
        alias:
          type: string
          description: The network alias
          example: BEP20
        addressExplorerUrl:
          type: string
          format: url
          example: https://etherscan.io/address
          description: 'Base URL path of an address on the blockchain explorer. Full URL can be obtained by appending the address to this.

            '
        txExplorerUrl:
          type: string
          format: url
          example: https://etherscan.io/tx
          description: 'Base URL Path of a transaction on the blockchain explorer. Full URL can be obtained by appending the TX hash to this URL.

            '
      x-source-svc: ledger
    AssetBlockchainTokens:
      type: object
      required:
      - asset
      - tokens
      properties:
        asset:
          type: string
          example: USD
        tokens:
          type: array
          description: A list of funding tokens with details of their supported networks.
          items:
            $ref: '#/components/schemas/TokenDetails'
      x-source-svc: ledger
    TokenDetails:
      type: object
      description: Details of supported funding token object.
      required:
      - symbol
      - name
      - logoUrl
      - supportedNetworks
      properties:
        symbol:
          type: string
          description: Token symbol
          example: USDC
        name:
          type: string
          description: Token name.
          example: USD Coin
        logoUrl:
          type: string
          example: https://etherscan.io/token/images/centre-usdc_28.png
          description: URL for token's logo.
        supportedNetworks:
          description: A list of networks on which the token is supported
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/TokenNetwork'
      x-source-svc: ledger
    SupportedAssetsList:
      type: object
      description: List of assets supported for main account.
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
      x-source-svc: ledger
    Account:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - customerName
      - balance
      - availableBalance
      - currency
      - createdDate
      properties:
        id:
          description: The customer account identifier
          type: string
          format: uuid
        name:
          description: The customer account name
          type: string
          example: ACME Corp
        customerName:
          description: The customer name associated to the details
          type: string
          example: Babajide Apata
        balance:
          description: The account balance on provider
          type: number
          example: '100.00'
          minimum: 0
        availableBalance:
          description: The available balance on provider
          type: number
          example: '100.00'
          minimum: 0
        currency:
          description: The account currency code
          type: string
          example: GBP
        createdDate:
          description: The date the customer was created
          type: string
          format: date-time
      x-source-svc: ledger
    TokenNetwork:
      type: object
      required:
      - code
      - networkInfo
      - decimals
      - contractAddress
      - minimumDeposit
      properties:
        code:
          type: string
          description: 'human-readable identifier for the token on this network. Usually a combination of network code and asset symbol

            '
          example: ETH_USDC
        decimals:
          type: integer
          format: int32
          example: 6
          minimum: 0
          description: The number of decimals used by this token on this network.
        contractAddress:
          type: string
          description: Contract address of the token on the given network.
          example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
        minimumDeposit:
          type: number
          description: Minimum amount allowed for deposits.
          example: 5.25
        depositAvailable:
          type: boolean
          description: Indicates if deposits are currently available. Address request will fail if this is false.
          default: true
        withdrawalAvailable:
          type: boolean
          description: Indicates if withdrawals are currently available. Withdrawal request will fail if this is false.
          default: true
        withdrawalFee:
          type: number
          minimum: 0
          example: '100.01'
          description: Transaction value. Must be positive.
        networkInfo:
          $ref: '#/components/schemas/LedgerSvcBlockchainNetwork'
      x-source-svc: ledger
    CashDepositPaymentDetails:
      type: object
      description: 'Destination account details the customer must pay into to fund the deposit. Mirrors a Beneficiary

        (without an id). Carries only the account details needed to make the payment; transaction context

        (amount, status, etc.) lives on the enclosing CashDepositTransaction.

        '
      required:
      - details
      - payinCurrency
      properties:
        details:
          $ref: '#/components/schemas/CashAccountDetails'
        payinCurrency:
          type: string
          description: Currency the destination account accepts for the deposit.
          example: NGN
      x-source-svc: ledger
    CustomerAccountList:
      type: object
      additionalProperties: false
      properties:
        content:
          type: array
          uniqueItems: true
          description: List of accounts
          items:
            $ref: '#/components/schemas/Account'
      x-source-svc: ledger
    Asset:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 3
          description: The asset code/symbol for this asset.
          example: USD
        name:
          type: string
          description: Name of this asset.
          example: US Dollars
        decimals:
          type: integer
          description: Number of decimal places supported by this asset.
          example: 2
        symbol:
          type: string
          description: asset symbol
        supportsBlockchainTransfer:
          type: boolean
          description: Indicates if this asset supports blockchain operations like crypto transfers.
          default: false
      x-source-svc: ledger
    ErrorMessageDto:
      description: Default error object for services. This gives consistent error object that all services may use.
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code
          example: UNKNOWN_ERROR
        message:
          type: string
          description: Descriptive error message
          example: Request could not be completed due to an error
        data:
          type: object
          description: Additional data for this error message.
          additionalProperties: true
          properties: {}
      x-common-model: ErrorMessageDto
    CashAccountDetails:
      type: object
      required:
      - accountInfoType
      - accountName
      - accountNumber
      properties:
        accountInfoType:
          type: string
          pattern: ^Cash(LocalBank|SepaBank|ACHBank|SwiftBank|MobileWallet|MultiRailBank)Account$
          description: 'Used to determine the exact schema type.

            Allowed values:

            - CashLocalBankAccount

            - CashSepaBankAccount

            - CashACHBankAccount

            - CashSwiftBankAccount

            - CashMobileWalletAccount

            - CashMultiRailBankAccount

            '
        accountName:
          type: string
          description: Name on the destination account.
          example: John Doe
        accountNumber:
          type: string
          description: 'The destination account identifier. For mobile money this is the phone number, for P2P wallet the account ID.

            Where routing number or sort code is present, this would be `{routingNumber}-{accountNumber}`.

            '
          example: '230101010'
        reference:
          type: string
          description: 'Reference the customer must include with the deposit so the pay-in is auto-matched.

            Optional — some providers do not require one.

            '
          example: PROV123456
      discriminator:
        propertyName: accountInfoType
        mapping:
          CashLocalBankAccount: '#/components/schemas/CashLocalBankAccount'
          CashSepaBankAccount: '#/components/schemas/CashSepaBankAccount'
          CashACHBankAccount: '#/components/schemas/CashACHBankAccount'
          CashSwiftBankAccount: '#/components/schemas/CashSwiftBankAccount'
          CashMobileWalletAccount: '#/components/schemas/CashMobileWalletAccount'
          CashMultiRailBankAccount: '#/components/schemas/CashMultiRailBankAccount'
      x-source-svc: ledger
  responses:
    LedgerSvcUnauthorized:
      description: Client is not authorized to make request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: UNAUTHORIZED
            message: Either client security header is missing or it is not valid.
    LedgerSvcNotFound:
      description: Entity was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: NOT_FOUND
            message: Information could not be found
    LedgerSvcAccessDenied:
      description: Expected permission is not available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: ACCESS_DENIED
            message: Expected permission or scope is not present.
    LedgerSvcServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: INTERNAL_ERROR
            message: An internal server error occurred.
    LedgerSvcInvalidRequest:
      description: Request could not be validated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: BAD_REQUEST
            message: Request could not be validated.
  securitySchemes:
    authSignature:
      type: apiKey
      name: x-signature
      in: header
    authToken:
      type: apiKey
      name: x-auth-token
      in: header
      description: Auth Token header for inter-service communication
x-organization: onboard
x-service-id: external-gateway
x-preserve-refs:
- '#/components/schemas/IntegrationProduct'
- '#/components/schemas/AdAppliedEscrowBalanceDto'
- '#/components/schemas/P2PWalletRecipient'
- '#/components/schemas/BankAccountRecipient'
- '#/components/schemas/MobileMoneyRecipient'
- '#/components/schemas/OrderEvent'
- '#/components/schemas/PaymentMethodEventAction'
- '#/components/schemas/PaymentMethodEventPayload'
- '#/components/schemas/TransactionServiceErrorCode'
- '#/components/schemas/ErrorCodes'