Nestcoin ledger-account activity API

openapi: 3.2.0
info:
  version: 3.0.2
  title: Onboard External API Gateway ledger-account activity 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-account activity
paths:
  /ledger/accounts/{accountId}/activities:
    x-original-path: /accounts/{accountId}/activities
    get:
      summary: Get account transaction activities
      description: 'This operation allows the client to fetch a paginated, aggregated feed of all

        transaction activity for an account (cash deposits/payments, account-number

        deposits, crypto deposits/withdrawals, internal transfers, offramp deposits),

        each with type-specific details in activityData.'
      operationId: getAccountActivities
      x-visibility: external
      tags:
      - ledger-account activity
      parameters:
      - $ref: '#/components/parameters/LedgerSvcaccountId'
      - name: type
        in: query
        description: Filter by activity type
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TransactionActivityType'
      - name: direction
        in: query
        description: Filter by activity direction
        required: false
        schema:
          $ref: '#/components/schemas/ActivityDirection'
      - name: startDate
        in: query
        description: Filter activities occurring on or after this date-time
        required: false
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        description: Filter activities occurring on or before this date-time
        required: false
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/LedgerSvcpage'
      - $ref: '#/components/parameters/LedgerSvcsize'
      responses:
        '200':
          description: Activities fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionActivityList'
        '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}/activities/{activityId}:
    x-original-path: /accounts/{accountId}/activities/{activityId}
    get:
      summary: Get a single transaction activity
      description: This operation allows the client to fetch a specific transaction activity by its ID.
      operationId: getAccountActivityById
      x-visibility: external
      tags:
      - ledger-account activity
      parameters:
      - $ref: '#/components/parameters/LedgerSvcaccountId'
      - $ref: '#/components/parameters/LedgerSvcactivityId'
      responses:
        '200':
          description: Activity fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionActivity'
        '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: []
  /ledger/subaccounts/{subAccountIdRef}/activities:
    x-original-path: /subaccounts/{subAccountIdRef}/activities
    get:
      summary: Get sub-account transaction activities
      description: 'This operation allows the client to fetch a paginated, aggregated feed of all

        transaction activities for a sub-account (cash deposits/payments, account-number

        deposits, crypto deposits/withdrawals, internal transfers, offramp deposits),

        each with type-specific details in activityData.'
      operationId: getSubAccountActivities
      x-visibility: external
      tags:
      - ledger-account activity
      parameters:
      - $ref: '#/components/parameters/LedgerSvcsubAccountIdOrRef'
      - name: type
        in: query
        description: Filter by activity type
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TransactionActivityType'
      - name: direction
        in: query
        description: Filter by activity direction
        required: false
        schema:
          $ref: '#/components/schemas/ActivityDirection'
      - name: startDate
        in: query
        description: Filter activities occurring on or after this date-time
        required: false
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        description: Filter activities occurring on or before this date-time
        required: false
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/LedgerSvcpage'
      - $ref: '#/components/parameters/LedgerSvcsize'
      responses:
        '200':
          description: Activities fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionActivityList'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
  /ledger/subaccounts/{subAccountIdRef}/activities/{activityId}:
    x-original-path: /subaccounts/{subAccountIdRef}/activities/{activityId}
    get:
      summary: Get a single sub-account transaction activity
      description: This operation allows the client to fetch a specific transaction activity by its ID.
      operationId: getSubAccountActivityById
      x-visibility: external
      tags:
      - ledger-account activity
      parameters:
      - $ref: '#/components/parameters/LedgerSvcsubAccountIdOrRef'
      - $ref: '#/components/parameters/LedgerSvcactivityId'
      responses:
        '200':
          description: Activity fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionActivity'
        '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: []
  /ledger/transaction-activities:
    x-original-path: /transaction-activities
    get:
      summary: Get transaction activities across the business
      description: 'This operation allows the client to fetch a paginated, aggregated feed of all

        transaction activity for the authenticated business, optionally scoped to a

        single account, with the same type-specific activityData as the account-scoped

        activities endpoint.'
      operationId: getTransactionActivities
      x-visibility: external
      tags:
      - ledger-account activity
      parameters:
      - $ref: '#/components/parameters/LedgerSvcanyAccountIdQuery'
      - name: type
        in: query
        description: Filter by activity type
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TransactionActivityType'
      - name: direction
        in: query
        description: Filter by activity direction
        required: false
        schema:
          $ref: '#/components/schemas/ActivityDirection'
      - name: startDate
        in: query
        description: Filter activities occurring on or after this date-time
        required: false
        schema:
          type: string
          format: date-time
      - name: endDate
        in: query
        description: Filter activities occurring on or before this date-time
        required: false
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/LedgerSvcpage'
      - $ref: '#/components/parameters/LedgerSvcsize'
      responses:
        '200':
          description: Activities fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionActivityList'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
components:
  schemas:
    ActivityDirection:
      type: string
      enum:
      - CREDIT
      - DEBIT
      x-source-svc: ledger
    TransactionStatus:
      type: string
      description: 'Status of the transaction, indicating its current state in the processing lifecycle.

        - PENDING: The transaction has been created but not yet processed.

        - IN_PROGRESS: The transaction is currently being processed.

        - FAILED: The transaction processing has failed.

        - SUCCESS: The transaction has been successfully processed.

        '
      enum:
      - PENDING
      - IN_PROGRESS
      - FAILED
      - SUCCESS
      x-source-svc: ledger
    TransactionActivityType:
      type: string
      description: Semantic category of a transaction activity feed entry.
      enum:
      - CASH_DEPOSIT
      - CASH_PAYMENT
      - ACCOUNT_NUMBER_DEPOSIT
      - CRYPTO_WITHDRAWAL
      - CRYPTO_DEPOSIT
      - INTERNAL_TRANSFER
      - OFFRAMP_DEPOSIT
      x-source-svc: ledger
    TransactionActivity:
      type: object
      description: 'A single entry in the aggregated account activity feed. The concrete subtype is

        determined by the activityType discriminator; the type field carries the

        semantic category for filtering and display.

        '
      discriminator:
        propertyName: activityType
        mapping:
          CashDepositActivity: '#/components/schemas/CashDepositActivity'
          CashPaymentActivity: '#/components/schemas/CashPaymentActivity'
          AccountNumberDepositActivity: '#/components/schemas/AccountNumberDepositActivity'
          CryptoWithdrawalActivity: '#/components/schemas/CryptoWithdrawalActivity'
          CryptoDepositActivity: '#/components/schemas/CryptoDepositActivity'
          InternalTransferActivity: '#/components/schemas/InternalTransferActivity'
          OfframpDepositActivity: '#/components/schemas/OfframpDepositActivity'
      required:
      - id
      - activityType
      - type
      - direction
      - amount
      - currency
      - status
      - activityAt
      - accountId
      - accountType
      properties:
        id:
          type: string
          format: uuid
        activityType:
          type: string
          description: 'Discriminator; the concrete activity model name, e.g. CashDepositActivity.

            '
        type:
          $ref: '#/components/schemas/TransactionActivityType'
        direction:
          $ref: '#/components/schemas/ActivityDirection'
        amount:
          type: number
          description: Always positive; see direction for credit/debit.
          example: 100
        currency:
          type: string
          example: USD
        status:
          $ref: '#/components/schemas/TransactionStatus'
        reference:
          type: string
          description: Customer-facing reference of the source transaction.
        accountId:
          type: string
          format: uuid
        accountType:
          $ref: '#/components/schemas/ActivityAccountType'
        subAccountId:
          type: string
          format: uuid
          description: Set when accountType is SUB_ACCOUNT.
        accountTransactionId:
          type: string
          description: Identifier of the transaction on the ledger account, when available.
        groupId:
          type: string
          format: uuid
          description: 'Links related activities together, e.g. the two legs of an internal

            transfer, or an offramp deposit and its refund.

            '
        narration:
          type: string
        activityAt:
          type: string
          format: date-time
      x-source-svc: ledger
    Paging:
      description: Base object for paginated list
      type: object
      properties:
        name:
          type: string
          description: Descriptive name for the list
        size:
          minimum: 0
          type: integer
          format: int32
          description: Positive integer
        totalItems:
          minimum: 0
          type: integer
          format: int32
          description: Positive integer
        nextPage:
          minimum: 0
          type: integer
          format: int32
          description: Positive integer
        previousPage:
          minimum: 0
          type: integer
          format: int32
          description: Positive integer
      discriminator:
        propertyName: name
      x-common-model: Paging
    TransactionActivityList:
      allOf:
      - $ref: '#/components/schemas/Paging'
      - type: object
        properties:
          content:
            type: array
            description: List of transaction activities
            items:
              $ref: '#/components/schemas/TransactionActivity'
      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
    ActivityAccountType:
      type: string
      description: The kind of account a transaction activity occurred on.
      enum:
      - MAIN
      - SUB_ACCOUNT
      - OFFRAMP_ACCOUNT
      x-source-svc: ledger
  parameters:
    LedgerSvcsubAccountIdOrRef:
      in: path
      name: subAccountIdRef
      description: 'The unique onboard sub-account ID or reference

        '
      required: true
      schema:
        type: string
    LedgerSvcpage:
      in: query
      name: page
      required: false
      description: Page parameter, starting from 1
      schema:
        type: integer
        minimum: 1
        default: 1
    LedgerSvcanyAccountIdQuery:
      name: accountId
      description: Any account ID (could be Main account, sub-account or offramp account)
      required: false
      in: query
      schema:
        type: string
        format: uuid
    LedgerSvcaccountId:
      in: path
      name: accountId
      description: the unique onboard account ID
      required: true
      schema:
        type: string
        format: uuid
    LedgerSvcactivityId:
      in: path
      name: activityId
      description: The unique transaction activity ID
      required: true
      schema:
        type: string
        format: uuid
    LedgerSvcsize:
      in: query
      name: size
      required: false
      schema:
        type: integer
        maximum: 100
        minimum: 1
        default: 20
  responses:
    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.
    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.
    LedgerSvcNotFound:
      description: Entity was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: NOT_FOUND
            message: Information could not be found
    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.
  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'