Skip to content

Ripple Collections (alpha) (0.0.1)

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/v0/api/collections
https://api.test.ripple.com
https://api.ripple.com

Authentication

Endpoints for authentication

Operations

List collections

Request

Retrieves a list of collections, 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
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/v0/api/collections/v0/collections/links?id=e8d43598-107d-4694-9fb2-934e7484c3d4&payer_id=0c5479ff-3772-4123-b2b7-e679e71eb570&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(Collection)
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.

Security
Bearer
Bodyapplication/jsonrequired
payer_idstring(uuid)required

Unique identifier of the payer partner

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

Unique identifier of the beneficiary partner

Example: "01467076-8bb0-41c1-ad54-5751dd4a9e80"
amountstring^[0-9]+(\.[0-9]{1,8})?$required

Collection amount as a string to preserve precision

Example: "800.00"
currencystringrequired

Currency or asset symbol

Example: "USD"
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/v0/api/collections/v0/collections/links \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payer_id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
    "beneficiary_id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
    "amount": "800.00",
    "currency": "USD",
    "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"
reference_idstring

External reference identifier for the collection

Example: "INV-2025-009"
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"
gross_amountstringrequired

Total amount including fees

Example: "808.00"
net_amountstringrequired

Amount excluding buyer fees

Example: "800.00"
currencystringrequired

Currency or asset symbol

Example: "USD"
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(Transaction)

List of blockchain 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"
  },
  "reference_id": "INV-2025-009",
  "gross_amount": "808.00",
  "net_amount": "800.00",
  "currency": "USD",
  "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.

Security
Bearer
Path
collection_idstring(uuid)required

Unique identifier of the collection to retrieve

Example: 22a0337b-8e62-449c-91ca-a0f830c55733
curl -i -X GET \
  https://docs.ripple.com/_mock/products/collections/v0/api/collections/v0/collections/links/22a0337b-8e62-449c-91ca-a0f830c55733 \
  -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"
reference_idstring

External reference identifier for the collection

Example: "INV-2025-009"
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"
gross_amountstringrequired

Total amount including fees

Example: "808.00"
net_amountstringrequired

Amount excluding buyer fees

Example: "800.00"
currencystringrequired

Currency or asset symbol

Example: "USD"
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(Transaction)

List of blockchain 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": "22a0337b-8e62-449c-91ca-a0f830c55733",
  "payer": {
    "id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
    "name": "Nigerian Imports Ltd.",
    "email": "nigerian@imports.com"
  },
  "reference_id": "INV-2025-009",
  "beneficiary": {
    "id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
    "name": "Hong Kong Exports Ltd.",
    "email": "hongkong@exports.com"
  },
  "gross_amount": "800.00",
  "net_amount": "792.00",
  "currency": "USD",
  "fee_mode": "INCLUDED",
  "fee": "8.00",
  "amount_remaining": "750.50",
  "description": "Payment for Order #2670",
  "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"
}

Cancel a collection

Request

API to cancel a payment collection.

Security
Bearer
Bodyapplication/jsonrequired
idstring(uuid)required

Unique identifier of the collection to cancel

Example: "92e001a4-311a-4a63-ab2a-f050207c5283"
reasonstring

Optional reason for cancelling the collection

Example: "Collection cancelled"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/collections/v0/api/collections/v0/collections/links/cancel \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "92e001a4-311a-4a63-ab2a-f050207c5283",
    "reason": "Collection cancelled"
  }'

Responses

Collection cancelled 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"
reference_idstring

External reference identifier for the collection

Example: "INV-2025-009"
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"
gross_amountstringrequired

Total amount including fees

Example: "808.00"
net_amountstringrequired

Amount excluding buyer fees

Example: "800.00"
currencystringrequired

Currency or asset symbol

Example: "USD"
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(Transaction)

List of blockchain 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": "92e001a4-311a-4a63-ab2a-f050207c5283",
  "payer": {
    "id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
    "name": "Nigerian Imports Ltd.",
    "email": "nigerian@imports.com"
  },
  "reference_id": "INV-2025-009",
  "beneficiary": {
    "id": "01467076-8bb0-41c1-ad54-5751dd4a9e80",
    "name": "Hong Kong Exports Ltd.",
    "email": "hongkong@exports.com"
  },
  "gross_amount": "800.00",
  "net_amount": "792.00",
  "currency": "USD",
  "fee_mode": "INCLUDED",
  "fee": "8.00",
  "amount_remaining": "800.00",
  "description": "Payment for Order #2669",
  "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/124c5f9b",
  "status": "CANCELLED",
  "reason": "Collection cancelled",
  "created_at": "2025-06-17T12:00:00Z",
  "updated_at": "2025-06-17T12:30:00Z"
}

Collection Channels

Endpoints for managing persistent collection channels

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

Operations

Webhooks

Endpoints for managing webhook registrations

Operations