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

# Initiate an off-ramp request with transaction hash

> Mark an off-ramp request as initiated by submitting its on-chain transaction hash.

After sending crypto to the Venly deposit wallet, submit the `blockchainTransactionHash` to initiate processing of an off-ramp request.

**Concept guide:** [Transactions](/guides/payments/transactions)


## OpenAPI

````yaml api-reference/Fundflow-API.yaml PATCH /v1/ramp-requests/{id}/initiate
openapi: 3.1.0
info:
  title: Fundflow API
  description: >
    Fundflow API provides endpoints for managing cryptocurrency on-ramp and
    off-ramp requests, 

    company bank accounts, wallets, and user management for blockchain payment
    operations.


    ## Overview

    The Fundflow API enables companies to:

    - Create and manage on-ramp (fiat to crypto) and off-ramp (crypto to fiat)
    requests

    - Manage company bank accounts across multiple payment networks (SEPA, ACH,
    SWIFT, etc.)

    - Manage company cryptocurrency wallets across multiple blockchains

    - Handle user roles and permissions within the company

    - Calculate fees and retrieve exchange rate information


    ## Authentication

    All endpoints require OAuth2 authentication using a bearer token that is
    retrieved from authentication endpoint using your client_id and
    client_secret.


    ## Optimistic Locking

    Many write operations use optimistic locking via a `version` field to
    prevent concurrent updates.

    When a version conflict occurs (HTTP 409), you must:

    1. Fetch the latest version of the resource

    2. Reapply their changes to the updated resource

    3. Retry the operation with the new version number


    ## Status Workflows


    ### Ramp Request Status Flow

    - **AWAITING_APPROVAL** → **AWAITING_FUNDS** (after approval)

    - **AWAITING_APPROVAL** → **CANCELLED** (cancelled by requester)

    - **AWAITING_APPROVAL** → **REJECTED** (rejected by company admin)

    - **AWAITING_APPROVAL** → **DENIED** (denied by Venly admin)

    - **AWAITING_APPROVAL** → **BLOCKED** (blocked by Venly admin)

    - **AWAITING_FUNDS** → **PROCESSING** (payment received/initiated)

    - **PROCESSING** → **SUCCEEDED** (transaction completed)

    - **PROCESSING** → **FAILED** (transaction failed)
  contact:
    name: Venly
    url: https://venly.io
    email: contact@venly.io
  version: 1.7.0
servers:
  - url: https://api-fundflow.venly.io
    description: Production
  - url: https://api-fundflow-staging.venly.io
    description: Staging
security: []
tags:
  - name: Ramp Requests
    description: >-
      On-ramp (fiat to crypto) and off-ramp (crypto to fiat) request lifecycle
      and management
  - name: Fees
    description: Fee configuration and per-request fee calculation
  - name: Company Wallets
    description: Company cryptocurrency wallet whitelisting, verification, and management
  - name: Company Bank Accounts
    description: >-
      Company bank account whitelisting and management across payment networks
      (SEPA, ACH, SWIFT, and more)
  - name: Deposit Wallets
    description: >-
      Venly deposit wallet addresses for wallet-ownership verification and
      off-ramp settlement
  - name: Crypto Currencies
    description: >-
      Cryptocurrencies supported for ramp operations, organised by blockchain
      network
  - name: Fiat Currencies
    description: Fiat currencies supported for ramp operations
  - name: Blockchain Networks
    description: Blockchain networks supported for cryptocurrency operations
  - name: Bank Account Configuration
    description: Enabled bank account types, supported countries, and supported currencies
  - name: Company
    description: Authenticated company details and KYB status
  - name: Users
    description: Company user management, roles, and permissions
  - name: Authentication
    description: Authenticated user profile, company affiliation, and assigned authorities
paths:
  /v1/ramp-requests/{id}/initiate:
    patch:
      tags:
        - Ramp Requests
      summary: Initiate an off-ramp request with transaction hash
      description: >
        Updates the blockchain transaction hash for an off-ramp request, marking
        it as initiated. 
      operationId: updateTxHash
      parameters:
        - name: id
          in: path
          description: Unique identifier of the ramp request
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRampRequestTransactionHashRequest'
      responses:
        '200':
          description: Transaction hash successfully updated
          content:
            '*/*':
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    default: true
                  result:
                    $ref: '#/components/schemas/RampRequestDto'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/Conflict'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - OAuth2:
            - sign-off:ramp-request
components:
  schemas:
    UpdateRampRequestTransactionHashRequest:
      type: object
      title: Update Ramp Request Transaction Hash
      description: >-
        Request to add or update the blockchain transaction hash for a ramp
        request
      required:
        - blockchainTransactionHash
        - version
      properties:
        version:
          type: integer
          format: int64
          description: Version number for optimistic locking
        blockchainTransactionHash:
          type: string
          minLength: 1
          description: >
            The transaction hash of the transfer of crypto funds to the Venly
            deposit wallet.
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
    RampRequestDto:
      type: object
      description: >-
        Complete ramp request details including status, amounts, and event
        history
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
        companyId:
          type: string
          format: uuid
          description: Associated company ID
        companyName:
          type: string
          description: Name of the company
        rampType:
          type: string
          description: Type of ramp operation
          enum:
            - ON_RAMP
            - OFF_RAMP
        status:
          type: string
          description: >
            Current status of the request. See API overview for status flow
            details.
          enum:
            - AWAITING_APPROVAL
            - AWAITING_FUNDS
            - PROCESSING
            - SUCCEEDED
            - FAILED
            - BLOCKED
            - DENIED
            - REJECTED
            - CANCELLED
        amount:
          type: number
          description: Deprecated - use fiatAmount or cryptoAmount instead
          deprecated: true
        netAmount:
          type: number
          description: Deprecated - use fiatNetAmount instead
          deprecated: true
        fiatAmount:
          type: number
          description: Total fiat amount (including fees)
          example: 1000
        fiatNetAmount:
          type: number
          description: Net fiat amount (after deducting fees)
          example: 990
        cryptoAmount:
          type: number
          description: Crypto amount
          example: 0.5
        fiatFeeAmount:
          type: number
          description: Fee amount in fiat currency
          example: 10
        exchangeRate:
          type: number
          description: |
            Exchange rate used for the conversion.
          example: 2000
        feePercentage:
          type: number
          description: Fee percentage applied
          example: 1
        paymentReference:
          type: string
          description: Auto-generated unique payment reference for tracking
          example: PAY-2024-001234
        paymentReceived:
          type: boolean
          description: Whether payment has been received
        blockchainTransactionHash:
          type: string
          description: Blockchain transaction hash (when available)
          example: 0x1234...
        createdAt:
          type: string
          format: date-time
          description: Timestamp when request was created
        companyBankAccount:
          description: Company bank account (for OFF_RAMP)
          oneOf:
            - $ref: '#/components/schemas/EurSepaCompanyBankAccountDto'
            - $ref: '#/components/schemas/GbpChapsCompanyBankAccountDto'
            - $ref: '#/components/schemas/GbpFpsCompanyBankAccountDto'
            - $ref: '#/components/schemas/OtherCurrencySwiftCompanyBankAccountDto'
            - $ref: '#/components/schemas/UsAchCompanyBankAccountDto'
            - $ref: '#/components/schemas/UsSwiftCompanyBankAccountDto'
            - $ref: '#/components/schemas/UsWireCompanyBankAccountDto'
        companyWallet:
          $ref: '#/components/schemas/CompanyWalletDto'
          description: Company wallet (for ON_RAMP)
        depositBankAccount:
          description: |
            Venly deposit bank account where fiat should be sent (for ON_RAMP).
          oneOf:
            - $ref: '#/components/schemas/EurSepaDepositBankAccountDto'
            - $ref: '#/components/schemas/GbpChapsDepositBankAccountDto'
            - $ref: '#/components/schemas/GbpFpsDepositBankAccountDto'
            - $ref: '#/components/schemas/OtherCurrencySwiftDepositBankAccountDto'
            - $ref: '#/components/schemas/UsAchDepositBankAccountDto'
            - $ref: '#/components/schemas/UsSwiftDepositBankAccountDto'
            - $ref: '#/components/schemas/UsWireDepositBankAccountDto'
        depositWallet:
          $ref: '#/components/schemas/DepositWalletDto'
          description: |
            Venly deposit wallet where crypto should be sent (for OFF_RAMP).
        fiatCurrency:
          $ref: '#/components/schemas/FiatCurrencyDto'
        cryptoCurrency:
          $ref: '#/components/schemas/CryptoCurrencyDto'
        events:
          type: array
          description: Complete audit trail of all events for this request
          items:
            $ref: '#/components/schemas/RampRequestEventDto'
        version:
          type: integer
          format: int64
          description: Version number for optimistic locking
        amountReceived:
          type: number
          description: Actual amount received
    EurSepaCompanyBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/CompanyBankAccountDto'
        - type: object
          properties:
            iban:
              type: string
              description: International Bank Account Number
            bic:
              type: string
              description: Bank Identifier Code
            intermediaryBic:
              type: string
              description: Intermediary bank BIC (if applicable)
    GbpChapsCompanyBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/CompanyBankAccountDto'
        - type: object
          properties:
            accountNumber:
              type: string
            sortCode:
              type: string
    GbpFpsCompanyBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/CompanyBankAccountDto'
        - type: object
          properties:
            accountNumber:
              type: string
              description: UK account number (8 digits)
            sortCode:
              type: string
              description: UK sort code (6 digits)
    OtherCurrencySwiftCompanyBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/CompanyBankAccountDto'
        - type: object
          properties:
            currency:
              type: string
              description: ISO 4217 currency code
            bic:
              type: string
            accountNumber:
              type: string
            iban:
              type: string
            intermediaryBankName:
              type: string
            intermediaryBic:
              type: string
            intermediaryAccountNumber:
              type: string
    UsAchCompanyBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/CompanyBankAccountDto'
        - type: object
          properties:
            accountNumber:
              type: string
            routingNumber:
              type: string
              description: ABA routing number
    UsSwiftCompanyBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/CompanyBankAccountDto'
        - type: object
          properties:
            bic:
              type: string
            accountNumber:
              type: string
            iban:
              type: string
            bankStreetAddress:
              type: string
            bankCity:
              type: string
            bankPostalCode:
              type: string
            intermediaryBankName:
              type: string
            intermediaryBic:
              type: string
            intermediaryAccountNumber:
              type: string
    UsWireCompanyBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/CompanyBankAccountDto'
        - type: object
          properties:
            accountNumber:
              type: string
            routingNumber:
              type: string
    CompanyWalletDto:
      type: object
      description: Company cryptocurrency wallet details
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        description:
          type: string
          description: User-provided description
        address:
          type: string
          description: Blockchain wallet address
        chain:
          type: string
          description: Blockchain network
          enum:
            - ETHEREUM
            - POLYGON
            - BASE
            - ARBITRUM
            - SUI
        verificationStatus:
          type: string
          description: |
            Verification status of the wallet.
          enum:
            - PENDING
            - VERIFIED
            - DENIED
        verifiedAt:
          type: string
          format: date-time
          description: When wallet was verified (if applicable)
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        version:
          type: integer
          format: int64
    EurSepaDepositBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/DepositBankAccountDto'
        - type: object
          properties:
            bic:
              type: string
            intermediaryBic:
              type: string
            iban:
              type: string
    GbpChapsDepositBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/DepositBankAccountDto'
        - type: object
          properties:
            accountNumber:
              type: string
            sortCode:
              type: string
    GbpFpsDepositBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/DepositBankAccountDto'
        - type: object
          properties:
            accountNumber:
              type: string
            sortCode:
              type: string
    OtherCurrencySwiftDepositBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/DepositBankAccountDto'
        - type: object
          properties:
            companyName:
              type: string
            email:
              type: string
            phoneNumber:
              type: string
            bic:
              type: string
            accountNumber:
              type: string
            iban:
              type: string
            bankCountry:
              type: string
            intermediaryBankName:
              type: string
            intermediaryBic:
              type: string
            intermediaryAccountNumber:
              type: string
            beneficiaryAddressLine1:
              type: string
            beneficiaryAddressLine2:
              type: string
            beneficiaryCity:
              type: string
            beneficiaryState:
              type: string
            beneficiaryPostalCode:
              type: string
            beneficiaryCountry:
              type: string
    UsAchDepositBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/DepositBankAccountDto'
        - type: object
          properties:
            companyName:
              type: string
            email:
              type: string
            phoneNumber:
              type: string
            accountNumber:
              type: string
            routingNumber:
              type: string
            bankCountry:
              type: string
            beneficiaryAddressLine1:
              type: string
            beneficiaryAddressLine2:
              type: string
            beneficiaryCity:
              type: string
            beneficiaryState:
              type: string
            beneficiaryPostalCode:
              type: string
            beneficiaryCountry:
              type: string
    UsSwiftDepositBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/DepositBankAccountDto'
        - type: object
          properties:
            companyName:
              type: string
            email:
              type: string
            phoneNumber:
              type: string
            bic:
              type: string
            accountNumber:
              type: string
            iban:
              type: string
            bankCountry:
              type: string
            bankStreetAddress:
              type: string
            bankCity:
              type: string
            bankPostalCode:
              type: string
            intermediaryBankName:
              type: string
            intermediaryBic:
              type: string
            intermediaryAccountNumber:
              type: string
            beneficiaryAddressLine1:
              type: string
            beneficiaryAddressLine2:
              type: string
            beneficiaryCity:
              type: string
            beneficiaryState:
              type: string
            beneficiaryPostalCode:
              type: string
            beneficiaryCountry:
              type: string
    UsWireDepositBankAccountDto:
      allOf:
        - $ref: '#/components/schemas/DepositBankAccountDto'
        - type: object
          properties:
            companyName:
              type: string
            email:
              type: string
            phoneNumber:
              type: string
            accountNumber:
              type: string
            routingNumber:
              type: string
            bankCountry:
              type: string
            beneficiaryAddressLine1:
              type: string
            beneficiaryAddressLine2:
              type: string
            beneficiaryCity:
              type: string
            beneficiaryState:
              type: string
            beneficiaryPostalCode:
              type: string
            beneficiaryCountry:
              type: string
    DepositWalletDto:
      type: object
      description: |
        Venly-managed deposit wallet where customers send crypto for off-ramp.
      properties:
        id:
          type: string
          format: uuid
        address:
          type: string
          description: Blockchain wallet address
        chain:
          type: string
          enum:
            - ETHEREUM
            - POLYGON
            - BASE
            - ARBITRUM
            - SUI
        label:
          type: string
        isDefault:
          type: boolean
        isActive:
          type: boolean
        version:
          type: integer
          format: int64
    FiatCurrencyDto:
      type: object
      description: Fiat currency supported for ramp operations
      properties:
        id:
          type: string
          format: uuid
        currency:
          type: string
          description: ISO 4217 currency code
          example: EUR
        label:
          type: string
          description: Display name
          example: Euro
        enabled:
          type: boolean
          description: Whether this currency is currently enabled
        version:
          type: integer
          format: int64
    CryptoCurrencyDto:
      type: object
      description: Cryptocurrency supported for ramp operations
      properties:
        id:
          type: string
          format: uuid
        currency:
          type: string
          description: Currency symbol
          example: USDC
        chain:
          type: string
          description: Blockchain network
          enum:
            - ETHEREUM
            - POLYGON
            - BASE
            - ARBITRUM
            - SUI
        label:
          type: string
          description: Display name
          example: USD Coin
        enabled:
          type: boolean
        version:
          type: integer
          format: int64
        coingeckoId:
          type: string
          description: CoinGecko API identifier for price data
    RampRequestEventDto:
      type: object
      description: Audit event for a ramp request
      properties:
        id:
          type: string
          format: uuid
        eventType:
          type: string
          description: Type of event that occurred
          enum:
            - CREATED
            - AWAITING_APPROVAL
            - TX_HASH_ADDED
            - UPDATED
            - STATUS_CHANGED
            - APPROVED
            - REJECTED
            - ADMIN_REJECTED
            - PAYMENT_RECEIVED
            - PAYMENT_SENT
            - COMPLETED
            - FAILED
            - CANCELLED
            - AMOUNT_CHANGED
        userId:
          type: string
          description: ID of user who triggered the event
        username:
          type: string
          description: Username of user who triggered the event
        email:
          type: string
          description: Email of user who triggered the event
        role:
          type: string
          description: Role of user who triggered the event
          enum:
            - COMPANY_ADMIN
            - COMPANY_VIEWER
            - COMPANY_MANAGER
        createdAt:
          type: string
          format: date-time
          description: When the event occurred
        version:
          type: integer
          format: int64
        metadata:
          type: object
          description: |
            Event-specific metadata in JSON format.
            For AMOUNT_CHANGED events, contains:
            - previousAmount: The amount before the change
            - newAmount: The amount after the change
    ErrorResponse:
      type: object
      description: Error response wrapper
      properties:
        success:
          type: boolean
          default: false
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorBody'
        result:
          type: object
          nullable: true
    CompanyBankAccountDto:
      type: object
      description: Base company bank account schema
      discriminator:
        propertyName: bankAccountType
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        name:
          type: string
          description: Display name
        bankName:
          type: string
        companyName:
          type: string
          description: Legal company name (account holder)
        email:
          type: string
        phoneNumber:
          type: string
        bankCountry:
          type: string
          description: ISO 3166-1 alpha-2 country code
        beneficiaryAddressLine1:
          type: string
        beneficiaryAddressLine2:
          type: string
        beneficiaryCity:
          type: string
        beneficiaryState:
          type: string
        beneficiaryPostalCode:
          type: string
        beneficiaryCountry:
          type: string
          description: ISO 3166-1 alpha-2 country code
        bankAccountType:
          type: string
          enum:
            - EUR_SEPA
            - USD_WIRE
            - USD_ACH
            - USD_SWIFT
            - GBP_FPS
            - GBP_CHAPS
            - OTHER_SWIFT
        supportedRampType:
          type: string
          enum:
            - ON_RAMP
            - OFF_RAMP
            - ON_AND_OFF_RAMP
        verificationStatus:
          type: string
          description: |
            Verification status of the bank account.
          enum:
            - PENDING
            - VERIFIED
            - DENIED
        verifiedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        version:
          type: integer
          format: int64
    DepositBankAccountDto:
      type: object
      description: >
        Venly-managed deposit bank account where customers send fiat for
        on-ramp.
      discriminator:
        propertyName: bankAccountType
      properties:
        id:
          type: string
          format: uuid
        bankName:
          type: string
        beneficiary:
          type: string
          description: Beneficiary name (Venly entity)
        fiatCurrency:
          $ref: '#/components/schemas/FiatCurrencyDto'
        label:
          type: string
        isActive:
          type: boolean
        isDefault:
          type: boolean
        bankAccountType:
          type: string
          enum:
            - EUR_SEPA
            - USD_WIRE
            - USD_ACH
            - USD_SWIFT
            - GBP_FPS
            - GBP_CHAPS
            - OTHER_SWIFT
        version:
          type: integer
          format: int64
    ErrorBody:
      type: object
      description: Individual error details
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
  responses:
    BadRequest:
      description: When the request contains invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: validation-error
                message: A descriptive error message
    Unauthorized:
      description: When the user is not authorized to access the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: UNAUTHORIZED
                message: Access is denied.
    Forbidden:
      description: When a user doesn't have proper security authority
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: FORBIDDEN
                message: User doesn't have proper authority to access this resource
    NotFound:
      description: When a resource is not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: NOT_FOUND
    MethodNotAllowed:
      description: When the HttpMethod is not supported
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: METHOD_NOT_SUPPORTED
                message: HttpMethod is not supported. Supported methods are [..]
    Conflict:
      description: Version conflict - the resource was modified by another request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: OPTIMISTIC_LOCK_EXCEPTION
                message: >-
                  The resource has been modified. Please fetch the latest
                  version and retry.
    UnsupportedMediaType:
      description: Usually when the input is not a valid json
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: INVALID_MEDIA_TYPE
    InternalServerError:
      description: When there's an unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            errors:
              - code: INTERNAL_SERVER_ERROR
                message: A description of the error (optional)
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth2 authentication via Venly Identity Platform
      flows:
        implicit:
          authorizationUrl: >-
            https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/auth
          scopes:
            openid: OpenID Connect scope
            view:ramp-request: View ramp requests
            create:ramp-request: Create ramp requests
            edit:ramp-request: Edit ramp request amounts
            approve:ramp-request: Approve ramp requests
            reject:ramp-request: Reject ramp requests
            cancel:ramp-request: Cancel ramp requests
            sign-off:ramp-request: Sign off on ramp requests (add transaction hash)
            export:ramp-requests: Export ramp requests
            view:company-wallet: View company wallets
            manage:company-wallet: Create and manage company wallets
            view:company-bank-account: View company bank accounts
            manage:company-bank-account: Create and manage company bank accounts
            manage:company-users: Manage company users

````