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

Collection Channels

Endpoints for managing persistent collection channels

Operations

Partners

Endpoints for managing partners who can transact

Operations

List partners

Request

Retrieves a list of partners, filterable by ID or type.

Security
Bearer
Query
idstring(uuid)

Filter partners by specific partner ID

Example: id=0c5479ff-3772-4123-b2b7-e679e71eb570
sincestring(date-time)

ISO 8601 timestamp after partner was created

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

ISO 8601 timestamp before partner was created

Example: until=2025-06-17T12:00:00Z
typestring(PartnerType)

Filter partners by type

Enum"BUSINESS""INDIVIDUAL"
Example: type=BUSINESS
statusstring(PartnerStatus)

Filter partners by status

Enum"PENDING""ON_HOLD""FAILED""ACTIVATED""DEACTIVATED"
Example: status=PENDING
external_reference_idstring

External reference id for partner

Example: external_reference_id=Ref-123
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/partners?id=0c5479ff-3772-4123-b2b7-e679e71eb570&since=2025-06-17T12%3A00%3A00Z&until=2025-06-17T12%3A00%3A00Z&type=BUSINESS&status=PENDING&external_reference_id=Ref-123&page=1&size=10' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

A list of partners.

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

Pagination metadata.

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

Create a partner

Request

This API allows users to add new parties who can transact.

Security
Bearer
Bodyapplication/jsonrequired
namestringrequired

Full name of the partner organization or individual

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

Email address for partner communications

Example: "nigerian@imports.com"
external_reference_idstring

External reference id for partner

Example: "Ref-123"
dataobject(PartnerMetadata)
curl -i -X POST \
  https://docs.ripple.com/_mock/products/collections/v0/api/collections/v0/collections/partners \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Nigerian Imports Ltd.",
    "email": "nigerian@imports.com",
    "external_reference_id": "Ref-123",
    "data": {
      "type": "BUSINESS",
      "legal_entity": "Nigerian Imports Ltd.",
      "registration_number": "RC-123456-NGR",
      "registration_type": "AIIN",
      "country": "NG",
      "city": "Lagos Island",
      "postal_code": "10010",
      "address": "15 Marina Street",
      "address_line_2": "Suite 200"
    }
  }'

Responses

Partner created successfully.

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the partner

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

Full name of the partner organization or individual

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

Email address for partner communications

Example: "nigerian@imports.com"
external_reference_idstring

External reference id for partner

Example: "Ref-123"
dataobject(PartnerMetadata)
statusstring(PartnerStatus)required

Partner status for collection links or channels

Enum"PENDING""ON_HOLD""FAILED""ACTIVATED""DEACTIVATED"
Example: "PENDING"
reasonstring or null

Reason for current status (if applicable)

Example: null
created_atstring(date-time)read-onlyrequired

Timestamp when the partner was created

Example: "2025-09-18T22:54:00.542Z"
updated_atstring(date-time)read-onlyrequired

Timestamp when the partner was last updated

Example: "2025-09-18T23:54:00.542Z"
Response
application/json
{
  "id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
  "name": "Nigerian Imports Ltd.",
  "email": "nigerian@imports.com",
  "external_reference_id": "Ref-123",
  "data": {
    "type": "BUSINESS",
    "legal_entity": "Nigerian Imports Ltd.",
    "registration_number": "RC-123456-NGR",
    "registration_type": "AIIN",
    "country": "NG",
    "city": "Lagos Island",
    "postal_code": "10010",
    "address": "15 Marina Street",
    "address_line_2": "Suite 200"
  },
  "status": "PENDING",
  "reason": null,
  "created_at": "2025-09-18T22:54:00.542Z",
  "updated_at": "2025-09-18T23:54:00.542Z"
}

Get partner by ID

Request

This API allows users to retrieve a specific partner by their ID.

Security
Bearer
Path
partner_idstring(uuid)required

Unique identifier of the partner to retrieve

Example: 0c5479ff-3772-4123-b2b7-e679e71eb570
Query
external_reference_idstring

External reference id for partner

Example: external_reference_id=Ref-123
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/collections/v0/api/collections/v0/collections/partners/0c5479ff-3772-4123-b2b7-e679e71eb570?external_reference_id=Ref-123' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the partner

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

Full name of the partner organization or individual

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

Email address for partner communications

Example: "nigerian@imports.com"
external_reference_idstring

External reference id for partner

Example: "Ref-123"
dataobject(PartnerMetadata)
statusstring(PartnerStatus)required

Partner status for collection links or channels

Enum"PENDING""ON_HOLD""FAILED""ACTIVATED""DEACTIVATED"
Example: "PENDING"
reasonstring or null

Reason for current status (if applicable)

Example: null
created_atstring(date-time)read-onlyrequired

Timestamp when the partner was created

Example: "2025-09-18T22:54:00.542Z"
updated_atstring(date-time)read-onlyrequired

Timestamp when the partner was last updated

Example: "2025-09-18T23:54:00.542Z"
Response
application/json
{
  "id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
  "name": "Nigerian Imports Ltd.",
  "email": "nigerian@imports.com",
  "external_reference_id": "Ref-123",
  "data": {
    "type": "BUSINESS",
    "legal_entity": "Nigerian Imports Ltd.",
    "registration_number": "RC-123456-NGR",
    "registration_type": "AIIN",
    "country": "NG",
    "city": "Lagos Island",
    "postal_code": "10010",
    "address": "15 Marina Street",
    "address_line_2": "Suite 200"
  },
  "status": "PENDING",
  "reason": null,
  "created_at": "2025-09-18T22:54:00.542Z",
  "updated_at": "2025-09-18T23:54:00.542Z"
}

Update a partner

Request

API to update a partner to use in collections API.

Security
Bearer
Path
partner_idstring(uuid)required

Unique identifier of the partner to update

Example: 0c5479ff-3772-4123-b2b7-e679e71eb570
Bodyapplication/jsonrequired
namestring

Full name of the partner organization or individual

Example: "Nigerian Imports Ltd."
emailstring(email)

Email address for partner communications

Example: "nigerian@imports.com"
external_reference_idstring

External reference id for partner

Example: "Ref-123"
dataobject(PartnerMetadata)
curl -i -X PUT \
  https://docs.ripple.com/_mock/products/collections/v0/api/collections/v0/collections/partners/0c5479ff-3772-4123-b2b7-e679e71eb570 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Nigerian Imports Ltd.",
    "email": "nigerian@imports.com",
    "external_reference_id": "Ref-123",
    "data": {
      "type": "BUSINESS",
      "legal_entity": "Nigerian Imports Ltd.",
      "registration_number": "RC-123456-NGR",
      "registration_type": "AIIN",
      "country": "NG",
      "city": "Lagos Island",
      "postal_code": "10010",
      "address": "15 Marina Street",
      "address_line_2": "Suite 200"
    }
  }'

Responses

Partner updated successfully.

Bodyapplication/json
idstring(uuid)read-onlyrequired

Unique identifier for the partner

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

Full name of the partner organization or individual

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

Email address for partner communications

Example: "nigerian@imports.com"
external_reference_idstring

External reference id for partner

Example: "Ref-123"
dataobject(PartnerMetadata)
statusstring(PartnerStatus)required

Partner status for collection links or channels

Enum"PENDING""ON_HOLD""FAILED""ACTIVATED""DEACTIVATED"
Example: "PENDING"
reasonstring or null

Reason for current status (if applicable)

Example: null
created_atstring(date-time)read-onlyrequired

Timestamp when the partner was created

Example: "2025-09-18T22:54:00.542Z"
updated_atstring(date-time)read-onlyrequired

Timestamp when the partner was last updated

Example: "2025-09-18T23:54:00.542Z"
Response
application/json
{
  "id": "0c5479ff-3772-4123-b2b7-e679e71eb570",
  "name": "Nigerian Imports Ltd.",
  "email": "nigerian@imports.com",
  "external_reference_id": "Ref-123",
  "data": {
    "type": "BUSINESS",
    "legal_entity": "Nigerian Imports Ltd.",
    "registration_number": "RC-123456-NGR",
    "registration_type": "AIIN",
    "country": "NG",
    "city": "Lagos Island",
    "postal_code": "10010",
    "address": "15 Marina Street",
    "address_line_2": "Suite 200"
  },
  "status": "PENDING",
  "reason": null,
  "created_at": "2025-09-18T22:54:00.542Z",
  "updated_at": "2025-09-18T23:54:00.542Z"
}

Settlements

Endpoints for managing settlements

Operations

Transactions

Endpoints for viewing transactions across collection links and channels

Operations

Webhooks

Endpoints for managing webhook registrations

Operations