Skip to content

Ripple Collections (1.0.0)

The Ripple Collection APIs are used to manage collections, manage payment channels, manage partners and settlements.

API Environments

The Ripple Collection APIs offers the following environments:

Environment
Base URLDescription
Sandboxhttps://docs.ripple.com/products/collections/_mock/api/collectionsSandbox environment with mock data which does not require auth.
UAThttps://api.test.ripple.comUAT environment with simulated transactions.
Productionhttps://api.ripple.comProduction environment

For guides on API authentication, idempotency, and webhook verification, see the sidebar.

Download OpenAPI description
collections.json
collections.yaml
Languages
Servers
Mock server
https://docs.ripple.com/_mock/products/collections/api/collections
https://api.test.ripple.com
https://api.ripple.com

Authentication

Endpoints for authentication

Operations

Accounts

Endpoints for managing payment accounts

Operations

List accounts

Request

Retrieves a list of accounts, filterable by query parameters.

Security
Bearer
Query
idstring(uuid)

Filter accounts by specific account identifier

Example: id=a1b2c3d4-e5f6-7890-abcd-ef1234567890
account_owner_idstring(uuid)

Filter accounts by account owner identifier

Example: account_owner_id=291ecf34-a01d-466a-b0fd-662a88b7a1bb
currencystring

Filter accounts by currency

Example: currency=USD
typestring(AccountType)

Filter accounts by type

Enum"CRYPTO""FIAT"
Example: type=FIAT
statusstring(AccountStatus)

Filter accounts by status

Enum"PENDING""ACTIVE""INACTIVE""CLOSED"
Example: status=ACTIVE
pageinteger>= 1

Page number (starts at 1)

Default 1
Example: page=1
sizeinteger>= 1

Page size (items per page)

Default 10
Example: size=10
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/accounts?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&account_owner_id=291ecf34-a01d-466a-b0fd-662a88b7a1bb&currency=USD&type=FIAT&status=ACTIVE&page=1&size=10' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A list of accounts.

Bodyapplication/json
contentArray of objects(Account)
pageobject(PageMetadata)

Pagination metadata.

Response
application/json
{
  "content": [
    { … },
    { … },
    { … }
  ],
  "page": {
    "page": 1,
    "size": 10,
    "total_elements": 3,
    "total_pages": 1
  }
}

Create an account

Request

Creates a new payment account for a beneficiary partner. The account type (CRYPTO or FIAT) is determined by the currency specified. Account creation is subject to the beneficiary's partner eligibility.

Security
Bearer
Bodyapplication/jsonrequired
beneficiary_idstring(uuid)required

Unique identifier of the beneficiary partner who will own this account

Example: "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
currencystringrequired

Currency for the account (crypto: RLUSD, USDC, USDT or fiat: USD, BRL)

Example: "USD"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/accounts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
    "currency": "USDC"
  }'

Responses

Account created successfully.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the account

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
account_owner_idstring(uuid)required

Unique identifier of the account owner can be customer or partner

Example: "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
currencystringrequired

Currency for the account

Example: "USD"
typestring(AccountType)required

Type of account

Enum"CRYPTO""FIAT"
Example: "CRYPTO"
railsArray of strings(RailType)required

Available payment rail types for this account

Items Enum"BLOCKCHAIN""FEDWIRE""ACH""RTP""PIX"
Example: ["BLOCKCHAIN"]
balancesobjectrequired

Account balance information

balances.​availableobjectrequired

Available balance that can be withdrawn or used

balances.​available.​amountstringrequired

Available balance amount as a string to preserve precision

Example: "1250.50"
balances.​pendingobjectrequired

Pending balance information

balances.​pending.​inboundobjectrequired

Pending inbound balance

balances.​pending.​inbound.​amountstringrequired

Pending inbound amount as a string to preserve precision

Example: "50.00"
balances.​pending.​outboundobjectrequired

Pending outbound balance

balances.​pending.​outbound.​amountstringrequired

Pending outbound amount as a string to preserve precision

Example: "25.00"
ownership_levelstringrequired

Indicates whether this account is owned at the partner or customer level

Enum"PARTNER""CUSTOMER"
Example: "PARTNER"
statusstring(AccountStatus)required

Status of the account

Enum"PENDING""ACTIVE""INACTIVE""CLOSED"
Example: "ACTIVE"
created_atstring(date-time)required

ISO 8601 timestamp when the account was created

Example: "2025-09-18T22:54:00.542Z"
updated_atstring(date-time)required

ISO 8601 timestamp when the account was last updated

Example: "2025-09-18T22:54:00.542Z"
Response
application/json
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "account_owner_id": "87a6b830-1bbe-409c-9bff-9cf12bed774f",
  "currency": "USD",
  "type": "FIAT",
  "rails": [
    "FEDWIRE",
    "ACH",
    "RTP"
  ],
  "balances": {
    "available": { … },
    "pending": { … }
  },
  "ownership_level": "CUSTOMER",
  "status": "ACTIVE",
  "created_at": "2025-09-18T22:54:00.542Z",
  "updated_at": "2025-09-18T22:54:00.542Z"
}

Get account by ID

Request

Retrieves the details of a specific account by its ID.

Security
Bearer
Path
account_idstring(uuid)required

Unique identifier of the account to retrieve

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
curl -i -X GET \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
idstring(uuid)required

Unique identifier for the account

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
account_owner_idstring(uuid)required

Unique identifier of the account owner can be customer or partner

Example: "291ecf34-a01d-466a-b0fd-662a88b7a1bb"
currencystringrequired

Currency for the account

Example: "USD"
typestring(AccountType)required

Type of account

Enum"CRYPTO""FIAT"
Example: "CRYPTO"
railsArray of strings(RailType)required

Available payment rail types for this account

Items Enum"BLOCKCHAIN""FEDWIRE""ACH""RTP""PIX"
Example: ["BLOCKCHAIN"]
balancesobjectrequired

Account balance information

balances.​availableobjectrequired

Available balance that can be withdrawn or used

balances.​available.​amountstringrequired

Available balance amount as a string to preserve precision

Example: "1250.50"
balances.​pendingobjectrequired

Pending balance information

balances.​pending.​inboundobjectrequired

Pending inbound balance

balances.​pending.​inbound.​amountstringrequired

Pending inbound amount as a string to preserve precision

Example: "50.00"
balances.​pending.​outboundobjectrequired

Pending outbound balance

balances.​pending.​outbound.​amountstringrequired

Pending outbound amount as a string to preserve precision

Example: "25.00"
ownership_levelstringrequired

Indicates whether this account is owned at the partner or customer level

Enum"PARTNER""CUSTOMER"
Example: "PARTNER"
statusstring(AccountStatus)required

Status of the account

Enum"PENDING""ACTIVE""INACTIVE""CLOSED"
Example: "ACTIVE"
created_atstring(date-time)required

ISO 8601 timestamp when the account was created

Example: "2025-09-18T22:54:00.542Z"
updated_atstring(date-time)required

ISO 8601 timestamp when the account was last updated

Example: "2025-09-18T22:54:00.542Z"
Response
application/json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "account_owner_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
  "currency": "USD",
  "type": "CRYPTO",
  "rails": [
    "BLOCKCHAIN"
  ],
  "balances": {
    "available": { … },
    "pending": { … }
  },
  "ownership_level": "PARTNER",
  "status": "ACTIVE",
  "created_at": "2025-09-18T22:54:00.542Z",
  "updated_at": "2025-09-18T22:54:00.542Z"
}

List transactions for an account

Request

Retrieves a paginated list of transactions associated with a specific account. Replaces the embedded transactions array in channel/collection responses for better scalability and pagination support.

Security
Bearer
Path
account_idstring(uuid)required

Unique identifier of the account

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Query
statusstring(TransactionStatus)

Filter by transaction status

Enum"COMPLETED""FAILED_KYT""FAILED""HOLD_KYT""REFUNDED_KYT""PROCESSING"
Example: status=COMPLETED
sincestring(date-time)

ISO 8601 timestamp — return transactions created after this time

Example: since=2025-06-17T12:00:00Z
untilstring(date-time)

ISO 8601 timestamp — return transactions created before this time

Example: until=2025-06-17T12:00:00Z
pageinteger>= 1

Page number (starts at 1)

Default 1
Example: page=1
sizeinteger>= 1

Page size (items per page)

Default 10
Example: size=10
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/accounts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/transactions?status=COMPLETED&since=2025-06-17T12%3A00%3A00Z&until=2025-06-17T12%3A00%3A00Z&page=1&size=10' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A paginated list of transactions for the account.

Bodyapplication/json
dataArray of objects(TransactionV1)
pageobject
Response
application/json
{
  "data": [
    { … }
  ],
  "page": {
    "page": 0,
    "size": 0,
    "total_elements": 0,
    "total_pages": 0
  }
}

Collection Channels

Endpoints for managing persistent collection channels with account-based routing

Operations

Partners

Endpoints for managing partners who can transact

Operations

Settlements

Endpoints for managing settlements

Operations

Transactions

Endpoints for viewing transactions across collection links and channels with account-based routing

Operations

Webhooks

Endpoints for managing webhook registrations

Operations