Nestcoin ledger-offramp accounts API

openapi: 3.0.3
info:
  version: 3.0.2
  title: Onboard External API Gateway auth-oauth ledger-offramp accounts API
  description: "**Introduction**\nAPI Gateway for Onboard\n\nThis specification describes API endpoints that are available to the public internet via the API gateway. The different endpoints require different authentication schemes, see documentation for what applies to the operation you want to access.\n\n**Errors**\nUses conventional HTTP response codes to indicate success or failure. In\ngeneral:\n \n- `2xx` status codes indicate success. Codes in the\n- `4xx` range\nindicate a client error (e.g. required parameters, failed request etc.).\n- `5xx` status codes indicate a server error occurred."
  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-offramp accounts
paths:
  /ledger/offramp-accounts:
    x-original-path: /offramp-accounts
    get:
      summary: Get a list of offramp accounts
      description: Get a list of offramp accounts, with pagination and payout currency
      operationId: getOfframpAccounts
      x-visibility: external
      tags:
      - ledger-offramp accounts
      parameters:
      - name: payoutCurrency
        in: query
        required: false
        description: Filter by payout currency
        schema:
          type: string
          example: IDR
      - $ref: '#/components/parameters/LedgerSvcpage'
      - $ref: '#/components/parameters/LedgerSvcsize'
      responses:
        '200':
          description: List of offramp accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfframpAccountList'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
      - authToken: []
    post:
      summary: Create offramp account
      description: Create offramp account with beneficiary id.
      operationId: createOfframpAccount
      x-visibility: external
      tags:
      - ledger-offramp accounts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOfframpAccountRequest'
      responses:
        '200':
          description: Offramp account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfframpAccount'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
      - authToken: []
  /ledger/offramp-accounts/{offrampAccountId}:
    x-original-path: /offramp-accounts/{offrampAccountId}
    get:
      summary: Get offramp account
      description: Get offramp account by offrampAccountId
      operationId: getOfframpAccount
      x-visibility: external
      tags:
      - ledger-offramp accounts
      parameters:
      - name: offrampAccountId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Offramp account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfframpAccount'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '404':
          $ref: '#/components/responses/LedgerSvcNotFound'
      security:
      - authToken: []
    delete:
      summary: Delete offramp account
      description: Delete offramp account and automatically disable address assigned.
      operationId: deleteOfframpAccount
      x-visibility: external
      tags:
      - ledger-offramp accounts
      parameters:
      - name: offrampAccountId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Offramp account deleted
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '404':
          $ref: '#/components/responses/LedgerSvcNotFound'
      security:
      - authToken: []
  /ledger/offramp-accounts/{id}/funding-address:
    x-original-path: /offramp-accounts/{id}/funding-address
    get:
      summary: Get address for offramp account
      description: Get address for offramp account, response should include the list of TokenAssetNetwork supported for the address.
      operationId: getOfframpAccountFundingAddress
      x-visibility: external
      tags:
      - ledger-offramp accounts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: network
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Offramp account funding address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfframpAccountFundingAddress'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '404':
          $ref: '#/components/responses/LedgerSvcNotFound'
      security:
      - authToken: []
  /ledger/offramp-accounts/{id}/transactions:
    x-original-path: /offramp-accounts/{id}/transactions
    get:
      summary: Get transactions for offramp account
      description: Get a paginated list of transactions proccessed by offramp accounts
      operationId: getOfframpAccountTransactions
      x-visibility: external
      tags:
      - ledger-offramp accounts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/LedgerSvcpage'
      - $ref: '#/components/parameters/LedgerSvcsize'
      responses:
        '200':
          description: List of transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfframpAccountTransactionList'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '404':
          $ref: '#/components/responses/LedgerSvcNotFound'
      security:
      - authToken: []
components:
  schemas:
    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
    OfframpAccountList:
      allOf:
      - $ref: '#/components/schemas/Paging'
      - type: object
        required:
        - content
        properties:
          content:
            type: array
            items:
              $ref: '#/components/schemas/OfframpAccount'
      x-source-svc: ledger
    OfframpAccountTransaction:
      allOf:
      - $ref: '#/components/schemas/CashPaymentTransaction'
      - type: object
        description: Details of an offramp account transaction.
        properties:
          offrampAccountId:
            type: string
            format: uuid
            description: Identifier of the offramp account associated with this transaction.
          blockchainInfo:
            $ref: '#/components/schemas/TransactionBlockchainInfo'
      x-source-svc: ledger
    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
    OfframpAccount:
      type: object
      required:
      - id
      - beneficiary
      - payoutCurrency
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the offramp account.
        beneficiary:
          $ref: '#/components/schemas/Beneficiary'
        payoutCurrency:
          type: string
          example: KES
        status:
          $ref: '#/components/schemas/OfframpAccountStatus'
        createdDate:
          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
    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
    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
    CreateOfframpAccountRequest:
      type: object
      required:
      - beneficiaryId
      - payoutCurrency
      properties:
        payoutCurrency:
          type: string
          description: Currency in which payouts will be made to the beneficiary.
          example: KES
        beneficiaryId:
          type: string
          format: uuid
          description: "Identifier of an existing beneficiary to be linked to the offramp account. \nShould be in the same currency as payoutCurrency.\n"
      x-source-svc: ledger
    OfframpAccountStatus:
      type: string
      description: Status of the offramp account.
      enum:
      - ACTIVE
      - INACTIVE
      - SUSPENDED
      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
    Beneficiary:
      type: object
      additionalProperties: false
      description: Fiat beneficiary object
      discriminator:
        propertyName: beneficiaryType
        mapping:
          BeneficiaryLocalBankAccount: '#/components/schemas/BeneficiaryLocalBankAccount'
          BeneficiarySepaBankAccount: '#/components/schemas/BeneficiarySepaBankAccount'
          BeneficiaryACHBankAccount: '#/components/schemas/BeneficiaryACHBankAccount'
          BeneficiarySwiftBankAccount: '#/components/schemas/BeneficiarySwiftBankAccount'
          BeneficiaryMobileWalletAccount: '#/components/schemas/BeneficiaryMobileWalletAccount'
      required:
      - id
      - accountNumber
      - accountName
      - currency
      - accountHolderType
      properties:
        id:
          description: Beneficiary identifier
          type: string
          format: uuid
        accountNumber:
          description: Beneficiary account number, for international payments like SEPA, this is the IBAN
          type: string
        accountName:
          description: Beneficiary account name
          type: string
        currency:
          type: string
        beneficiaryType:
          type: string
          description: 'Discriminator value for beneficiary type. Allowed values include:

            - BeneficiaryLocalBankAccount

            - BeneficiarySepaBankAccount

            - BeneficiaryACHBankAccount

            - BeneficiarySwiftBankAccount

            - BeneficiaryMobileWalletAccount

            '
        isThirdParty:
          type: boolean
          description: Flag to indicate if the beneficiary is a third party
          default: false
        accountHolderType:
          $ref: '#/components/schemas/AccountHolderType'
      x-source-svc: ledger
    OfframpAccountTransactionList:
      allOf:
      - $ref: '#/components/schemas/Paging'
      - type: object
        required:
        - content
        properties:
          content:
            type: array
            description: List of offramp account transactions
            items:
              $ref: '#/components/schemas/OfframpAccountTransaction'
      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
    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
    CashPaymentTransaction:
      type: object
      description: Details of a cash payment transaction.
      required:
      - id
      - reference
      - currency
      - status
      - payoutCurrency
      - amount
      - rate
      - payoutAmount
      - createdDate
      - recipient
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: string
          description: Reference for the cash payment transaction at initiation.
        accountTransactionId:
          type: string
          description: Identifier of the transaction on the account.
        currency:
          type: string
          description: Currency in which the account was debited.
          example: USD
        status:
          $ref: '#/components/schemas/TransactionStatus'
        payoutCurrency:
          type: string
          description: Currency in which the beneficiary will be paid out.
          example: NGN
        amount:
          type: number
          description: Amount transferred.
          example: 100
        rate:
          type: number
          description: Exchange rate applied for this transfer.
          example: 1450.75
        payoutAmount:
          type: number
          description: Amount paid out to the beneficiary in payout currency.
          example: 145075
        providerReference:
          type: string
          description: Reference provided by the cash payment provider.
          example: PROV123456
        recipient:
          $ref: '#/components/schemas/BasicBeneficiaryInfo'
        createdDate:
          type: string
          format: date-time
      x-source-svc: ledger
    AccountHolderType:
      type: string
      enum:
      - INDIVIDUAL
      - BUSINESS
      x-source-svc: ledger
    OfframpAccountFundingAddress:
      type: object
      required:
      - address
      - network
      - supportedTokens
      properties:
        address:
          type: string
          description: The deposit address for the offramp account.
          example: '0x43e4715ae093a4c86b5ecddb52216c4f879e9672'
        memo:
          type: string
          description: Memo for networks that support memo.
        network:
          $ref: '#/components/schemas/LedgerSvcBlockchainNetwork'
        supportedTokens:
          type: array
          items:
            $ref: '#/components/schemas/TokenDetails'
      x-source-svc: ledger
    BasicBeneficiaryInfo:
      type: object
      description: Basic information about a beneficiary as at the time of transaction.
      required:
      - id
      - accountName
      - beneficiaryType
      - accountIdentifier
      - paymentChannelId
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the beneficiary.
        accountName:
          type: string
          description: Name on the account
          example: John Doe
        beneficiaryType:
          type: string
          description: Type of beneficiary object.
          example: BeneficiaryLocalBankAccount
        bankName:
          type: string
          description: 'Name of the receiving bank, for mobile money this would be the network, and for P2P wallet it will be the name of the account provider

            '
          example: Great Bank LLC
        accountIdentifier:
          type: string
          description: 'The account identifier at the bank. For mobile money, this is the phone number on account, for P2P wallet, this is the account ID

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

            '
          example: '230101010'
        paymentChannelId:
          type: string
          description: Identifier of the payment channel used for this transaction, if available. This can be used to determine the exact payment method used for the transaction.
          example: BANK_TRANSFER_NIGERIA
        country:
          type: string
          description: Country where the payment method belongs if available
          example: IE
      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.
    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.
    LedgerSvcNotFound:
      description: Entity was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: NOT_FOUND
            message: Information could not be found
  parameters:
    LedgerSvcpage:
      in: query
      name: page
      required: false
      description: Page parameter, starting from 1
      schema:
        type: integer
        minimum: 1
        default: 1
    LedgerSvcsize:
      in: query
      name: size
      required: false
      schema:
        type: integer
        maximum: 100
        minimum: 1
        default: 20
  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'