> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onboard.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Cash Deposit

> Get specific cash deposit by reference

Fetches a single cash deposit by reference.


## OpenAPI

````yaml GET /ledger/cash-deposits/{reference}
openapi: 3.0.3
info:
  version: 3.0.2
  title: Onboard External API Gateway
  description: >-
    **Introduction**

    API Gateway for Onboard


    This 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.


    **Errors**

    Uses conventional HTTP response codes to indicate success or failure. In

    general:
     
    - `2xx` status codes indicate success. Codes in the

    - `4xx` range

    indicate a client error (e.g. required parameters, failed request etc.).

    - `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.
security: []
tags:
  - name: users-onboardapi
    description: Endpoints available to for merchants liquidity automation
  - name: users-users
    description: User related endpoints
  - name: users-partners
    description: Partner related endpoints
  - name: users-admin
    description: Back office related endpoints
  - name: users-user2fa
    description: User 2fa related endpoints
  - name: users-usernotifications
    description: User notifications related endpoints
  - name: users-merchantnetwork
    description: Merchant network endpoints
  - name: users-userauth
    description: Authentication endpoints
  - name: users-userservice
    description: Service endpoints
  - name: users-webhook
    description: webhook endpoints
  - name: users-config
    description: Configuration Endpoints
paths:
  /ledger/cash-deposits/{reference}:
    get:
      tags:
        - ledger-cash deposits
      summary: Get specific cash deposit
      description: Get specific cash deposit by reference
      operationId: getCashDepositByReference
      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:
        - HMACAuth: []
components:
  schemas:
    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
    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
    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.


        `details` can be nullable when the account number provider is still
        generating it
      required:
        - 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
    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
    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:
            $ref: '#/components/schemas/CashLocalBankAccount'
          CashSepaBankAccount:
            $ref: '#/components/schemas/CashSepaBankAccount'
          CashACHBankAccount:
            $ref: '#/components/schemas/CashACHBankAccount'
          CashSwiftBankAccount:
            $ref: '#/components/schemas/CashSwiftBankAccount'
          CashMobileWalletAccount:
            $ref: '#/components/schemas/CashMobileWalletAccount'
          CashMultiRailBankAccount:
            $ref: '#/components/schemas/CashMultiRailBankAccount'
      x-source-svc: ledger
    CashLocalBankAccount:
      allOf:
        - $ref: '#/components/schemas/CashAccountDetails'
        - $ref: '#/components/schemas/BaseLocalBankAccount'
      x-source-svc: ledger
    CashSepaBankAccount:
      allOf:
        - $ref: '#/components/schemas/CashAccountDetails'
        - $ref: '#/components/schemas/BaseSepaBankAccount'
      x-source-svc: ledger
    CashACHBankAccount:
      allOf:
        - $ref: '#/components/schemas/CashAccountDetails'
        - $ref: '#/components/schemas/BaseACHBankAccount'
      x-source-svc: ledger
    CashSwiftBankAccount:
      allOf:
        - $ref: '#/components/schemas/CashAccountDetails'
        - $ref: '#/components/schemas/BaseSwiftBankAccount'
      x-source-svc: ledger
    CashMobileWalletAccount:
      allOf:
        - $ref: '#/components/schemas/CashAccountDetails'
        - $ref: '#/components/schemas/BaseMobileWalletAccount'
      x-source-svc: ledger
    CashMultiRailBankAccount:
      allOf:
        - $ref: '#/components/schemas/CashAccountDetails'
        - $ref: '#/components/schemas/BaseMultiRailBankAccount'
      x-source-svc: ledger
    BaseLocalBankAccount:
      description: Details for local bank accounts
      type: object
      required:
        - bankCode
      properties:
        bankName:
          description: Beneficiary bank name
          type: string
        bankCode:
          description: Beneficiary bank code
          type: string
          minLength: 3
          maxLength: 12
        bankAddress:
          $ref: '#/components/schemas/PhysicalAddress'
      x-source-svc: ledger
    BaseSepaBankAccount:
      description: Details for SEPA accounts
      type: object
      required:
        - country
      properties:
        country:
          description: Beneficiary country ISO code
          type: string
          minLength: 2
          maxLength: 2
        bic:
          description: >
            Providing a BIC alongside the IBAN is optional for regular SEPA
            transfers. 

            Banks are required by SEPA to automatically derive the BIC from the
            IBAN.  

            You must still provide the BIC if the SEPA-participating country
            does not use the euro (e.g., Switzerland, Monaco, or San Marino).
          type: string
        bankName:
          description: Beneficiary bank name
          type: string
        bankAddress:
          $ref: '#/components/schemas/PhysicalAddress'
      x-source-svc: ledger
    BaseACHBankAccount:
      description: Bank details needed for ACH payments
      type: object
      required:
        - recipientAddress
        - bankAddress
        - routingNumber
        - bankName
      properties:
        routingNumber:
          type: string
          minLength: 9
          maxLength: 9
          pattern: ^\d{9}$
          example: '021000021'
        accountType:
          $ref: '#/components/schemas/AccountType'
        recipientAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        bankAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        bankName:
          description: Beneficiary bank name
          type: string
      x-source-svc: ledger
    BaseSwiftBankAccount:
      description: Bank details needed for SWIFT
      type: object
      required:
        - recipientAddress
        - bankAddress
        - bankName
        - bic
      properties:
        routingNumber:
          type: string
          minLength: 9
          maxLength: 9
          pattern: ^\d{9}$
          example: '021000021'
        recipientAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        bankAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        bankName:
          description: Beneficiary bank name
          type: string
        bic:
          description: Beneficiary BIC, might be called SWIFT code
          type: string
      x-source-svc: ledger
    BaseMobileWalletAccount:
      description: Details needed for mobile money payments
      type: object
      required:
        - accountNumber
      properties:
        accountNumber:
          description: >-
            Beneficiary account number, for Mobile Money, this is the phone
            number.
          type: string
          example: '233501234567'
        mobileNetwork:
          type: string
          description: >-
            Mobile network operator for the mobile money account (e.g., MTN,
            Vodafone)
      x-source-svc: ledger
    BaseMultiRailBankAccount:
      description: >
        Bank details for an account reachable via more than one
        independently-coded payment rail on the

        same account number (e.g. a US account that accepts ACH, FedWire, and
        SWIFT, each with its own

        routing code). Use the single-rail Cash*BankAccount schemas instead when
        only one rail applies.
      type: object
      required:
        - bankName
        - bankAddress
        - supportedRails
      properties:
        bankName:
          description: Beneficiary bank name
          type: string
        bankAddress:
          $ref: '#/components/schemas/PhysicalAddress'
        accountType:
          $ref: '#/components/schemas/AccountType'
        supportedRails:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/CashPaymentRail'
      x-source-svc: ledger
    PhysicalAddress:
      required:
        - city
        - country
        - postalCode
        - state
        - streetAddress
      type: object
      properties:
        streetAddress:
          minLength: 3
          type: string
          description: the street address of the user
          example: 11 Main Street
        city:
          minLength: 2
          type: string
          description: the city/municipality where the user lives
          example: Gbagada
        state:
          minLength: 3
          type: string
          description: the state/region/province where the user lives
          example: Lagos
        country:
          maxLength: 2
          minLength: 2
          type: string
          description: the country ISO CODE 3166-2 where the user lives
          example: NG
        postalCode:
          minLength: 4
          type: string
          description: the postal code of the specified address
          example: '200124'
        apartmentNo:
          minLength: 1
          type: string
          description: the flat/apartment number of the user at the specified address
          example: 5B
      x-source-svc: ledger
    AccountType:
      type: string
      description: The account type
      example: CHECKING
      enum:
        - CHECKING
        - SAVINGS
      x-source-svc: ledger
    CashPaymentRail:
      description: >
        A single payment rail supported by a multi-rail bank account, and the
        routing code specific to

        that rail (e.g. the ABA routing number for ACH/FedWire, or the BIC for
        SWIFT).
      type: object
      required:
        - rail
        - routingCode
      properties:
        rail:
          type: string
          enum:
            - ACH
            - FEDWIRE
            - SWIFT
        routingCode:
          type: string
          example: '021000021'
      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.
    LedgerSvcNotFound:
      description: Entity was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageDto'
          example:
            code: NOT_FOUND
            message: Information could not be found
  securitySchemes:
    HMACAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: |-
        Requires authentication via API key and HMAC signature.
          * `x-api-key`: Your API key generated from your Onboard Business dashboard.
          * `x-timestamp`:  Unix epoch timestamp (seconds) used in signature, allowed skew is 30 seconds
          * `x-signature`: SHA256 HMAC HEX signature calculated over  `t={x-timestamp}&{requestBody}` using your API Secret.

````