Ripple Collections (alpha) (0.0.1)
View as Markdown
Open this page as Markdown
Copy for LLM
Copy page as Markdown for LLMs
Open in Claude
Get insights from Claude
Open in ChatGPT
Get insights from ChatGPT

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 URL	Description
Sandbox	`https://docs.ripple.com/products/collections/_mock/api/collections`	Sandbox environment with mock data which does not require auth.
UAT	`https://api.test.ripple.com`	UAT environment with simulated transactions.
Production	`https://api.ripple.com`	Production environment

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

Download OpenAPI description

collections.json

collections.yaml

Servers

Mock server

https://docs.ripple.com/_mock/products/collections/v0/api/collections

https://api.test.ripple.com

https://api.ripple.com

Authentication

Endpoints for authentication

Operations

Collection Links

Endpoints for managing one-time collection links

Operations

Collection Channels

Endpoints for managing persistent collection channels

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).

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

Page size (items per page)

Default 10

Example: size=10

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/collections/v0/api/collections/v0/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(Settlement)

pageobject(PageMetadata)

Pagination metadata.

Response

application/json

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

Get settlement by ID

Request

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

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/v0/api/collections/v0/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"

feesstringrequired

Total fees applied to the settlement

Example: "0.50"

dataobjectrequired

Additional settlement data including account details

data.sending_accountobject(SettlementAccountDetails)

Account details for settlement transactions

data.receiving_accountobject(SettlementAccountDetails)

Account details for settlement transactions

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"

transactionsArray of objects(Transaction)required

List of transactions associated with this settlement

transactions[].idstring(uuid)required

Unique identifier for the transaction

Example: "487ba009-56cf-4ad9-8b5c-045e27893e00"

transactions[].parent_idstring(uuid)required

Identifier of the parent entity (collection link or channel) for this transaction

Example: "e8d43598-107d-4694-9fb2-934e7484c3d4"

transactions[].settlement_idstring or null(uuid)

Identifier of the settlement associated with this transaction. Null if the transaction has not been included in a settlement yet.

Example: "9f3e4d2c-1a5b-4c8e-9d7f-2e1a3b4c5d6e"

transactions[].payerobjectrequired

Payer partner details

transactions[].payer.idstring(uuid)required

Unique identifier for the payer partner

Example: "0c5479ff-3772-4123-b2b7-e679e71eb570"

transactions[].payer.namestringrequired

Full name of the payer partner

Example: "Nigerian Imports Ltd."

transactions[].payer.emailstring(email)required

Email address of the payer partner

Example: "nigerian@imports.com"

transactions[].beneficiaryobjectrequired

Beneficiary partner details

transactions[].beneficiary.idstring(uuid)required

Unique identifier of the beneficiary partner

Example: "01467076-8bb0-41c1-ad54-5751dd4a9e80"

transactions[].beneficiary.namestringrequired

Full name of the beneficiary partner

Example: "Hong Kong Exports Ltd."

transactions[].beneficiary.emailstring(email)required

Email address of the beneficiary partner

Example: "hongkong@exports.com"

transactions[].payment_amountobjectrequired

Crypto payment amount and asset

transactions[].payment_amount.valuestringrequired

Payment amount as a string to preserve precision

Example: "50.00000000"

transactions[].payment_amount.assetstringrequired

Crypto asset symbol of the payment

Example: "USDT"

transactions[].fiat_equivalentobjectrequired

Fiat equivalent amounts for payment, fee, and net

transactions[].fiat_equivalent.gross_amountobjectrequired

transactions[].fiat_equivalent.gross_amount.valuestringrequired

Gross amount in fiat

Example: "50.00"

transactions[].fiat_equivalent.gross_amount.currencystringrequired

Fiat currency code

Example: "USD"

transactions[].fiat_equivalent.fee_amountobjectrequired

transactions[].fiat_equivalent.fee_amount.valuestringrequired

Fee amount in fiat

Example: "0.50"

transactions[].fiat_equivalent.fee_amount.currencystringrequired

Fiat currency code

Example: "USD"

transactions[].fiat_equivalent.net_amountobjectrequired

transactions[].fiat_equivalent.net_amount.valuestringrequired

Net amount in fiat

Example: "49.50"

transactions[].fiat_equivalent.net_amount.currencystringrequired

Fiat currency code

Example: "USD"

transactions[].market_rateobjectrequired

Market rate reference for the transaction

transactions[].market_rate.basestring

Base currency for the exchange rate

Example: "USDT"

transactions[].market_rate.counterstring

Counter currency for the exchange rate

Example: "USD"

transactions[].market_rate.ratestring

Exchange rate from base to counter currency

Example: "1.00"

transactions[].exchange_rateobjectrequired

Exchange rate applied on the transaction

transactions[].exchange_rate.basestring

Base currency for the exchange rate

Example: "USDT"

transactions[].exchange_rate.counterstring

Counter currency for the exchange rate

Example: "USD"

transactions[].exchange_rate.ratestring

Exchange rate from base to counter currency

Example: "0.99"

transactions[].source_transaction_detailsobjectrequired

On-chain transaction details

transactions[].source_transaction_details.networkstring(Network)required

Supported blockchain networks

Enum"ETHEREUM""ETHEREUM_SEPOLIA_TESTNET""SOLANA""SOLANA_TESTNET""XRPL""XRPL_TESTNET"

Example: "ETHEREUM"

transactions[].source_transaction_details.transaction_hashstringrequired

Blockchain transaction hash

Example: "0x94365ftfr76iy45t6ghu876567ytr54ertyui987uyt698uyh87u"

transactions[].source_transaction_details.block_idstringrequired

Blockchain block identifier containing this transaction

Example: "0xh7865gugi87yea94e8267987a9e91eddcd0da916b22f3cfa0c8bd91dbad85"

transactions[].source_transaction_details.source_addressstringrequired

Blockchain address from which funds were sent

Example: "0x880f622a1933ACf82bFC5e630c9ab7f18eF47809"

transactions[].source_transaction_details.destination_addressstringrequired

Blockchain address to which funds were sent

Example: "0x02937b288b588058533C48b18EdFDdd76A324D6"

transactions[].source_transaction_details.gas_feeobjectrequired

Blockchain gas fee details

transactions[].source_transaction_details.gas_fee.valuestring

Gas fee value

Example: "0.0045"

transactions[].source_transaction_details.gas_fee.assetstring

Asset used to pay gas fee

Example: "ETH"

transactions[].statusstring(TransactionStatus)required

Transaction status

Enum"COMPLETED""FAILED_KYT""FAILED""HOLD_KYT""REFUNDED_KYT""PROCESSING"

Example: "COMPLETED"

transactions[].reasonstring or null

Reason for current status (if applicable)

Example: null

transactions[].transaction_processed_datestring(date-time)required

ISO 8601 timestamp of the transaction

Example: "2025-06-17T12:20:00Z"

transactions[].date_createdinteger(int64)required

Unix timestamp (milliseconds) when transaction was created

Example: 1566203005000

transactions[].date_confirmedinteger(int64)required

Unix timestamp (milliseconds) when transaction was confirmed on blockchain

Example: 1566203005000

statusstring(SettlementStatus)required

Settlement status

Enum"PENDING""PROCESSING""COMPLETED""FAILED""CANCELLED"

Example: "PENDING"

reasonstring or null

Reason for current status (if applicable)

Example: null

Response

application/json

{
  "id": "63dd59dd-88be-41a2-a246-2f6724209422",
  "type": "FIAT",
  "currency": "USD",
  "gross_amount": "50.00",
  "settlement_amount": "49.50",
  "fees": "0.50",
  "data": {
    "sending_account": { … },
    "receiving_account": { … },
    "transaction_reference_numbers": [ … ],
    "description": "Monthly Payout"
  },
  "transactions": [
    { … }
  ],
  "status": "PENDING",
  "reason": null
}

Transactions

Endpoints for viewing transactions across collection links and channels

Operations

Webhooks

Endpoints for managing webhook registrations

Operations

Ripple Collections (alpha) (0.0.1)
View as Markdown
Open this page as Markdown
Copy for LLM
Copy page as Markdown for LLMs
Open in Claude
Get insights from Claude
Open in ChatGPT
Get insights from ChatGPT

API Environments

Authentication

Collection Links

Collection Channels

Partners

Settlements

List settlements

Request

Responses

Was this page helpful?

Get settlement by ID

Request

Responses

Was this page helpful?

Transactions

Webhooks

Ripple Collections (alpha) (0.0.1)View as MarkdownView as MarkdownOpen this page as MarkdownCopy for LLMCopy page as Markdown for LLMsOpen in ClaudeGet insights from ClaudeOpen in ChatGPTGet insights from ChatGPT

API Environments

Authentication

Collection Links

Collection Channels

Partners

Settlements

List settlements

Request

Responses

Was this page helpful?

Get settlement by ID

Request

Responses

Was this page helpful?

Transactions

Webhooks

Ripple Collections (alpha) (0.0.1)
View as Markdown
Open this page as Markdown
Copy for LLM
Copy page as Markdown for LLMs
Open in Claude
Get insights from Claude
Open in ChatGPT
Get insights from ChatGPT