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

# Retrieve an onramp

> Retrieves an onramp.



## OpenAPI

````yaml https://production.hifi.com/api/v2/openapi.json get /v2/onramps/{transferId}
openapi: 3.0.0
info:
  title: Hifi API
  version: 2.0.0
  description: API documentation for HIFI
servers:
  - url: https://production.hifibridge.com
    description: Production server
  - url: https://sandbox.hifibridge.com
    description: Sandbox server
security:
  - bearerAuth: []
tags:
  - name: Common
    description: Common endpoints
  - name: User
    description: User endpoints
  - name: Kyc
    description: Kyc endpoints
  - name: Wallet
    description: Wallet endpoints
  - name: Account
    description: Account endpoints
  - name: External Account
    description: External Account endpoints for managing beneficiary bank accounts
  - name: Virtual Account
    description: Virtual Account endpoints
  - name: Onramp
    description: Onramp endpoints
  - name: Offramp
    description: Offramp endpoints
  - name: Orchestration Address
    description: >-
      Orchestration Address endpoints — persistent on-chain wallets that
      automatically off-ramp incoming stablecoin deposits to a USD bank account
  - name: Crypto Transfer
    description: Crypto Transfer endpoints
  - name: Cross-Chain Bridge
    description: Cross-Chain Bridge endpoints
  - name: Token Swap
    description: Token Swap endpoints
  - name: Canton Offers
    description: Canton Offers endpoints
  - name: Transfer Rules
    description: Transfer approval rules and configuration
  - name: Transfer Approvals
    description: Transfer approval workflow and admin actions
  - name: File
    description: File endpoints
  - name: Reporting
    description: Reporting and metrics endpoints
paths:
  /v2/onramps/{transferId}:
    get:
      tags:
        - Onramp
      summary: Retrieve an onramp
      description: Retrieves an onramp.
      parameters:
        - $ref: '#/components/parameters/OnrampRecordIDPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/FiatToCryptoRecordResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  parameters:
    OnrampRecordIDPathParameter:
      name: transferId
      in: path
      schema:
        type: string
      description: Transfer record ID.
      required: true
  responses:
    FiatToCryptoRecordResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OnrampRecordObject'
          examples:
            OnrampObjectUsdFiatPendingExample:
              $ref: '#/components/examples/OnrampObjectUsdFiatPendingExample'
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
    NotFoundResponse:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
  schemas:
    OnrampRecordObject:
      $ref: '#/components/schemas/OnrampObject'
    Unauthorized:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        error:
          type: string
          description: Error type
        errorDetails:
          type: string
          description: Detailed error message
    InternalServerError:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        error:
          type: string
          description: Error type
        errorDetails:
          type: string
          description: Detailed error message
    OnrampObject:
      type: object
      properties:
        transferType:
          type: string
        transferDetails:
          type: object
          properties:
            id:
              type: string
              format: uuid
            requestId:
              type: string
              format: uuid
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
            status:
              $ref: '#/components/schemas/OnrampStatusEnum'
            failedReason:
              type: string
              nullable: true
              description: >-
                Legacy failure label. `null` unless the transaction failed, and
                `null` on most failures in favour of `error` / `errorDetails`.
            error:
              type: string
              description: >
                Error code when the onramp transaction has failed (e.g.
                `INTERNAL_ERROR`, `EXPIRED`, `AMOUNT_TOO_LOW`,
                `TRANSACTION_REJECTED`).

                Present when status is a failed state such as `FIAT_FAILED`,
                `CRYPTO_FAILED`, or `QUOTE_FAILED`.
            errorDetails:
              type: string
              description: >
                Human-readable error details when the onramp transaction has
                failed.

                Present when status is a failed state.
            source:
              type: object
              properties:
                userId:
                  type: string
                  format: uuid
                currency:
                  type: string
                amount:
                  type: number
                  format: float
                accountId:
                  type: string
                  nullable: true
                  description: >-
                    Source account the fiat was pulled from. `null` for deposits
                    into a virtual account or into onramp deposit instructions,
                    where no source account is on file.
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      nullable: true
                    lastName:
                      type: string
                      nullable: true
                      description: >-
                        `null` for business users, which carry `businessName`
                        instead.
                    firstName:
                      type: string
                      nullable: true
                      description: >-
                        `null` for business users, which carry `businessName`
                        instead.
                    businessName:
                      type: string
                      nullable: true
                      description: >-
                        `null` for individual users, which carry `firstName` /
                        `lastName` instead.
                bankInfo:
                  nullable: true
                  allOf:
                    - $ref: '#/components/schemas/InboundObject'
            destination:
              type: object
              properties:
                userId:
                  type: string
                  format: uuid
                currency:
                  type: string
                chain:
                  type: string
                walletAddress:
                  type: string
                externalWalletId:
                  type: string
                amount:
                  type: number
                  format: float
                user:
                  type: object
                  properties:
                    email:
                      type: string
                    lastName:
                      type: string
                    firstName:
                      type: string
                    businessName:
                      type: string
            receipt:
              type: object
              properties:
                transactionHash:
                  type: string
                  nullable: true
                returnReasonCode:
                  type: string
                  nullable: true
                  description: >-
                    Reason code for the returned inbound payment. Only populated
                    when `status` is `FIAT_RETURNED`.
            virtualAccountId:
              type: string
              format: uuid
              nullable: true
              description: >-
                Virtual account the funds were deposited into. `null` when the
                onramp was not driven by a virtual account.
            microDeposits:
              type: object
              description: >-
                Micro deposits received into the onramp deposit account while it
                is awaiting funds.
              properties:
                count:
                  type: integer
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      createdAt:
                        type: string
                        format: date-time
                      currency:
                        type: string
                      amount:
                        type: number
                        format: float
                      sourceBankInfo:
                        $ref: '#/components/schemas/InboundObject'
            quoteInformation:
              type: object
              nullable: true
              properties:
                sendGross:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                sendNet:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                railFee:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                receiveGross:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                receiveNet:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                rate:
                  type: string
                conversionFee:
                  type: object
                  description: >-
                    Conversion fee applied on the quote. Present on usd onramps,
                    where it is always zero.
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                    description:
                      type: string
                    timing:
                      type: string
                expiresAt:
                  type: string
                  description: >
                    Expiry of the quote as an ISO 8601 timestamp. Returns the
                    literal string `"N/A"` for

                    static quotes (usd onramps), which do not expire.
            depositInfo:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/OnrampDepositInfoObject'
    OnrampStatusEnum:
      type: string
      enum:
        - NOT_INITIATED
        - CREATED
        - OPEN_QUOTE
        - IN_REVIEW
        - FIAT_INITIATED
        - AWAITING_FUNDS
        - FIAT_PENDING
        - FIAT_PROCESSED
        - CRYPTO_INITIATED
        - CRYPTO_PENDING
        - COMPLETED
        - FIAT_FAILED
        - FIAT_RETURNED
        - CRYPTO_FAILED
        - QUOTE_FAILED
        - EXPIRED
        - CANCELLED
        - UNKNOWN
      description: >
        Refer to
        [here](https://docs.hifi.com/docs/transfers/onramps#transaction-status)
        for more details on each onramp status.
    InboundObject:
      type: object
      properties:
        bankName:
          type: string
          nullable: true
        senderName:
          type: string
          nullable: true
        routingNumber:
          type: string
          nullable: true
        accountNumber:
          type: string
          nullable: true
        accountType:
          type: string
          nullable: true
          description: ACH field. `null` when the inbound payment did not carry it.
        fedBatchId:
          type: string
          nullable: true
          description: ACH field. `null` when the inbound payment did not carry it.
        imad:
          type: string
          nullable: true
          description: >-
            Fedwire input message identifier. `null` when the inbound payment
            did not carry it.
        omad:
          type: string
          nullable: true
          description: >-
            Fedwire output message identifier. `null` when the inbound payment
            did not carry it.
        traceNumber:
          type: string
          nullable: true
          description: >-
            Trace number for the inbound payment. `null` when the payment did
            not carry one.
        bankAddress:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        references:
          type: object
          nullable: true
          description: >-
            Remittance and reference information supplied by the sender. `null`
            when the payment carried none.
          properties:
            senderReference:
              type: string
              nullable: true
            beneficiaryReference:
              type: string
              nullable: true
            remittance:
              type: array
              items:
                type: string
        paymentRail:
          type: string
          enum:
            - ach
            - wire
            - rtp
          nullable: true
    OnrampDepositInfoObject:
      type: object
      properties:
        bankName:
          type: string
        bankAddress:
          type: string
        swiftCode:
          type: string
        beneficiary:
          type: object
          properties:
            name:
              type: string
            address:
              type: string
        ach:
          type: object
          properties:
            routingNumber:
              type: string
            accountNumber:
              type: string
        wire:
          type: object
          properties:
            routingNumber:
              type: string
            accountNumber:
              type: string
        rtp:
          type: object
          properties:
            routingNumber:
              type: string
            accountNumber:
              type: string
        reference:
          type: string
        depositBy:
          type: string
          format: date-time
        instruction:
          type: string
  examples:
    OnrampObjectUsdFiatPendingExample:
      summary: Onramp Object (USD - FIAT_PENDING)
      value:
        transferType: ONRAMP
        transferDetails:
          id: b26927e6-2771-423c-af44-a3c7a3e815c5
          requestId: e1047def-6942-4fd7-be04-e62eb41813b6
          createdAt: '2025-02-03T17:15:31.927121+00:00'
          updatedAt: '2025-02-03T17:15:35.882+00:00'
          status: FIAT_PENDING
          failedReason: null
          source:
            userId: c15c0adf-3e45-4a62-b334-73aeec127649
            currency: usd
            amount: 10
            accountId: null
            user:
              email: example@hifibridge.com
              lastName: Wu
              firstName: Henry
              businessName: null
            bankInfo:
              bankName: Bank of America
              beneficiaryName: Henry Wu
              description: ''
              routingNumber: '026009593'
              referenceNumber: HFD70579F
              imad: ''
              omad: ''
              bankAddress: 100 N Tryon St, Charlotte, NC 28202, USA
          destination:
            userId: c15c0adf-3e45-4a62-b334-73aeec127649
            currency: usdc
            chain: POLYGON
            walletAddress: '0x848732f6c834E05b17C56fa01E83EE095f72C3c3'
            externalWalletId: null
            amount: null
            user:
              email: example@hifibridge.com
              lastName: Wu
              firstName: Henry
              businessName: null
          receipt:
            transactionHash: null
          developerFee: null
          virtualAccountId: null
          quoteInformation:
            sendGross:
              amount: '10.00'
              currency: usd
            sendNet:
              amount: '10.00'
              currency: usd
            railFee:
              amount: '0.00'
              currency: usdc
            receiveGross:
              amount: '10.00'
              currency: usdc
            receiveNet:
              amount: '10.00'
              currency: usdc
            rate: '1.00'
            expiresAt: N/A
          depositInfo:
            bankName: Bank of NoWhere
            bankAddress: 123 Main St, New York, NY 10001, USA
            beneficiary:
              name: Henry Wu
              address: Example St 1., Apt 123, New York, NY, 10010, US
            ach:
              routingNumber: '028000024'
              accountNumber: '123456789'
            wire:
              routingNumber: '021000021'
              accountNumber: '123456789'
            rtp:
              routingNumber: '021000021'
              accountNumber: '123456789'
            reference: HFD70579F
            depositBy: '2025-10-04T04:23:40.229Z'
            instruction: >-
              Please deposit only one payment with the exact amount of usd and
              the reference code HFD70579F to the designated bank account by
              2025-10-04T04:23:40.229Z. Missing or incorrect reference codes,
              discrepancies in the amount, or additional payments may result in
              the funds being lost. Ensure that the beneficiary name matches the
              provided account holder name, otherwise the payment may be
              rejected.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````