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

Request an access token

Request

Request an access token for authentication with Ripple APIs.

You need to request a token for the environment you want to authenticate with.

Note: The length of the access token isn't fixed, hence it can vary. Avoid validating tokens based on character length.

Tutorials

Environments

EnvironmentDomainDescription
UATapi.test.ripple.comUAT environment with simulated transactions.
Productionapi.ripple.comProduction environment
Body
required
client_idstringrequired

The client ID associated with a specific set of API credentials.

Example: "{YOUR_CLIENT_ID}"
client_secretstringrequired

The client secret associated with a specific set of API credentials.

Example: "{YOUR_CLIENT_SECRET}"
audiencestringrequired

The value of the audience field is based on URN syntax.

Format: urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}

  • The first component is urn:ripplenetxcurrent-.
  • The second component refers to the environment you want to access.
  • The third component is your tenant ID. Ripple integration engineers provide this component during training.
EnvironmentEnvironment stringDescription
UATuatUAT environment with simulated transactions.
ProductionprodProduction environment for Ripple's internal services.

Example: urn:ripplexcurrent-uat:{YOUR_TENANT_ID}

Example: "urn:ripplexcurrent-uat:{YOUR_TENANT_ID}"
grant_typestringrequired

Set the grant-type for this client credentials request. This must be set to client_credentials.

Value"client_credentials"
Example: "client_credentials"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/collections/api/collections/v2/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-uat:{YOUR_TENANT_ID}",
    "grant_type": "client_credentials"
  }'

Responses

Returns the authentication response object that includes the token, type, scopes, and expiry.

Bodyapplication/json
access_tokenstring

The bearer token you use when authenticating with a Ripple API.

Example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ"
scopestring

List of scopes applied to your access_token.

expires_ininteger(int64)

How long your access_token is valid. You need to request a new token when it expires.

Example: 3600
token_typestring

The type of token. Ripple APIs use Bearer auth tokens.

Example: "Bearer"
Response
application/json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  "scope": "string",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Test access token

Request

Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.

Security
Bearer
curl -i -X GET \
  https://docs.ripple.com/_mock/products/collections/api/collections/v2/oauth/token/test \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

If a valid bearer token is supplied, the time remaining before the token expires is returned.

Bodyapplication/jsonArray [
messagestring
Example: "token_ok"
seconds_to_expiryinteger(int64)

Remaining time in seconds before the tested token expires.

Example: 3600
]
Response
application/json
[
  {
    "message": "token_ok",
    "seconds_to_expiry": 3600
  }
]

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