Nestcoin ledger-cash deposits API

openapi: 3.2.0
info:
  version: 3.0.2
  title: Onboard External API Gateway ledger-cash deposits 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-cash deposits
paths:
  /ledger/cash-deposits/rates:
    x-original-path: /cash-deposits/rates
    get:
      summary: Get reference rate
      description: Get reference rate for cash deposits, from the pay-in currency to the account currency.
      operationId: getCashDepositRates
      x-visibility: external
      tags:
      - ledger-cash deposits
      parameters:
      - name: accountCurrency
        in: query
        required: true
        schema:
          type: string
      - name: payinCurrency
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Rate retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferRate'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
      - authToken: []
  /ledger/cash-deposits/quotes:
    x-original-path: /cash-deposits/quotes
    post:
      summary: Create deposit quote
      description: Create quote for cash deposit
      operationId: createDepositQuote
      x-visibility: external
      tags:
      - ledger-cash deposits
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDepositQuoteRequest'
      responses:
        '200':
          description: Quote created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashDepositQuote'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
      - authToken: []
  /ledger/cash-deposits:
    x-original-path: /cash-deposits
    get:
      summary: Retrieve list of cash deposits
      description: Retrieve a list of cash deposits, can accept accountId, status
      operationId: getCashDeposits
      x-visibility: external
      tags:
      - ledger-cash deposits
      parameters:
      - name: accountId
        in: query
        description: Filter by the account that was credited. Can be the main account ID or a sub-account ID.
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/LedgerSvcpage'
      - $ref: '#/components/parameters/LedgerSvcsize'
      responses:
        '200':
          description: Cash deposits list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashDepositTransactionList'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
      - authToken: []
    post:
      summary: Create cash deposit
      description: Create cash deposit, using the created quote. Returns the deposit transaction, including the payment details the customer must pay into.
      operationId: createCashDeposit
      x-visibility: external
      tags:
      - ledger-cash deposits
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCashDepositRequest'
      responses:
        '200':
          description: Cash deposit created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashDepositTransaction'
        '400':
          $ref: '#/components/responses/LedgerSvcInvalidRequest'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
      - authToken: []
  /ledger/cash-deposits/{reference}:
    x-original-path: /cash-deposits/{reference}
    get:
      summary: Get specific cash deposit
      description: Get specific cash deposit by reference
      operationId: getCashDepositByReference
      x-visibility: external
      tags:
      - ledger-cash deposits
      parameters:
      - name: reference
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: cash deposit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashDepositTransaction'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
        '404':
          $ref: '#/components/responses/LedgerSvcNotFound'
      security:
      - authToken: []
  /ledger/cash-deposits/currencies:
    x-original-path: /cash-deposits/currencies
    get:
      summary: Get supported pay-in currencies
      description: Get supported pay-in currencies for cash deposit. Only whitelisted pay-in currencies are returned.
      operationId: getCashDepositPayinCurrencies
      x-visibility: external
      tags:
      - ledger-cash deposits
      responses:
        '200':
          description: List of supported pay-in currencies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashPaymentCurrenciesList'
        '401':
          $ref: '#/components/responses/LedgerSvcUnauthorized'
      security:
      - authToken: []
components:
  schemas:
    CashPaymentCurrenciesList:
      type: object
      required:
      - currencies
      properties:
        currencies:
          type: array
          description: List of supported payout currencies for cash payments.
          items:
            $ref: '#/components/schemas/CashPaymentCurrency'
      x-source-svc: ledger
    CashPaymentChannel:
      type: object
      required:
      - name
      - id
      - beneficiaryType
      properties:
        name:
          type: string
          description: Human-readable display name of the payment method
          example: Bank Transfer
        id:
          type: string
          description: Unique identifier for this payment channel
          example: BANK_TRANSFER_NIGERIA
        beneficiaryType:
          type: string
          description: 'Type to use for beneficiaries created for this payment channel. See the Beneficiary schema for more details on beneficiary types.

            '
          example: BeneficiaryLocalBankAccount
      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
    TransferRate:
      type: object
      required:
      - accountCurrency
      - cashCurrency
      - rate
      properties:
        accountCurrency:
          type: string
          example: USD
        cashCurrency:
          type: string
          description: The cash (fiat) currency. For cash payments this is the payout currency; for cash deposits the pay-in currency.
          example: NGN
        rate:
          type: number
          example: 1500.5
      x-source-svc: ledger
    CashDepositTransaction:
      type: object
      description: Details of a cash deposit transaction.
      required:
      - id
      - reference
      - currency
      - status
      - payinCurrency
      - amount
      - rate
      - payinAmount
      - createdDate
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: string
          description: Reference for the cash deposit transaction at initiation.
        accountTransactionId:
          type: string
          description: Identifier of the credit transaction on the account.
        currency:
          type: string
          description: Currency in which the account was credited.
          example: USD
        status:
          $ref: '#/components/schemas/TransactionStatus'
        payinCurrency:
          type: string
          description: Currency the customer paid in.
          example: NGN
        amount:
          type: number
          description: Amount credited to the account.
          example: 100
        rate:
          type: number
          description: Exchange rate applied for this deposit.
          example: 1450.75
        payinAmount:
          type: number
          description: Amount the customer paid in, in the pay-in currency.
          example: 145075
        providerReference:
          type: string
          description: Reference provided by the cash deposit provider.
          example: PROV123456
        paymentDetails:
          $ref: '#/components/schemas/CashDepositPaymentDetails'
        createdDate:
          type: string
          format: date-time
      x-source-svc: ledger
    CashDepositTransactionList:
      allOf:
      - $ref: '#/components/schemas/Paging'
      - type: object
        properties:
          content:
            type: array
            items:
              $ref: '#/components/schemas/CashDepositTransaction'
      x-source-svc: ledger
    CreateDepositQuoteRequest:
      type: object
      required:
      - payinCurrency
      - accountCurrency
      - amount
      properties:
        payinCurrency:
          type: string
          example: NGN
          description: Currency the customer pays in.
        accountCurrency:
          type: string
          example: USD
          description: Currency of the account to be credited.
        amount:
          type: number
          example: 100
          multipleOf: 0.01
          exclusiveMinimum: 0
        unitCurrency:
          type: string
          description: Should be same as one of pay-in or account currencies. Defaults to account currency if not provided.
          example: USD
      x-source-svc: ledger
    CashDepositQuote:
      type: object
      required:
      - id
      - payinCurrency
      - accountCurrency
      - rate
      - minimumAmount
      - maximumAmount
      - expiresAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the deposit quote.
        accountCurrency:
          type: string
          description: Currency of the account to be credited.
          example: USD
        payinCurrency:
          type: string
          description: Currency the customer pays in.
          example: NGN
        rate:
          type: number
          description: Exchange rate applied for this quote
          example: 1450.75
        minimumAmount:
          type: number
          description: Minimum amount allowed for this quote
          example: 50
        maximumAmount:
          type: number
          description: Maximum amount allowed for this quote
          example: 10000
        minimumPayinAmount:
          type: number
          description: Minimum pay-in amount allowed for this quote
          example: 72500
        maximumPayinAmount:
          type: number
          description: Maximum pay-in amount allowed for this quote
          example: 14507500
        expiresAt:
          type: string
          format: date-time
          description: Timestamp field.
      x-source-svc: ledger
    CashPaymentCurrency:
      type: object
      required:
      - name
      - logo
      - code
      - countryCode
      - paymentChannels
      properties:
        name:
          type: string
        logo:
          type: string
        code:
          type: string
        countryCode:
          type: string
        paymentChannels:
          type: array
          uniqueItems: true
          default: []
          items:
            $ref: '#/components/schemas/CashPaymentChannel'
      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
    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
    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
    CreateCashDepositRequest:
      type: object
      description: Details required to create a cash deposit. The amount and currency must align with an existing quote.
      required:
      - quoteId
      - accountId
      - amount
      - reference
      properties:
        quoteId:
          type: string
          format: uuid
          description: Identifier of an existing cash deposit quote, retrieved from the cash deposit quote endpoint.
        accountId:
          type: string
          format: uuid
          description: Account to credit for this deposit. Can be the main account ID or a sub-account ID.
        reference:
          type: string
          description: Alpha-numeric deposit reference, unique for this deposit.
          example: CTR123456
          pattern: ^[a-zA-Z0-9_-]{8,48}$
          minLength: 8
          maxLength: 48
        amount:
          type: number
          exclusiveMinimum: 0
        unitCurrency:
          type: string
          description: 'Should be same as one of pay-in or account currencies in the quote.

            Defaults to account currency if not provided.

            '
        senderInfo:
          $ref: '#/components/schemas/DepositSenderInfo'
        narration:
          type: string
          description: Notes to be included with the deposit.
      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
    DepositSenderInfo:
      type: object
      description: Identifies the party sending fiat for the deposit. When omitted on a deposit request, it is constructed from the business details.
      required:
      - firstName
      - lastName
      - email
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        phoneNumber:
          type: string
          pattern: ^\+[1-9][0-9]{0,3}[0-9]{7,14}$
      x-source-svc: ledger
  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
  responses:
    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
    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'