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

Transactions

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

Operations

Webhooks

Endpoints for managing webhook registrations

Operations

List webhooks

Request

Security
Bearer
Query
event_typestring(EventType)required

Unique identifier event type to filter webhooks

Enum"WEBHOOK_CREATED""WEBHOOK_UPDATED""WEBHOOK_DELETED""TRANSACTION_STATUS_CHANGED""PARTNER_STATUS_CHANGED""WALLET_ADDRESS_CREATED""WALLET_ADDRESS_ROTATED""SETTLEMENT_INITIATED""SETTLEMENT_COMPLETED""SETTLEMENT_FAILED"
Example: event_type=TRANSACTION_STATUS_CHANGED
sincestring(date-time)

ISO 8601 timestamp after webhook was created

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

ISO 8601 timestamp before webhook 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/webhooks?event_type=TRANSACTION_STATUS_CHANGED&since=2025-06-17T12%3A00%3A00Z&until=2025-06-17T12%3A00%3A00Z&page=1&size=10' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of webhooks for the customer and page requested

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

Pagination metadata.

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

Create webhooks

Request

Creates one webhook per event type supplied.

Security
Bearer
Bodyapplication/jsonrequired
callback_urlstring(uri)required

HTTPS URL to POST events to.

Example: "https://webhook.partner.example/webhooks"
event_typesArray of strings(EventType)non-emptyrequired
Items Enum"WEBHOOK_CREATED""WEBHOOK_UPDATED""WEBHOOK_DELETED""TRANSACTION_STATUS_CHANGED""PARTNER_STATUS_CHANGED""WALLET_ADDRESS_CREATED""WALLET_ADDRESS_ROTATED""SETTLEMENT_INITIATED""SETTLEMENT_COMPLETED""SETTLEMENT_FAILED"
Example: ["TRANSACTION_STATUS_CHANGED"]
curl -i -X POST \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/webhooks \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback_url": "https://webhook.partner.example/webhooks",
    "event_types": [
      "WALLET_ADDRESS_CREATED",
      "SETTLEMENT_COMPLETED"
    ]
  }'

Responses

Webhooks created (one per event type)

Bodyapplication/jsonArray [
idstring(uuid)required

Unique identifier for the webhook.

Example: "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
event_typestringrequired

Event type for which a webhook can be created.

Enum"WEBHOOK_CREATED""WEBHOOK_UPDATED""WEBHOOK_DELETED""TRANSACTION_STATUS_CHANGED""PARTNER_STATUS_CHANGED""WALLET_ADDRESS_CREATED""WALLET_ADDRESS_ROTATED""SETTLEMENT_INITIATED""SETTLEMENT_COMPLETED""SETTLEMENT_FAILED"
Example: "TRANSACTION_STATUS_CHANGED"
callback_urlstring(uri)required

HTTPS URL to which events will be sent.

Example: "https://webhook.partner.example/webhooks"
signature_verification_keystringrequired

Hex-encoded public key used to verify webhook signatures.

Example: "04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8"
]
Response
application/json
[
  {
    "id": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10",
    "event_type": "WALLET_ADDRESS_CREATED",
    "callback_url": "https://webhook.partner.example/webhooks",
    "signature_verification_key": "9abc1234..."
  },
  {
    "id": "1c9fe6fd-1dd8-4e9a-8de2-7f4c89b4d210",
    "event_type": "SETTLEMENT_COMPLETED",
    "callback_url": "https://webhook.partner.example/webhooks",
    "signature_verification_key": "1def5678..."
  }
]

Get a webhook

Request

Security
Bearer
Path
webhook_idstring(uuid)required

Unique identifier of the webhook to retrieve

Example: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
curl -i -X GET \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/webhooks/5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Webhook found

Bodyapplication/json
idstring(uuid)required

Unique identifier for the webhook.

Example: "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
event_typestringrequired

Event type for which a webhook can be created.

Enum"WEBHOOK_CREATED""WEBHOOK_UPDATED""WEBHOOK_DELETED""TRANSACTION_STATUS_CHANGED""PARTNER_STATUS_CHANGED""WALLET_ADDRESS_CREATED""WALLET_ADDRESS_ROTATED""SETTLEMENT_INITIATED""SETTLEMENT_COMPLETED""SETTLEMENT_FAILED"
Example: "TRANSACTION_STATUS_CHANGED"
callback_urlstring(uri)required

HTTPS URL to which events will be sent.

Example: "https://webhook.partner.example/webhooks"
signature_verification_keystringrequired

Hex-encoded public key used to verify webhook signatures.

Example: "04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8"
Response
application/json
{
  "id": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10",
  "event_type": "WALLET_ADDRESS_CREATED",
  "callback_url": "https://webhook.partner.example/webhooks",
  "signature_verification_key": "04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8"
}

Update a webhook

Request

Security
Bearer
Path
webhook_idstring(uuid)required

Unique identifier of the webhook to update

Example: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
Bodyapplication/jsonrequired
callback_urlstring(uri)required

HTTPS URL to POST events to.

Example: "https://webhook-updated.partner.example/webhooks"
curl -i -X PUT \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/webhooks/5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback_url": "https://webhook-updated.partner.example/webhooks"
  }'

Responses

Updated webhook id

Bodyapplication/json
idstring(uuid)required

Unique identifier for the webhook.

Example: "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"
event_typestringrequired

Event type for which a webhook can be created.

Enum"WEBHOOK_CREATED""WEBHOOK_UPDATED""WEBHOOK_DELETED""TRANSACTION_STATUS_CHANGED""PARTNER_STATUS_CHANGED""WALLET_ADDRESS_CREATED""WALLET_ADDRESS_ROTATED""SETTLEMENT_INITIATED""SETTLEMENT_COMPLETED""SETTLEMENT_FAILED"
Example: "TRANSACTION_STATUS_CHANGED"
callback_urlstring(uri)required

HTTPS URL to which events will be sent.

Example: "https://webhook.partner.example/webhooks"
signature_verification_keystringrequired

Hex-encoded public key used to verify webhook signatures.

Example: "04bfcabf3c3e5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8"
Response
application/json
{
  "id": "5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10",
  "event_type": "WALLET_ADDRESS_CREATED",
  "callback_url": "https://webhook-updated.partner.example/webhooks",
  "signature_verification_key": "1dec2311..."
}

Delete a webhook

Request

Security
Bearer
Path
webhook_idstring(uuid)required

Unique identifier of the webhook to retrieve

Example: 5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10
curl -i -X DELETE \
  https://docs.ripple.com/_mock/products/collections/api/collections/v1/collections/webhooks/5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Deleted webhook id

Bodyapplication/json
string(uuid)
Response
application/json
"5c0d9ec9-5ad8-4a43-a1b4-6f8f1f6c4c10"