# Payments Direct 1.0 API
Use the {% $env.PUBLIC_VAR_RPD %} 1.0 API to get quotes, create and manage payments, and manage originator and beneficiary identities.
## API environments
The {% $env.PUBLIC_VAR_RPD %} 1.0 API offers the following environments:
| Environment
| Base URL |
| --- | --- |
| Test | `https://{customer-name}.test.rnc.ripplenet.com/v4` |
| Production | `https://{customer-name}.rnc.ripplenet.com/v4` |
## Base URL
The base URL for the {% $env.PUBLIC_VAR_RPD %} 1.0 API follows the `{domainprefix}.{domain}` pattern. For the test environment, the `{domainprefix}` is `{customername}.test`. For the production environment, the {`domainprefix}` is `{customername}`.
**Note**: The following examples use `aperture` as the customer name, your customer name will be different.
#### URL format
This is the URL format for the {% $env.PUBLIC_VAR_RPD %} 1.0 API.
```plaintext
https://{domainprefix}.{domain}/v4
```
#### Example base URL
This is an example base URL for the {% $env.PUBLIC_VAR_RPD %} 1.0 API.
```plaintext
https://aperture.test.rnc.ripplenet.com/v4/{path}?{parameters}
```
#### Example fully-qualified URL
This connects to the test environment and requests a list of payments with 100 results per page.
```plaintext
https://aperture.test.rnc.ripplenet.com/v4/payments?page=0&size=100
```
| Environment | Domain Prefix
| Domain | Base URL |
| --- | --- | --- | --- |
| Test | `aperture.test.rnc` | `ripplenet.com`| `https://aperture.test.rnc.ripplenet.com/v4` |
| Production | `aperture.rnc` | `ripplenet.com`| `https://aperture.rnc.ripplenet.com/v4` |
## API authentication
All {% $env.PUBLIC_VAR_RPD %} 1.0 API operations require a Bearer access token specific to the environment you're using. Ripple provides a secure model for authentication and authorization by providing access tokens scoped for a set of credentials.
### Generate client ID and client secret
You will need your _client ID_ and _client secret_ to obtain an access token.
If you do not already have your client ID and client secret, do the following:
1. Log into the Ripple Payments UI.
2. In the left navigation menu, click **Settings**.
3. Under **Administration**, click **API Credentials**.
4. In the dropdown list next to the page title, select the access environment. For example, to provision credentials for the test environment, select **Test** from the dropdown list.
5. In the upper right corner of the page, click **New Credential**.
6. Click **Save and Generate Key**.
**Caution:** The *client secret* is displayed only once when you are creating new credentials. You cannot retrieve the secret after exiting this page. Copy and store the client secret securely and share it with authorized individuals in accordance with your organization's security policy.
You can now use the client ID and client secret to generate access tokens using the [Request an access token](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/authentication/authenticate) operation.
### Request an access token
To get an access token, use the [Request an access token](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/authentication/authenticate) operation with your `client_id` and `client_secret`. The response contains a token in the `access_token` field.
We recommend rotating your API credentials at regular intervals according to your organization's security policy.
**Note**: Authentication tokens are not a fixed length and can vary, avoid validating tokens based on character length.
## Security
### Bearer
Type: http
Scheme: bearer
Bearer Format: JWT
### BasicAuth
Type: http
Scheme: basic
### oauth2
Type: oauth2
## Download OpenAPI description
[Payments Direct 1.0 API](https://docs.ripple.com/_bundle/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api.yaml)
## Authentication
Use these API operations to manage your authentication tokens.
| Operation | Method | Description |
| --- | --- | --- |
| [Request an access token](#operation/authenticate) | POST | Request an access token for authentication with Ripple APIs. |
| [Test access token](#operation/testAuthToken) | GET | Test if an access token can be used for authentication. |
### Request an access token
- [POST /oauth/token](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/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.
#### Environments
| Environment | Domain | Description |
| --- | --- | --- |
| Test | auth-test.rnc.ripplenet.com | Test environment with simulated partners and simulated currency. |
| Production | auth.rnc.ripplenet.com | Production environment for Ripple's internal services. |
### Test access token
- [GET /oauth/token/test](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/authentication/testauthtoken.md): Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.
## Identities
Use these API operations to manage your identities.
| Operation | Method | Description |
| --- | --- | --- |
| [List identities](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/getidentities) | GET | Get a list of existing identities. |
| [Create an identity](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/createidentity) | POST | Create a new identity. |
| [Get an identity by ID](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/getidentitybyid) | GET | Get an identity by its unique ID. |
| [Delete an identity](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/deactivateidentity) | DELETE | Delete an identity. |
### Get a list of identities
- [GET /identities](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/getidentities.md): Get a list of identities that match the query parameters.
Note: Depending on the number of identities in your account, not all of them may be returned even if they match your query parameters.
### Create a new identity
- [POST /identities](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/createidentity.md): Create a new identity.
Tutorials
* Learn how to Create an identity.
* Learn how to Work with the piiData object.
### Get an identity by ID
- [GET /identities/{identity-id}](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/getidentitybyid.md): Get an identity by its unique ID
### Delete an identity
- [DELETE /identities/{identity-id}](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/deactivateidentity.md): Delete an identity
## Payments
Use these API operations to manage your payments.
| Operation | Method | Description |
| --- | --- | --- |
| [Get payments](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/payments/getpayments) | GET | Get a list of existing payments. |
| [Get payment by payment ID](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/payments/getpaymentbypaymentid) | GET | Get a specific payment by payment ID. |
### Get payments
- [GET /payments](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/payments/getpayments.md): Retrieves all payments that meet the criteria defined by the query parameters. You can use the query parameters to filter payments.
The default parameters are sort_field : MODIFIED_AT , sort_direction : DESC , page : 0 , size : 10'
### Get payment by payment ID
- [GET /payments/{payment_id}](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/payments/getpaymentbypaymentid.md): Gets a payment by ID.
## Quotes
Use these API operations to manage your quotes.
| Operation | Method | Description |
| --- | --- | --- |
| [Accept quote](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/quotes/acceptquote) | POST | Accepts a quote ID to start the payment process. |
| [Create quote collection](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/quotes/createquotecollection) | POST | Create a collection of quotes. |
### Accept quote
- [POST /payments/accept](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/quotes/acceptquote.md): Accepts a quote ID to start the payment process.
Tutorials
* Learn how to Accept a quote.
* Learn how to Work with the user_info object.
### Create quote collection
- [POST /quote_collections](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/quotes/createquotecollection.md): Creates a collection of quotes for a proposed payment.
Prerequisite
* Learn how to Get a payout method.
Tutorials
* Learn how to Create a quote collection.
## Routing
Use this API operation to look up a payout method.
| Operation | Method | Description |
| --- | --- | --- |
| [Get payout method](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/routing/routingtablelookup) | GET | Look up a payout method. |
### Get payout method
- [GET /config/routing_table/lookup](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/routing/routingtablelookup.md): Look up the payout method based on the beneficiary's country.
Tutorial
* Learn how to get a payout method.
## Data requirements
Use this API operation to get the data required for making a payout using a specific currency.
| Operation | Method | Description |
| --- | --- | --- |
| [Get data requirements](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/data-requirements/getdatarequirements) | GET | Retrieve data requirements. |
### Get data requirements
- [GET /data-requirements](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/data-requirements/getdatarequirements.md): Returns the fields required to make a payout using the given payout method.
## Balances
Use this API operation to get your account balance information.
| Operation | Method | Description |
| --- | --- | --- |
| [Get spendable balance](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/balances/getspendablebalance) | GET | Retrieve account balances. |
### Get spendable balance information
- [GET /spendable_balance](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/balances/getspendablebalance.md): Retrieves your spendable balance.
Note: The response contains either the funded_balance or the credit_usage object depending on your funding method. If you're using the Funded Payments method, the response contains only the funded_balance object. If you're using the T+1 Invoicing method, the response contains only the credit_usage object.
## Internal
### Get a list of examples
- [GET /examples](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/internal/getexamples.md): Get a list of examples.
## Reports
Use these API operations to get payment reports.
| Operation | Method | Description |
| --- | --- | --- |
| [List reports](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/getreports) | GET | Returns an array of reports available for download. |
| [Create a report](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/postreport) | POST | Create a report. |
| [Get a report](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/getreport) | GET | Get the download link for a specific report. |
| [Delete a report](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/deletereport) | DELETE | Delete a specific report. |
| [Download a report](/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/getreportdownload) | GET | Download a transaction report. |
### List reports
- [GET /reports](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/getreports.md): Returns an array of reports available for download. Each array element represents an available report, and contains the reportId, reportType, and reportFormat fields associated with that report.
To get the download link for a specific report, store the reportId for the report you want, and use it with the Get a report operation.
### Create report
- [POST /reports](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/postreport.md): Request the generation of a custom report based on the specified parameters.
Report duration
Reports can contain up to 90 days of transactions from the previous 9 months.
* Minimum report duration is 1 day.
* Maximum report duration is 90 days.
#### Report retention
Reports are retained for 6 months after the endDate specified in your request. After this period, the report is purged and will no longer be accessible.
### Get a report
- [GET /reports/{report-id}](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/getreport.md): Here, you apply the report-id from the List reports operation as the path parameter to get a downloadlink containing the report.
Download the report at the link in the downloadLink field in the response.
### Delete reports
- [DELETE /reports/{report-id}](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/deletereport.md): Delete a specific report with the report-id path parameter.
### Download a report
- [GET /reports/download/{report-id}](https://docs.ripple.com/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/getreportdownload.md): Download a transaction report. Download the report by applying the report-id from the List reports operation as a path parameter.