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 collections

Request

Retrieves a list of collections using account-based routing, filterable by query parameters.

Security
Bearer
Query
idstring(uuid)

Filter collections by specific collection identifier

Example: id=e8d43598-107d-4694-9fb2-934e7484c3d4
payer_idstring(uuid)

Filter collections by payer identifier

Example: payer_id=0c5479ff-3772-4123-b2b7-e679e71eb570
account_idstring(uuid)

Filter collections by account identifier

Example: account_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890
beneficiary_idstring(uuid)

Filter collections by beneficiary identifier

Example: beneficiary_id=01467076-8bb0-41c1-ad54-5751dd4a9e80
sincestring(date-time)

ISO 8601 timestamp after collection was created

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

ISO 8601 timestamp before collection 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/api/collections/v1/collections/links?id=e8d43598-107d-4694-9fb2-934e7484c3d4&payer_id=0c5479ff-3772-4123-b2b7-e679e71eb570&account_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&beneficiary_id=01467076-8bb0-41c1-ad54-5751dd4a9e80&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 collections.

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

Pagination metadata.

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

Create a collection

Request

Creates a new payment link for a collection using account-based routing. The collection is associated with an account which determines the available payment rails and currency. The amount is denominated in the account's currency.

Security
Bearer
Bodyapplication/jsonrequired
payer_idstring(uuid)required

Unique identifier of the payer partner

Example: "0c5479ff-3772-4123-b2b7-e679e71eb570"
account_idstring(uuid)required

Unique identifier of the account to receive funds

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
amountstring^[0-9]+(\.[0-9]{1,8})?$required

Collection amount as a string to preserve precision

Example: "800.00"
fee_modestring

How fees are handled in the collection

Default "EXCLUDED"
Enum"INCLUDED""EXCLUDED"
Example: "EXCLUDED"
reference_idstring

External reference identifier for the collection

Example: "INV-2025-009"
descriptionstring

Human-readable description of the collection purpose

Example: "Payment for Order #2668"
link_expiryinteger[ 300 .. 2592000 ]required

Payment link expiry time in seconds from creation

Example: 172800
return_urlstring(uri)required

URL to redirect user after payment completion

Example: "https://example.com/payment/completion"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/links \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payer_id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "800.00",
    "fee_mode": "EXCLUDED",
    "reference_id": "INV-2025-009",
    "description": "Payment for Order #2668",
    "link_expiry": 172800,
    "return_url": "https://example.com/payment/completion"
  }'

Responses

Collection Created Successfully

Bodyapplication/json
idstring(uuid)required

Unique identifier for the collection

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

Payer partner details

payer.​idstring(uuid)required

Unique identifier for the payer partner

Example: "0c5479ff-3772-4123-b2b7-e679e71eb570"
payer.​namestringrequired

Full name of the payer partner

Example: "Nigerian Imports Ltd."
payer.​emailstring(email)required

Email address of the payer partner

Example: "nigerian@imports.com"
beneficiaryobjectrequired

Beneficiary partner details

beneficiary.​idstring(uuid)required

Unique identifier of the beneficiary partner

Example: "01467076-8bb0-41c1-ad54-5751dd4a9e80"
beneficiary.​namestringrequired

Full name of the beneficiary partner

Example: "Hong Kong Exports Ltd."
beneficiary.​emailstring(email)required

Email address of the beneficiary partner

Example: "hongkong@exports.com"
accountobjectrequired

Account associated to this collection, which funds will be routed to

account.​idstring(uuid)required

Unique identifier for the account

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
account.​beneficiary_idstring(uuid)required

Unique identifier of the beneficiary partner

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

Currency for the account

Example: "USD"
account.​typestringrequired

Type of account

Enum"FIAT""CRYPTO"
Example: "FIAT"
reference_idstring

External reference identifier for the collection

Example: "INV-2025-009"
gross_amountstringrequired

Total amount including fees

Example: "808.00"
net_amountstringrequired

Amount excluding buyer fees

Example: "800.00"
fee_modestring(FeeMode)required

How fees are handled in the collection

Enum"INCLUDED""EXCLUDED"
Example: "EXCLUDED"
feestringrequired

Fee amount charged for the collection

Example: "8.00"
amount_remainingstringrequired

Amount remaining for an incomplete payment

Example: "758.50"
descriptionstringrequired

Human-readable description of the collection purpose

Example: "Payment for Order #2668"
link_expiryintegerrequired

Payment link expiry time in seconds from creation

Example: 172800
return_urlstring(uri)required
Example: "https://example.com/payment/completion"
expires_atstring(date-time)required

ISO 8601 timestamp when the collection expires

Example: "2025-06-30T23:59:59Z"
transactionsArray of objects(TransactionV1)

List of transactions associated with this collection

payment_linkstring(uri)

URL for the payment interface

Example: "https://collections.ripple.com/link/pay/384c5f9b"
statusstring(CollectionStatus)required

The status of the collection

Enum"CREATED""CLOSED""HOLD""EXPIRED""PENDING""PROCESSING""COMPLETED""UNDERPAID""OVERPAID""CANCELLED"
Example: "PENDING"
reasonstring or null

Reason for current status (if applicable)

Example: null
created_atstring(date-time)required

ISO 8601 timestamp when the collection was created

Example: "2025-06-17T12:00:00Z"
updated_atstring(date-time)required

ISO 8601 timestamp when the collection was last updated

Example: "2025-06-17T12:30:00Z"
Response
application/json
{
  "id": "e8d43598-107d-4694-9fb2-934e7484c3d4",
  "payer": {
    "id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
    "name": "Nigerian Imports Ltd.",
    "email": "nigerian@imports.com"
  },
  "beneficiary": {
    "id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
    "name": "Hong Kong Exports Ltd.",
    "email": "hongkong@exports.com"
  },
  "reference_id": "INV-2025-009",
  "account": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
    "currency": "USDC",
    "type": "CRYPTO"
  },
  "gross_amount": "808.00",
  "net_amount": "800.00",
  "fee_mode": "EXCLUDED",
  "fee": "8.00",
  "amount_remaining": "808.00",
  "description": "Payment for Order #2668",
  "link_expiry": 172800,
  "return_url": "https://example.com/payment/completion",
  "expires_at": "2025-06-30T23:59:59Z",
  "transactions": [],
  "payment_link": "https://collections.ripple.com/link/pay/384c5f9b",
  "status": "CREATED",
  "reason": null,
  "created_at": "2025-06-17T12:00:00Z",
  "updated_at": "2025-06-17T12:30:00Z"
}

Get collection details

Request

Retrieves the details of a specific collection by its ID using account-based routing.

Security
Bearer
Path
collection_idstring(uuid)required

Unique identifier of the collection to retrieve

Example: e8d43598-107d-4694-9fb2-934e7484c3d4
curl -i -X GET \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/links/e8d43598-107d-4694-9fb2-934e7484c3d4 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
idstring(uuid)required

Unique identifier for the collection

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

Payer partner details

payer.​idstring(uuid)required

Unique identifier for the payer partner

Example: "0c5479ff-3772-4123-b2b7-e679e71eb570"
payer.​namestringrequired

Full name of the payer partner

Example: "Nigerian Imports Ltd."
payer.​emailstring(email)required

Email address of the payer partner

Example: "nigerian@imports.com"
beneficiaryobjectrequired

Beneficiary partner details

beneficiary.​idstring(uuid)required

Unique identifier of the beneficiary partner

Example: "01467076-8bb0-41c1-ad54-5751dd4a9e80"
beneficiary.​namestringrequired

Full name of the beneficiary partner

Example: "Hong Kong Exports Ltd."
beneficiary.​emailstring(email)required

Email address of the beneficiary partner

Example: "hongkong@exports.com"
accountobjectrequired

Account associated to this collection, which funds will be routed to

account.​idstring(uuid)required

Unique identifier for the account

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
account.​beneficiary_idstring(uuid)required

Unique identifier of the beneficiary partner

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

Currency for the account

Example: "USD"
account.​typestringrequired

Type of account

Enum"FIAT""CRYPTO"
Example: "FIAT"
reference_idstring

External reference identifier for the collection

Example: "INV-2025-009"
gross_amountstringrequired

Total amount including fees

Example: "808.00"
net_amountstringrequired

Amount excluding buyer fees

Example: "800.00"
fee_modestring(FeeMode)required

How fees are handled in the collection

Enum"INCLUDED""EXCLUDED"
Example: "EXCLUDED"
feestringrequired

Fee amount charged for the collection

Example: "8.00"
amount_remainingstringrequired

Amount remaining for an incomplete payment

Example: "758.50"
descriptionstringrequired

Human-readable description of the collection purpose

Example: "Payment for Order #2668"
link_expiryintegerrequired

Payment link expiry time in seconds from creation

Example: 172800
return_urlstring(uri)required
Example: "https://example.com/payment/completion"
expires_atstring(date-time)required

ISO 8601 timestamp when the collection expires

Example: "2025-06-30T23:59:59Z"
transactionsArray of objects(TransactionV1)

List of transactions associated with this collection

payment_linkstring(uri)

URL for the payment interface

Example: "https://collections.ripple.com/link/pay/384c5f9b"
statusstring(CollectionStatus)required

The status of the collection

Enum"CREATED""CLOSED""HOLD""EXPIRED""PENDING""PROCESSING""COMPLETED""UNDERPAID""OVERPAID""CANCELLED"
Example: "PENDING"
reasonstring or null

Reason for current status (if applicable)

Example: null
created_atstring(date-time)required

ISO 8601 timestamp when the collection was created

Example: "2025-06-17T12:00:00Z"
updated_atstring(date-time)required

ISO 8601 timestamp when the collection was last updated

Example: "2025-06-17T12:30:00Z"
Response
application/json
{
  "id": "e8d43598-107d-4694-9fb2-934e7484c3d4",
  "payer": {
    "id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
    "name": "Nigerian Imports Ltd.",
    "email": "nigerian@imports.com"
  },
  "beneficiary": {
    "id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
    "name": "Hong Kong Exports Ltd.",
    "email": "hongkong@exports.com"
  },
  "account": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "beneficiary_id": "291ecf34-a01d-466a-b0fd-662a88b7a1bb",
    "currency": "USD",
    "type": "FIAT"
  },
  "reference_id": "INV-2025-009",
  "gross_amount": "808.00",
  "net_amount": "800.00",
  "fee_mode": "EXCLUDED",
  "fee": "8.00",
  "amount_remaining": "758.50",
  "description": "Payment for Order #2668",
  "link_expiry": 172800,
  "return_url": "https://example.com/payment/completion",
  "expires_at": "2025-06-30T23:59:59Z",
  "transactions": [
    { … }
  ],
  "payment_link": "https://collections.ripple.com/link/pay/384c5f9b",
  "status": "PENDING",
  "reason": null,
  "created_at": "2025-06-17T12:00:00Z",
  "updated_at": "2025-06-17T12:30:00Z"
}

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