# Ripple Collections

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:
| <div style="width:90px">Environment</div>  | Base URL                      | Description                               |
| ------------------------------------------ | ----------------------------- | ----------------------------------------- |
| Sandbox                                    | `https://docs.ripple.com/products/collections/_mock/api/collections` | Sandbox environment with mock data which does not require auth.|
| UAT                                       | `https://api.test.ripple.com` | UAT environment with simulated transactions. |
| Production                                 | `https://api.ripple.com`      | Production environment                    |

For guides on API authentication, idempotency, and webhook verification, see the sidebar. 

Version: 1.0.0

## Servers

```
https://api.test.ripple.com
```

```
https://api.ripple.com
```

## Security

### Bearer

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Ripple Collections](https://docs.ripple.com/_bundle/products/collections/@v1/api/collections.yaml)

## Authentication

Endpoints for authentication

### Request an access token

 - [POST /v2/oauth/token](https://docs.ripple.com/products/collections/api/collections/authentication/authenticate.md): 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

* Learn how to Request an access token.

#### Environments

| Environment | Domain | Description |
| --- | --- | --- |
| UAT | api.test.ripple.com | UAT environment with simulated transactions. |
| Production | api.ripple.com | Production environment |

### Test access token

 - [GET /v2/oauth/token/test](https://docs.ripple.com/products/collections/api/collections/authentication/testauthtoken.md): Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.

## Accounts

Endpoints for managing payment accounts

### List accounts

 - [GET /v1/collections/accounts](https://docs.ripple.com/products/collections/api/collections/accounts/listaccountsv1.md): Retrieves a list of accounts, filterable by query parameters.

### Create an account

 - [POST /v1/collections/accounts](https://docs.ripple.com/products/collections/api/collections/accounts/createaccountv1.md): Creates a new payment account for a beneficiary partner. The account type (CRYPTO or FIAT)
is determined by the currency specified. Account creation is subject to the beneficiary's
partner eligibility.

### Get account by ID

 - [GET /v1/collections/accounts/{account_id}](https://docs.ripple.com/products/collections/api/collections/accounts/getaccountbyidv1.md): Retrieves the details of a specific account by its ID.

### List transactions for an account

 - [GET /v1/collections/accounts/{account_id}/transactions](https://docs.ripple.com/products/collections/api/collections/accounts/listtransactionsbyaccountidv1.md): Retrieves a paginated list of transactions associated with a specific account. Replaces the embedded transactions array in channel/collection responses for better scalability and pagination support.

## Collection Links

Endpoints for managing one-time collection links with account-based routing

### List collections

 - [GET /v1/collections/links](https://docs.ripple.com/products/collections/api/collections/collection-links/listcollectionsv1.md): Retrieves a list of collections using account-based routing, filterable by query parameters.

### Create a collection

 - [POST /v1/collections/links](https://docs.ripple.com/products/collections/api/collections/collection-links/createcollectionv1.md): 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.

### Get collection details

 - [GET /v1/collections/links/{collection_id}](https://docs.ripple.com/products/collections/api/collections/collection-links/getcollectionbyidv1.md): Retrieves the details of a specific collection by its ID using account-based routing.

## Collection Channels

Endpoints for managing persistent collection channels with account-based routing

### List channels

 - [GET /v1/collections/channels](https://docs.ripple.com/products/collections/api/collections/collection-channels/listchannelsv1.md): Retrieves a list of channels using account-based routing, filterable by query parameters.

### Create a channel

 - [POST /v1/collections/channels](https://docs.ripple.com/products/collections/api/collections/collection-channels/createchannelv1.md): Creates a new payment channel using account-based routing. The channel is associated
with an account which determines the available payment rails (crypto networks or fiat
rails) based on the account's currency.

### Get channel details

 - [GET /v1/collections/channels/{channel_id}](https://docs.ripple.com/products/collections/api/collections/collection-channels/getchannelbyidv1.md): Retrieves the details of a specific channel by its ID using account-based routing.

## Partners

Endpoints for managing partners who can transact

### List partners

 - [GET /v1/collections/partners](https://docs.ripple.com/products/collections/api/collections/partners/listpartnersv1.md): Retrieves a list of partners, filterable by ID or type.

### Create a partner

 - [POST /v1/collections/partners](https://docs.ripple.com/products/collections/api/collections/partners/createpartnerv1.md): This API allows users to add new parties who can transact.

### Get partner by ID

 - [GET /v1/collections/partners/{partner_id}](https://docs.ripple.com/products/collections/api/collections/partners/getpartnerbyidv1.md): This API allows users to retrieve a specific partner by their ID.

### Update a partner

 - [PUT /v1/collections/partners/{partner_id}](https://docs.ripple.com/products/collections/api/collections/partners/updatepartnerv1.md): API to update a partner to use in collections API.

## Settlements

Endpoints for managing settlements

### List settlements

 - [GET /v1/collections/settlements](https://docs.ripple.com/products/collections/api/collections/settlements/listsettlementsv1.md): API to fetch first party payouts (settlements) with enhanced v1 response format.

### Create a settlement

 - [POST /v1/collections/settlements](https://docs.ripple.com/products/collections/api/collections/settlements/createsettlementv1.md): API to initiate a first party payout (settlement to our customer).

### Get settlement by ID

 - [GET /v1/collections/settlements/{settlement_id}](https://docs.ripple.com/products/collections/api/collections/settlements/getsettlementbyidv1.md): API to fetch a first party payout (settlement to our customer) with enhanced v1 response format.

## Transactions

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

### List Transactions

 - [GET /v1/collections/transactions](https://docs.ripple.com/products/collections/api/collections/transactions/listtransactionsv1.md): API to fetch transactions across collection links or channels using account-based routing.

### Get transaction by ID

 - [GET /v1/collections/transactions/{transaction_id}](https://docs.ripple.com/products/collections/api/collections/transactions/gettransactionbyidv1.md): API to fetch a transaction (payment from a payer to beneficiary) using account-based routing.

## Webhooks

Endpoints for managing webhook registrations

### List webhooks

 - [GET /v1/collections/webhooks](https://docs.ripple.com/products/collections/api/collections/webhooks/listwebhooks.md)

### Create webhooks

 - [POST /v1/collections/webhooks](https://docs.ripple.com/products/collections/api/collections/webhooks/createwebhooks.md): Creates one webhook per event type supplied.

### Get a webhook

 - [GET /v1/collections/webhooks/{webhook_id}](https://docs.ripple.com/products/collections/api/collections/webhooks/getwebhook.md)

### Update a webhook

 - [PUT /v1/collections/webhooks/{webhook_id}](https://docs.ripple.com/products/collections/api/collections/webhooks/updatewebhook.md)

### Delete a webhook

 - [DELETE /v1/collections/webhooks/{webhook_id}](https://docs.ripple.com/products/collections/api/collections/webhooks/deletewebhook.md)