Nestcoin Ledger Transfer API

openapi: 3.2.0
info:
  version: 3.0.2
  title: Onboard External API Gateway Ledger Transfer 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-transfer
paths:
  /ledger/internal-transfers:
    x-original-path: /internal-transfers
    post:
      summary: Create internal transfer
      description: This operation allows the client to create an internal transfer between subaccounts and main account.
      operationId: createInternalTransfer
      x-visibility: external
      tags:
      - ledger-transfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternalTransferRequest'
      responses:
        '201':
          description: Internal transfer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalTransfer'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
  /ledger/internal-transfers/{referenceId}:
    x-original-path: /internal-transfers/{referenceId}
    get:
      summary: Get internal transfer by reference
      description: This operation allows the client to fetch an internal transfer by its reference ID.
      operationId: getInternalTransferByReference
      x-visibility: external
      tags:
      - ledger-transfer
      parameters:
      - $ref: '#/components/parameters/LedgerSvcreferenceId'
      responses:
        '200':
          description: Internal transfer fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalTransfer'
        '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/crypto-transfer:
    x-original-path: /crypto-transfer
    post:
      summary: Performs crypto transfer
      description: 'This operations allow the client to perform crypto transfer to n external wallet.


        N.B. The amount field is the amount after fees + fees, i.e the total amount, also send the fee in the fee field.'
      operationId: cryptoTransfer
      x-visibility: external
      tags:
      - ledger-transfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CryptoTransferRequest'
      responses:
        '201':
          description: Request received, do 2FA
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferResponse'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '403':
          $ref: '#/components/responses/LedgerSvcAccessDenied'
        default:
          $ref: '#/components/responses/LedgerSvcServerError'
      security:
      - authToken: []
  /ledger/crypto-transfer/{transferReference}:
    x-original-path: /crypto-transfer/{transferReference}
    get:
      summary: Get crypto transfer by reference
      description: This operation allows the client to fetch a specific crypto transfer by its reference ID.
      operationId: getCryptoTransferByReference
      x-visibility: external
      tags:
      - ledger-transfer
      parameters:
      - $ref: '#/components/parameters/LedgerSvctransferReference'
      responses:
        '200':
          description: Crypto Transfer fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTransaction'
        '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: []
components:
  schemas:
    TransactionType:
      type: string
      enum:
      - DEPOSIT
      - WITHDRAWAL
      - TRANSFER
      x-source-svc: ledger
    InternalTransfer:
      type: object
      additionalProperties: false
      required:
      - reference
      - sourceAccountId
      - destinationAccountId
      - amount
      - currency
      - status
      - createdDate
      properties:
        reference:
          type: string
          description: Transfer reference
          example: ITR123456
        sourceAccountId:
          type: string
          format: uuid
          description: Source account ID
        sourceAccountRef:
          type: string
          description: The transaction reference on the source account.
        destinationAccountId:
          type: string
          format: uuid
          description: Destination account ID
        destinationAccountRef:
          type: string
          description: The transaction reference on the destination account.
        amount:
          type: number
          description: Transfer amount
          example: 100
        currency:
          type: string
          description: Transfer currency
          example: USD
        status:
          $ref: '#/components/schemas/TransactionStatus'
        createdDate:
          type: string
          format: date-time
          description: Transfer creation date
        description:
          type: string
          description: Transfer description
      x-source-svc: ledger
    CryptoTransferRequest:
      description: 'Request object for crypto payment initiation request. The sourceAccountId can be a main account or sub-account.

        '
      type: object
      additionalProperties: false
      required:
      - sourceAccountId
      - amount
      - destination
      properties:
        sourceAccountId:
          type: string
          format: uuid
          description: The source account ID from which funds will be debited. This can be a main account or sub-account.
        amount:
          type: number
          example: '100.00'
          minimum: 0
          description: Transaction amount, specified in the source account's currency.
        narration:
          type: string
          description: Notes
        destination:
          $ref: '#/components/schemas/CryptoTransferDestination'
      x-source-svc: ledger
    AccountTransaction:
      type: object
      additionalProperties: false
      required:
      - id
      - reference
      - type
      - amount
      - currency
      - status
      - createdDate
      properties:
        id:
          type: string
          description: Unique transaction ID
          example: txn_123456
        reference:
          type: string
          description: Unique transaction reference.
          example: REF123456
        type:
          $ref: '#/components/schemas/TransactionType'
        amount:
          type: number
          description: Transaction amount, negative for debits, positive for credits
          example: 100
        currency:
          type: string
          description: Transaction currency
          example: USD
        status:
          $ref: '#/components/schemas/TransactionStatus'
        categoryTag:
          type: string
          description: Category tag for the transaction
          example: crypto-withdrawal
        createdDate:
          type: string
          format: date-time
          description: Transaction creation date
        notes:
          type: string
          description: Transaction description
          example: Conversion from USDC to IDR
        accountId:
          type: string
          format: uuid
          description: Associated account ID
        feeAmount:
          type: number
          description: Fee amount associated with the transaction
          example: 1
        feeInclusive:
          type: boolean
          description: Indicates if the fee is inclusive in the transaction amount
        subAccountId:
          type: string
          format: uuid
          description: Associated sub-account ID, if applicable
        blockchainInfo:
          $ref: '#/components/schemas/TransactionBlockchainInfo'
      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
    CryptoTransferDestination:
      type: object
      additionalProperties: false
      description: The destination details of the transfer. Either beneficiaryId or address must be provided.
      required:
      - tokenNetworkCode
      properties:
        tokenNetworkCode:
          type: string
          description: The token network code for the transfer
          example: BUSD_BSC
        beneficiaryId:
          type: string
          format: uuid
          description: The ID of the saved crypto beneficiary to which the transfer will be made.
        address:
          type: string
          example: '0x7BCc5bCBa19DE3C903F062D8fB5fF8d9f818173E'
        memo:
          type: string
          example: '405070'
          description: Optional, for networks that require memo.
      x-source-svc: ledger
    TransactionBlockchainInfo:
      type: object
      description: Blockchain transaction data, present on Crypto-backed transactions.
      required:
      - txHash
      - recipient
      - value
      - tokenSymbol
      properties:
        txHash:
          type: string
          description: Blockchain Transaction Hash
          example: '0x093a0b443d5f698d1097368c1c05fab1ee2304e508b36c08bb72c40389c17584'
        recipient:
          $ref: '#/components/schemas/TransactionBlockchainAddress'
        senderAddress:
          type: string
          description: The address of the sender.
          example: '0x2b059a574a35e60b228d10d54fec2671de4928e1'
        value:
          type: number
          example: '100.01'
          minimum: 0
          description: Quantity of tokens transferred in the transaction.
          default: '0.0'
        blockNumber:
          type: integer
          format: int64
          example: 20564802
        tokenSymbol:
          example: USDT
          description: Token symbol
          type: string
        timestamp:
          type: integer
          format: int64
          description: Transaction block timestamp.
        explorerUrl:
          type: string
          format: url
          description: URL to view the transaction on a blockchain explorer.
      x-source-svc: ledger
    User2FAMethod:
      type: string
      enum:
      - AUTHENTICATOR_APP
      - EMAIL
      - SMS
      x-source-svc: ledger
    TransferResponse:
      type: object
      additionalProperties: false
      description: The payment initiation response
      required:
      - id
      - status
      - awaiting2fA
      properties:
        id:
          type: string
          example: P12005E1DV
        status:
          $ref: '#/components/schemas/TransactionStatus'
        awaiting2fA:
          type: boolean
          default: false
          description: Indicates if transfer is awaiting 2FA confirmation. This applies mostly to transaction initiated via dashboard
        twoFaMethod:
          type: array
          description: List of 2fa enabled
          items:
            $ref: '#/components/schemas/User2FAMethod'
      x-source-svc: ledger
    InternalTransferRequest:
      type: object
      additionalProperties: false
      description: 'Internal request to transfer funds between two sub-accounts of between main account and sub-account.

        The accounts must have the same currency.

        '
      required:
      - sourceAccountId
      - destinationAccountId
      - amount
      properties:
        sourceAccountId:
          type: string
          format: uuid
          description: Source account ID, could be the main account or another sub-account
        destinationAccountId:
          type: string
          format: uuid
          description: Destination account ID, could be the main account or another sub-account
        reference:
          type: string
          description: Alpha-numeric transfer reference
          example: ITR123456
          pattern: ^[a-zA-Z0-9_-]{8,32}$
          minLength: 8
          maxLength: 32
        amount:
          type: number
          description: Transfer amount
          example: 100
          exclusiveMinimum: 0
        notes:
          type: string
          description: Transfer description
      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
    TransactionBlockchainAddress:
      type: object
      description: Address data
      required:
      - address
      properties:
        address:
          type: string
          description: Blockchain address where deposit was received.
          example: '0x2b059a574a35e60b228d10d54fec2671de4928e1'
        memo:
          type: string
          description: Memo for blockchains where memo is required.
          example: '1290122112'
      x-source-svc: ledger
  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.
  parameters:
    LedgerSvcreferenceId:
      in: path
      name: referenceId
      description: The transaction or transfer reference ID
      required: true
      schema:
        type: string
    LedgerSvctransferReference:
      in: path
      name: transferReference
      description: The transfer unique ID
      required: true
      schema:
        type: string
  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'