> ## 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.
# List Refundable Crypto Deposits
> Returns the customer's crypto deposits that arrived at one of their off-ramp deposit addresses and matched no order. Crypto twin of `GET /customers/{customerId}/refundableDeposits/`: the object is a payment with no operation behind it, so it appears on no transaction listing — this is the only place you see it.
By default the list answers **what can still be claimed**: only the deposits a new refund can be requested for. A deposit whose refund is under way or already completed is not listed; one whose previous request was rejected is, and its `latestRefund` carries the reason.
With `?includeRequested=true` it answers **where the customer's crypto is**: the same deposits plus the ones whose refund was already requested and has not landed on-chain yet, each carrying its state in `latestRefund`. A deposit leaves the list only when its refund reaches `COMPLETED`. In that wider mode the presence of a deposit no longer means it can be claimed: read `latestRefund` to tell the two apart (`null` or `REJECTED` → a refund can be requested; any other state → one is already under way).
Only deposits whose matching has concluded are listed. A deposit that arrived seconds ago and may still find its order is held back, because refunding it would return crypto an imminent match is about to sell. The refund endpoint deliberately accepts it and answers `409` / `20077`, which is the one refusal you can retry later.
Both modes require off-ramp refunds to be enabled for your account. While they are not, the claimable half is left out of both: the endpoint answers `200` with no such deposits rather than offering ones a request would then reject with `403` / `20072`. An empty page therefore does not mean the customer has no unmatched deposits. What `?includeRequested=true` still returns in that case is any deposit whose refund Ripio support already started on the customer's behalf.
This endpoint serves API integrations. Deposits made through an off-ramp **session** always get an order, so a widget-only integration has none of these.
Crypto refunds are an **opt-in feature that must be enabled for your account by the Ripio team**. While it is disabled, this listing returns no claimable deposits — an empty page does not mean the customer has none.
## OpenAPI
````yaml ramps-api/openapi.json GET /api/v1/customers/{customerId}/refundableCryptoDeposits/
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/:
get:
tags:
- Refunds
summary: List Refundable Crypto Deposits
description: >-
Returns the customer's crypto deposits that arrived at one of their
off-ramp deposit addresses and matched no order. Crypto twin of `GET
/customers/{customerId}/refundableDeposits/`: the object is a payment
with no operation behind it, so it appears on no transaction listing —
this is the only place you see it.
By default the list answers **what can still be claimed**: only the
deposits a new refund can be requested for. A deposit whose refund is
under way or already completed is not listed; one whose previous request
was rejected is, and its `latestRefund` carries the reason.
With `?includeRequested=true` it answers **where the customer's crypto
is**: the same deposits plus the ones whose refund was already requested
and has not landed on-chain yet, each carrying its state in
`latestRefund`. A deposit leaves the list only when its refund reaches
`COMPLETED`. In that wider mode the presence of a deposit no longer
means it can be claimed: read `latestRefund` to tell the two apart
(`null` or `REJECTED` → a refund can be requested; any other state → one
is already under way).
Only deposits whose matching has concluded are listed. A deposit that
arrived seconds ago and may still find its order is held back, because
refunding it would return crypto an imminent match is about to sell. The
refund endpoint deliberately accepts it and answers `409` / `20077`,
which is the one refusal you can retry later.
Both modes require off-ramp refunds to be enabled for your account.
While they are not, the claimable half is left out of both: the endpoint
answers `200` with no such deposits rather than offering ones a request
would then reject with `403` / `20072`. An empty page therefore does not
mean the customer has no unmatched deposits. What
`?includeRequested=true` still returns in that case is any deposit whose
refund Ripio support already started on the customer's behalf.
This endpoint serves API integrations. Deposits made through an off-ramp
**session** always get an order, so a widget-only integration has none
of these.
operationId: listRefundableCryptoDeposits
parameters:
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/IncludeRequested'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: Paginated list of the customer's refundable crypto deposits.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedRefundableCryptoDepositList'
'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
'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
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
IncludeRequested:
name: includeRequested
in: query
description: >-
Also list the deposits whose refund was already requested and has not
been credited yet. Omit it (the default) to list only the deposits a new
refund can be requested for. Any value other than `true` reads as
`false`.
required: false
schema:
type: boolean
default: false
example: true
Limit:
name: limit
in: query
description: Maximum number of items to return.
required: false
schema:
type: integer
minimum: 1
default: 100
example: 100
Offset:
name: offset
in: query
description: Starting point to limit the total items to return (for pagination).
required: false
schema:
type: integer
minimum: 0
example: 0
schemas:
PaginatedRefundableCryptoDepositList:
type: object
description: Paginated list of a customer's refundable crypto deposits.
properties:
count:
type: integer
description: Total number of deposits across all pages.
next:
type:
- string
- 'null'
format: uri
description: URL to the next page of results. Null if no next page.
previous:
type:
- string
- 'null'
format: uri
description: URL to the previous page of results. Null if no previous page.
results:
type: array
items:
$ref: '#/components/schemas/RefundableCryptoDeposit'
description: Array of refundable crypto deposits for the customer.
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
RefundableCryptoDeposit:
type: object
description: >-
A crypto deposit that arrived at one of your customers' deposit
addresses and matched no off-ramp order, so it can be returned on-chain.
It appears on no other listing — `GET /transactions/offramp/` is rooted
at orders, and this deposit has none.
properties:
depositId:
type: string
format: uuid
description: Identifier of the deposit, used to request its refund.
amount:
type: string
description: >-
Amount received, as the blockchain reported it. Not rounded — some
networks carry 18 decimals.
example: '12.5'
currency:
type: string
description: Ticker of the deposited asset. Case is significant.
example: USDC
network:
type: string
description: Network the crypto arrived on.
example: POLYGON
txnHash:
type: string
description: >-
Hash of the transfer that came **in** — how you recognise the
payment.
example: '0x9a3c1f7e5b2d84c06f1ab93e27d5c480f6b1e9a24c7d3058be41f92a6c8d7051'
refundedTxnHash:
type:
- string
- 'null'
description: >-
Hash of the transfer that went **back**, or `null` until the refund
completes. The only place this hash is available: the
`OFF-RAMP.DEPOSIT.REFUNDED` event carries the incoming hash, not
this one, and `latestRefund` has no hash field.
example: null
createdAt:
type: string
format: date-time
description: When the deposit was received.
refundDestinationRequired:
type:
- boolean
- 'null'
description: >-
Whether refunding this deposit requires naming a `refundAddress`.
`true` means it is **required** — unlike the order-rooted endpoint,
there is no order that could already carry one. `false` means the
crypto returns to the on-chain origin address and `refundAddress` is
rejected. `null` when the deposit is not in refund territory.
latestRefund:
anyOf:
- $ref: '#/components/schemas/LatestCryptoRefund'
- type: 'null'
description: >-
State of the most recent refund of this deposit, or `null` if there
never was one. On the default list it can only be a rejection,
because a deposit whose refund is under way is not listed. With
`?includeRequested=true` it also carries the states of a refund in
progress (`PENDING`, `PROCESSING`, `FAILED`), which is what tells
you whether the deposit can still be claimed or its refund is
already being resolved.
LatestCryptoRefund:
type: object
description: State of the most recent crypto refund of the order's deposit.
properties:
refundId:
type: string
format: uuid
description: Unique identifier of the refund.
status:
type: string
enum:
- PENDING
- PROCESSING
- COMPLETED
- REJECTED
- FAILED
description: >-
Current state of the refund: `PENDING` (registered, not yet sent to
the provider), `PROCESSING` (sent, awaiting confirmation),
`COMPLETED` (the money reached its destination), `REJECTED` (the
request was declined — see `rejectionReason` — and nothing was sent)
or `FAILED` / `CANCELLED` (the attempt did not go through; contact
Ripio support).
rejectionReason:
type: string
enum:
- ''
- DUPLICATE_REQUEST
- INVALID_DESTINATION
- ALREADY_RESOLVED
- NOT_ELIGIBLE
- CONTACT_SUPPORT
description: Why the request was declined. Empty unless `status` is `REJECTED`.
initiatedBy:
type: string
enum:
- PARTNER
- WIDGET
- OPS
description: >-
Which door the request came through: `PARTNER` (your API call),
`WIDGET` (the end user, from the widget) or `OPS` (registered by
Ripio's support team on the customer's behalf).
requestedAt:
type: string
format: date-time
description: When the refund was requested.
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 `.
````