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

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

List settlements

Request

API to fetch first party payouts (settlements) with enhanced v1 response format.

Security
Bearer
Query
idstring(uuid)

Filter settlements by specific settlement ID

Example: id=63dd59dd-88be-41a2-a246-2f6724209422
typestring(SettlementType)

Settlement type

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

Settlement status

Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
Example: status=PENDING
sincestring(date-time)

ISO 8601 timestamp after settlement was created

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

ISO 8601 timestamp before settlement was created

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

Page number (starts at 1)

Default 1
Example: page=1
sizeinteger[ 1 .. 100 ]

Number of settlements per page

Default 10
Example: size=10
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/settlements?id=63dd59dd-88be-41a2-a246-2f6724209422&type=FIAT&status=PENDING&since=2025-06-17T12%3A00%3A00Z&until=2025-06-17T12%3A00%3A00Z&page=1&size=10' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A list of settlements.

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

Pagination metadata.

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

Create a settlement

Request

API to initiate a first party payout (settlement to our customer).

Security
Bearer
Bodyapplication/jsonrequired
source_account_idstring(uuid)required

Source customer account ID for the settlement

Example: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
amountstringrequired

Amount for the settlement

Example: "100.00"
currencystringrequired

Currency for the settlement

Example: "USD"
networkstring

Network for crypto settlements (only applicable when type is CRYPTO)

curl -i -X POST \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/settlements \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": "100.00",
    "currency": "USD",
    "network": "string"
  }'

Responses

Settlement created successfully.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the settlement

Example: "63dd59dd-88be-41a2-a246-2f6724209422"
typestring(SettlementType)required

Settlement type

Enum"FIAT""CRYPTO"
Example: "FIAT"
currencystringrequired

Currency code for the settlement

Example: "USD"
gross_amountstringrequired

Total settlement amount before fees

Example: "50.00"
settlement_amountstringrequired

Net settlement amount after fees

Example: "49.50"
feesobjectrequired

Settlement fees

fees.​transaction_feesstring

Total fees applied to the settlement

Example: "0.50"
statusstring(SettlementStatus)required

Settlement status

Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
Example: "PENDING"
dataany(SettlementDataV1)required

Settlement data - varies based on settlement type (FIAT or CRYPTO)

data.​typestringrequired

Discriminator for fiat settlement data

Value"FIAT"
Example: "FIAT"
Discriminator
data.​sending_accountobject(SettlementAccountDetails)required

Account details for settlement transactions

data.​sending_account.​account_holderstringrequired

Full name of the account holder

Example: "John Doe"
data.​sending_account.​institution_namestringrequired

Name of the financial institution

Example: "Bank of America"
data.​sending_account.​account_numberstringrequired

Account number for the settlement

Example: "XXXX6789"
data.​sending_account.​routing_numberstringrequired

Routing number for the financial institution

Example: "XXXX4321"
data.​receiving_accountobject(SettlementAccountDetails)required

Account details for settlement transactions

data.​receiving_account.​account_holderstringrequired

Full name of the account holder

Example: "John Doe"
data.​receiving_account.​institution_namestringrequired

Name of the financial institution

Example: "Bank of America"
data.​receiving_account.​account_numberstringrequired

Account number for the settlement

Example: "XXXX6789"
data.​receiving_account.​routing_numberstringrequired

Routing number for the financial institution

Example: "XXXX4321"
data.​transaction_reference_numbersArray of strings

Bank reference numbers for the settlement transaction

Example: ["ABC12345"]
data.​descriptionstring

Human-readable description of the settlement

Example: "Monthly Payout"
settlement_transactionsArray of objects(SettlementTransactionV1)required

List of settlement transactions

settlement_transactions[].​idstring(uuid)required

Unique identifier of the settlement transaction

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
settlement_transactions[].​account_idstring(uuid)required

Account ID associated with this settlement transaction

Example: "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
settlement_transactions[].​market_rateobject

Market rate at the time of settlement

settlement_transactions[].​exchange_rateobject

Exchange rate from base to counter currency

settlement_transactions[].​amountstring^[0-9]+(\.[0-9]{1,8})?$required
Example: "49.50"
Response
application/json
{
  "id": "63dd59dd-88be-41a2-a246-2f6724209422",
  "type": "FIAT",
  "currency": "USD",
  "gross_amount": "50.00",
  "settlement_amount": "49.50",
  "fees": {
    "transaction_fees": "0.50"
  },
  "status": "PENDING",
  "data": {
    "type": "FIAT",
    "sending_account": { … },
    "receiving_account": { … },
    "transaction_reference_numbers": [ … ],
    "description": "Monthly Payout"
  },
  "settlement_transactions": [
    { … }
  ]
}

Get settlement by ID

Request

API to fetch a first party payout (settlement to our customer) with enhanced v1 response format.

Security
Bearer
Path
settlement_idstring(uuid)required

Unique identifier of the settlement to retrieve

Example: 63dd59dd-88be-41a2-a246-2f6724209422
curl -i -X GET \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/settlements/63dd59dd-88be-41a2-a246-2f6724209422 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response.

Bodyapplication/json
idstring(uuid)required

Unique identifier for the settlement

Example: "63dd59dd-88be-41a2-a246-2f6724209422"
typestring(SettlementType)required

Settlement type

Enum"FIAT""CRYPTO"
Example: "FIAT"
currencystringrequired

Currency code for the settlement

Example: "USD"
gross_amountstringrequired

Total settlement amount before fees

Example: "50.00"
settlement_amountstringrequired

Net settlement amount after fees

Example: "49.50"
feesobjectrequired

Settlement fees

fees.​transaction_feesstring

Total fees applied to the settlement

Example: "0.50"
statusstring(SettlementStatus)required

Settlement status

Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"
Example: "PENDING"
dataany(SettlementDataV1)required

Settlement data - varies based on settlement type (FIAT or CRYPTO)

data.​typestringrequired

Discriminator for fiat settlement data

Value"FIAT"
Example: "FIAT"
Discriminator
data.​sending_accountobject(SettlementAccountDetails)required

Account details for settlement transactions

data.​sending_account.​account_holderstringrequired

Full name of the account holder

Example: "John Doe"
data.​sending_account.​institution_namestringrequired

Name of the financial institution

Example: "Bank of America"
data.​sending_account.​account_numberstringrequired

Account number for the settlement

Example: "XXXX6789"
data.​sending_account.​routing_numberstringrequired

Routing number for the financial institution

Example: "XXXX4321"
data.​receiving_accountobject(SettlementAccountDetails)required

Account details for settlement transactions

data.​receiving_account.​account_holderstringrequired

Full name of the account holder

Example: "John Doe"
data.​receiving_account.​institution_namestringrequired

Name of the financial institution

Example: "Bank of America"
data.​receiving_account.​account_numberstringrequired

Account number for the settlement

Example: "XXXX6789"
data.​receiving_account.​routing_numberstringrequired

Routing number for the financial institution

Example: "XXXX4321"
data.​transaction_reference_numbersArray of strings

Bank reference numbers for the settlement transaction

Example: ["ABC12345"]
data.​descriptionstring

Human-readable description of the settlement

Example: "Monthly Payout"
settlement_transactionsArray of objects(SettlementTransactionV1)required

List of settlement transactions

settlement_transactions[].​idstring(uuid)required

Unique identifier of the settlement transaction

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
settlement_transactions[].​account_idstring(uuid)required

Account ID associated with this settlement transaction

Example: "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
settlement_transactions[].​market_rateobject

Market rate at the time of settlement

settlement_transactions[].​exchange_rateobject

Exchange rate from base to counter currency

settlement_transactions[].​amountstring^[0-9]+(\.[0-9]{1,8})?$required
Example: "49.50"
Response
application/json
{
  "id": "63dd59dd-88be-41a2-a246-2f6724209422",
  "type": "FIAT",
  "currency": "USD",
  "gross_amount": "50.00",
  "settlement_amount": "49.50",
  "fees": {
    "transaction_fees": "0.50"
  },
  "status": "PENDING",
  "data": {
    "type": "FIAT",
    "sending_account": { … },
    "receiving_account": { … },
    "transaction_reference_numbers": [ … ],
    "description": "Monthly Payout"
  },
  "settlement_transactions": [
    { … }
  ]
}

Transactions

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

Operations

Webhooks

Endpoints for managing webhook registrations

Operations