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

# Refund a Crypto Deposit

> Requests the return of a crypto deposit that arrived at one of your customers' deposit addresses and matched no off-ramp order — the ones listed by `GET /customers/{customerId}/refundableCryptoDeposits/`.

Whether the request must name a destination is given by `refundDestinationRequired` on the listed deposit: `true` means `refundAddress` is **required** — unlike the order-rooted endpoint there is no order that could already carry one — and `false` means the crypto returns to the on-chain origin address and `refundAddress` is rejected with `20074`.

The request only **registers** the refund: Ripio reviews it before anything is sent on-chain, so `202` means "queued for review", not "sent". It is idempotent: `202` when the refund is registered, `200` when one already owns the deposit.

The response names the refund, not an order: keep the `refundId` and follow it through `latestRefund` on the deposit. Registering, approving and **rejecting** are all silent; only a completed refund emits an event, `OFF-RAMP.DEPOSIT.REFUNDED` (see [Off-Ramp Events](/ramps-api/webhooks/off-ramp-events)). Its payload carries the hash of the crypto that came **in** — read `refundedTxnHash` on the deposit for the hash of what went back.

Deposits whose order was cancelled are refunded through the order instead, with `POST /customers/{customerId}/transactions/offramp/{orderId}/refund/`.

See [Refunds](/ramps-api/refunds/overview) for the full model.

<Warning>
  Crypto refunds are an **opt-in feature that must be enabled for your account by the Ripio team**. While it is disabled, every request returns `403 Forbidden` with the error code `20072` (`CryptoRefundNotEnabledException`).
</Warning>


## OpenAPI

````yaml ramps-api/openapi.json POST /api/v1/customers/{customerId}/refundableCryptoDeposits/{depositId}/refund/
openapi: 3.1.0
info:
  title: Ripio Ramp API
  version: v1
  description: >-
    API for Ripio ramp services, enabling partners to integrate On-Ramp,
    Off-Ramp, customer management, KYC processes, and other financial
    functionalities. This API is RESTful, uses JSON for requests and responses,
    and standard HTTP status codes. This document is based on the
    'onramp-api.pdf' provided and aims to be compliant with OpenAPI
    Specification v3.1.0. The PDF indicates that the API documentation is a
    draft and subject to change.
servers:
  - url: https://skala-sandbox.ripio.com
    description: Sandbox environment
  - url: https://skala.ripio.com
    description: Production environment
security:
  - BearerToken: []
tags:
  - name: Authentication
    description: Operations related to API authentication and authorization.
  - name: Support Tickets
    description: >-
      Operations for raising and tracking customer support tickets with Ripio's
      support team. This feature must be enabled for your account by the Ripio
      team.
  - name: Customers
    description: Operations related to customer management.
  - name: KYC
    description: Operations related to Know Your Customer processes.
  - name: Fiat Accounts
    description: Operations related to managing fiat accounts and their requirements.
  - name: Quotes
    description: Operations related to obtaining and managing conversion quotes.
  - name: On-Ramp
    description: Operations related to fiat-to-crypto (on-ramp) processes.
  - name: Off-Ramp
    description: Operations related to crypto-to-fiat (off-ramp) processes.
  - name: Refunds
    description: >-
      Operations for returning the money of an on-ramp or off-ramp operation
      that could not be completed. Each ramp must be enabled for your account by
      the Ripio team.
  - name: Transactions
    description: Operations related to listing and managing all transaction types.
  - name: Networks
    description: >-
      Operations related to retrieving available deposit and withdrawal
      networks.
  - name: Rates
    description: Operations related to retrieving market rates.
  - name: Transaction Limits
    description: >-
      Operations related to retrieving per-transaction limits by currency and
      ramp operation.
  - name: Sandbox
    description: Operations specific to the sandbox environment for testing purposes.
  - name: Webhooks
    description: Webhook event notifications from Ripio Ramp API.
  - name: Sell and Pay
    description: >-
      Endpoints for managing Sell and Pay transactions, which allow customers to
      convert cryptocurrency to fiat currency and pay merchants via QR codes
paths:
  /api/v1/customers/{customerId}/refundableCryptoDeposits/{depositId}/refund/:
    post:
      tags:
        - Refunds
      summary: Refund a Crypto Deposit
      description: >-
        Requests the return of a crypto deposit that arrived at one of your
        customers' deposit addresses and matched no off-ramp order — the ones
        listed by `GET /customers/{customerId}/refundableCryptoDeposits/`.


        Whether the request must name a destination is given by
        `refundDestinationRequired` on the listed deposit: `true` means
        `refundAddress` is **required** — unlike the order-rooted endpoint there
        is no order that could already carry one — and `false` means the crypto
        returns to the on-chain origin address and `refundAddress` is rejected
        with `20074`.


        The request only **registers** the refund: Ripio reviews it before
        anything is sent on-chain, so `202` means "queued for review", not
        "sent". It is idempotent: `202` when the refund is registered, `200`
        when one already owns the deposit.


        The response names the refund, not an order: keep the `refundId` and
        follow it through `latestRefund` on the deposit. Registering, approving
        and **rejecting** are all silent; only a completed refund emits an
        event, `OFF-RAMP.DEPOSIT.REFUNDED` (see [Off-Ramp
        Events](/ramps-api/webhooks/off-ramp-events)). Its payload carries the
        hash of the crypto that came **in** — read `refundedTxnHash` on the
        deposit for the hash of what went back.


        Deposits whose order was cancelled are refunded through the order
        instead, with `POST
        /customers/{customerId}/transactions/offramp/{orderId}/refund/`.


        See [Refunds](/ramps-api/refunds/overview) for the full model.
      operationId: refundCryptoDeposit
      parameters:
        - $ref: '#/components/parameters/CustomerId'
        - $ref: '#/components/parameters/DepositId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrphanCryptoRefundRequest'
      responses:
        '200':
          description: A refund already owns this deposit; nothing new was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrphanCryptoRefundResponse'
        '202':
          description: Refund registered and queued for review.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrphanCryptoRefundResponse'
        '400':
          description: >-
            Bad Request - `refundAddress` was supplied for an account that
            refunds to the on-chain origin (`20074`), or it is missing when the
            deposit's `refundDestinationRequired` is `true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 20074
                type: CryptoRefundAddressNotAllowedException
                detail:
                  message: >-
                    A refund address is not allowed for this account: crypto
                    refunds are sent to the on-chain origin address.
                status: 400
        '401':
          description: Unauthorized - Invalid or missing access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 40001
                type: NotAuthenticated
                detail:
                  message: Authentication credentials were not provided.
                  code: not_authenticated
                status: 401
        '403':
          description: >-
            Forbidden - crypto refunds are not enabled for your account. Contact
            the Ripio team to enable this feature. The listing hides such
            deposits, so this answer means the deposit exists and the account
            cannot claim it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 20072
                type: CryptoRefundNotEnabledException
                detail:
                  message: Crypto refunds are not enabled for this account.
                status: 403
        '404':
          description: >-
            Not Found - the resource does not exist or does not belong to your
            account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 40004
                type: NotFound
                detail:
                  message: Not found.
                  code: not_found
                status: 404
        '409':
          description: >-
            Conflict - the deposit's matching has not concluded yet, so it may
            still find an order (`20077`, the one refusal you can retry later);
            or the deposit cannot be refunded at all (`20054`) — it was already
            refunded, or a previous attempt failed and Ripio's support team owns
            the retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 20077
                type: CryptoRefundDepositPendingMatchException
                detail:
                  message: >-
                    Crypto refund not allowed for deposit
                    3c9f6a15-52ec-4d8b-9a71-8f0c4d2e6b19: it may still match an
                    order
                status: 409
components:
  parameters:
    CustomerId:
      name: customerId
      in: path
      required: true
      description: Unique identifier for the customer.
      schema:
        type: string
        format: uuid
      example: 8142b065-79c4-4f48-9e33-11b17bc658d4
    DepositId:
      name: depositId
      in: path
      required: true
      description: Unique identifier for the crypto deposit.
      schema:
        type: string
        format: uuid
      example: 3c9f6a15-52ec-4d8b-9a71-8f0c4d2e6b19
  schemas:
    OrphanCryptoRefundRequest:
      type: object
      description: >-
        Body of a refund request for a crypto deposit with no order. Send
        `refundAddress` when the deposit's `refundDestinationRequired` is
        `true`; omit it when it is `false`.
      properties:
        refundAddress:
          type: string
          minLength: 10
          maxLength: 255
          description: >-
            On-chain address the crypto is returned to. **Required** when
            `refundDestinationRequired` is `true`: there is no order that could
            already carry an address. Rejected when the account is configured to
            refund to the deposit's origin address.
          example: '0x2f318C334780961FB129D2a6c30D0763d9a5C970'
    OrphanCryptoRefundResponse:
      type: object
      description: >-
        Acknowledgement of the refund request for a crypto deposit with no
        order. Shaped differently from the order-rooted `CryptoRefundResponse`:
        there is no order to name, and you need the `refundId` to follow the
        refund through `latestRefund` on the deposit.
      properties:
        refundId:
          type: string
          format: uuid
          description: Unique identifier of the refund.
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - REJECTED
            - FAILED
          description: >-
            State of the refund at the moment of the response. `PENDING` on a
            newly registered one: nothing has been sent on-chain yet.
        depositId:
          type: string
          format: uuid
          description: Identifier of the deposit being refunded.
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: Application-specific error code.
        type:
          type: string
          description: Type of error or exception.
        detail:
          type:
            - object
            - array
          description: >-
            Error details. The shape depends on the error:


            - Most business errors return an object with a `message` key.

            - Field validation errors return an object keyed by field name, each
            holding an array of `{ message, code }`.

            - Request-level validation errors (e.g. a missing query parameter)
            return a bare array of `{ message, code }`.
          properties:
            message:
              type: string
              description: Detailed error message.
          additionalProperties: true
        status:
          type: integer
          description: HTTP status code.
      required:
        - code
        - type
        - detail
        - status
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token obtained via
        [/oauth2/token/](/ramps-api/authentication/acquire-access-token). Use as
        `Authorization: Bearer <access_token>`.

````