Nestcoin transactions-offramp API

openapi: 3.0.3
info:
  version: 3.0.2
  title: Onboard External API Gateway auth-oauth transactions-offramp 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: transactions-offramp
paths:
  /transactions/v2/offramp/initiate:
    x-original-path: /v2/offramp/initiate
    post:
      tags:
      - transactions-offramp
      summary: Initiate an offramp transaction
      operationId: initiateOfframpWithoutReservation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInitiateOrderRequestV2'
        required: false
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
      security:
      - authToken: []
      x-visibility: external
  /transactions/offramp/customer-approve:
    x-original-path: /offramp/customer-approve
    post:
      tags:
      - transactions-offramp
      summary: Customer approves withdrawal from wallet
      operationId: offrampCustomerApprove
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerActionRequest'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
      security:
      - authToken: []
      x-visibility: external
  /transactions/offramp/customer-confirm:
    x-original-path: /offramp/customer-confirm
    post:
      tags:
      - transactions-offramp
      summary: Customer acknowledges receipt of fiat
      operationId: offrampCustomerConfirm
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerConfirmationRequest'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
      security:
      - authToken: []
      x-visibility: external
  /transactions/offramp/customer-cancel:
    x-original-path: /offramp/customer-cancel
    post:
      tags:
      - transactions-offramp
      summary: Customer cancels pending offramp transaction
      operationId: offrampCustomerCancel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerActionRequest'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
      security:
      - authToken: []
      x-visibility: external
components:
  schemas:
    CustomerConfirmationRequest:
      required:
      - customerId
      - transactionId
      - verificationData
      type: object
      properties:
        customerId:
          type: string
          format: uuid
        transactionId:
          type: string
          format: uuid
        verificationData:
          $ref: '#/components/schemas/VerificationData'
      x-source-svc: transactions
    TransactionsSvcTransactionType:
      type: string
      description: Transaction order type, can be ONRAMP or OFFRAMP
      enum:
      - ONRAMP
      - OFFRAMP
      x-source-svc: transactions
    VerificationData:
      type: object
      properties:
        message:
          type: string
          example: Hello Onboard
        signature:
          type: string
          example: 1.4274191415664356e+156
        timestamp:
          type: integer
          example: 1655483046
        otp:
          type: string
          example: '1655483046'
        totp:
          type: string
          description: User totp from authenticator app
          example: 28404
      x-source-svc: transactions
    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
    TransactionsSvcWalletDTO:
      type: object
      properties:
        walletAddress:
          type: string
          example: 0
        networkId:
          type: string
          example: bsc_testnet
        walletName:
          type: string
          example: My Trust Wallet
      x-source-svc: transactions
    TransactionsSvcTradeMode:
      type: string
      enum:
      - P2P
      - IP
      - OTC
      x-source-svc: transactions
    CustomerActionRequest:
      allOf:
      - $ref: '#/components/schemas/CustomerActionFields'
      - type: object
        properties:
          txHash:
            type: string
            description: Deposit transaction hash for deposit related transaction
          permitSignature:
            type: string
            description: Permit data signature for permit related approval
          flag:
            type: string
          paymentReceiptUploadId:
            type: string
            description: Upload ID for receipt uploaded on storage bucket
      x-source-svc: transactions
    TransactionsSvcOfferDTO:
      required:
      - instantPayEnabled
      - networkId
      - partnerId
      - rate
      - token
      - tokenAmount
      - transactionType
      type: object
      properties:
        offerId:
          type: string
          format: uuid
        partnerId:
          type: string
          format: uuid
        transactionType:
          $ref: '#/components/schemas/TransactionsSvcTransactionType'
        rate:
          type: number
          example: 0.32
        networkId:
          type: string
          example: TRC20
        fiatSymbol:
          type: string
          example: NGN
        fiatAmount:
          type: number
          example: 120.5
        token:
          type: string
          example: USDT
        tokenAmount:
          type: number
          example: 120.5
        usdAmount:
          type: number
          example: 120.5
        partnerDisplayName:
          type: string
          example: John Doe
        adNote:
          type: string
          example: Guaranteed fast payment
        instantPayEnabled:
          type: boolean
        instantPayPaymentAccountId:
          type: string
        customPayinProvider:
          type: string
        tradeMode:
          $ref: '#/components/schemas/TransactionsSvcTradeMode'
      x-source-svc: transactions
    TransactionOrderStatus:
      type: string
      description: Order transaction status
      enum:
      - INITIATED
      - DEPOSITED
      - CONFIRMED
      - COMPLETED
      - PENDING
      - CANCELLED
      - IN_DISPUTE
      - AWAITING_ACCEPTANCE
      x-source-svc: transactions
    CustomerActionFields:
      required:
      - customerId
      - transactionId
      type: object
      properties:
        customerId:
          type: string
          format: uuid
        transactionId:
          type: string
          format: uuid
      x-source-svc: transactions
    TimeoutDTO:
      type: object
      properties:
        name:
          type: string
          enum:
          - APPROVE_TRANSACTION
          - MAKE_DEPOSIT
          - CONFIRM_DEPOSIT
          - FLAG_DISPUTE
          - ACKNOWLEDGE_TRANSACTION
        startTime:
          type: string
          format: date-time
          x-faker: date.recent
        duration:
          type: number
        timeLeft:
          type: integer
          format: int64
      x-source-svc: transactions
    TradeContext:
      type: string
      enum:
      - STANDARD_TRADE
      - INTERNAL_RAIL
      x-source-svc: transactions
    Fee:
      required:
      - asFiat
      - asToken
      type: object
      properties:
        asToken:
          type: string
          pattern: ([0-9]*[.])?[0-9]+
          example: '1000.0'
        asFiat:
          type: number
      x-source-svc: transactions
    CustomerInitiateOrderRequestV2:
      type: object
      properties:
        offerId:
          type: string
          description: id of offer to make unit reservation from
        offerToken:
          type: string
          description: Token used to access private ads.
        unitAmount:
          type: string
          description: unit to be reserved
        rate:
          type: number
          description: rate to make reservation at
        fiatAmount:
          type: number
          description: fiat equivalent of reserved unit
        tradeRequestBroadcastId:
          type: string
          format: uuid
        paymentMethodId:
          type: string
        paymentChannelId:
          type: string
        buyerPaymentMethodId:
          type: string
        customerWallet:
          $ref: '#/components/schemas/TransactionsSvcWalletDTO'
        apiKey:
          type: string
        thirdPartyOrderTradeId:
          type: string
        cexOrderId:
          type: string
      required:
      - offerId
      - unitAmount
      x-source-svc: transactions
    ThirdpartyOrderInfoDTO:
      required:
      - businessId
      properties:
        businessId:
          type: string
          description: The thirdparty business the customer is trading via
        tradeId:
          type: string
          description: Tracking trade Id
        product:
          type: string
          description: Product name, typically custodial or web
        blockchainOrderId:
          type: integer
        externalOrderReference:
          type: string
      x-source-svc: transactions
    TransactionDTO:
      required:
      - customerId
      - fee
      - id
      - reference
      - status
      type: object
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: string
          example: 0165359005113074501885
        customerId:
          type: string
          format: uuid
        customerName:
          type: string
          example: John Doe
        offer:
          $ref: '#/components/schemas/TransactionsSvcOfferDTO'
        escrowAddress:
          type: string
          description: Escrow address
          example: 1.2869144918162796e+48
        paymentChannelId:
          type: string
          example: BANK_TRANSFER_NIGERIA
        paymentMethod:
          type: object
          properties: {}
        buyerPaymentMethod:
          type: object
          properties: {}
        customerWallet:
          $ref: '#/components/schemas/TransactionsSvcWalletDTO'
        tokenAddress:
          type: string
          example: 0
        status:
          $ref: '#/components/schemas/TransactionOrderStatus'
        createdAt:
          type: string
          format: date-time
          x-faker: date.recent
        initiatedAt:
          type: string
          format: date-time
          x-faker: date.recent
        depositedAt:
          type: string
          format: date-time
          x-faker: date.recent
        confirmedAt:
          type: string
          format: date-time
          x-faker: date.recent
        completedAt:
          type: string
          format: date-time
          x-faker: date.recent
        cancelledAt:
          type: string
          format: date-time
          x-faker: date.recent
        cancellationReason:
          type: string
        disputeId:
          type: string
          default: 'null'
        timeout:
          $ref: '#/components/schemas/TimeoutDTO'
        lockHash:
          type: string
          default: 'null'
        confirmationHash:
          type: string
          default: 'null'
        cancellationHash:
          type: string
          default: 'null'
        isPartnerAcknowledged:
          type: boolean
          default: false
        defaultingParty:
          $ref: '#/components/schemas/UserType'
        rating:
          type: number
          example: 3
        isCexOrder:
          type: boolean
          example: false
        fee:
          $ref: '#/components/schemas/Fee'
        instantPayProcessingStatus:
          $ref: '#/components/schemas/InstantPayProcessingStatus'
        tradeValue:
          type: number
          description: Actual token amount that is to be traded
          deprecated: true
        merchantTokenValue:
          type: number
          description: Actual token value that is to be traded by merchant less any fees
        customerTokenValue:
          type: number
          description: Actual token value that is to be traded by customer less any fees
        payableAmount:
          type: number
          description: Actual fiat amount that is to be paid.
        thirdpartyOrderInfo:
          $ref: '#/components/schemas/ThirdpartyOrderInfoDTO'
        isNoKyc:
          type: boolean
          description: Flag showing if order is a no kyc order
        paymentReceiptUploadId:
          type: string
          description: Upload ID for receipt uploaded on storage bucket
          default: 'null'
        suppressCustomerNotifications:
          type: boolean
          description: Flag to indicate if notifications should be sent to the customer or not during the lifetime of this transaction
          default: false
        chatUnavailable:
          type: boolean
          description: Flag to indicate if chat is unavailable for this transaction
          default: false
        tradeContext:
          $ref: '#/components/schemas/TradeContext'
      x-source-svc: transactions
    InstantPayProcessingStatus:
      type: string
      enum:
      - PENDING_IP_REPORT
      - IN_PROGRESS
      - FAILURE
      - SUCCESS
      x-source-svc: transactions
    UserType:
      type: string
      description: Type of user/role of user in transaction
      enum:
      - CUSTOMER
      - PARTNER
      x-source-svc: transactions
  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'