Skip to content

Payments Direct API (0.0.3)

Use the Payments Direct API to get quotes, create and manage payments, and manage originator and beneficiary identities.

API environments

The Payments Direct API offers the following environments:

Environment
Base URLDescription
Testhttps://api.test.ripple.comTest environment with simulated currency.
Productionhttps://api.ripple.comProduction environment

API authentication

All Ripple Payments Direct 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 operation.

Request an access token

To get an access token, use the Request an access token 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.

Overview
License

Apache 2.0

Languages
Servers
Mock server

https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/

Test environment with simulated currency

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

Production environment

https://api.ripple.com/

Authentication

Use these API operations to manage your authentication tokens.

OperationMethodDescription
Request an access tokenPOSTRequest an access token for authentication with Ripple APIs.
Test access tokenGETTest if an access token can be used 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
Testapi.test.ripple.comTest environment with simulated currency.
Productionapi.ripple.comProduction environment for Ripple Payments Direct
Security
BasicAuth
Headers
Authorizationstring

Optional base64-encoded client_id:client_secret. If provided here they aren't required in the request body.

Example: Basic ZGVtbzpwQDU1dzByZA==
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
TesttestTest environment with simulated partners and simulated currency.
ProductionprodProduction environment for Ripple's internal services.

Example: urn:ripplexcurrent-test:{YOUR_TENANT_ID}

Example: "urn:ripplexcurrent-test:{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 \
  -u <username>:<password> \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v2/oauth/token \
  -H 'Authorization: Basic ZGVtbzpwQDU1dzByZA==' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-test:{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.

Example: "pos:payments:create quote_collection:quote:create quote:quote:read pos:payments:read pcs_config:external_read data_requirements:read identities:create identities:read identities:write ledger:balance:read ledger:read"
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": "pos:payments:create quote_collection:quote:create quote:quote:read pos:payments:read pcs_config:external_read data_requirements:read identities:create identities:read identities:write ledger:balance:read ledger:read",
  "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/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/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
  }
]

Identities

Use these API operations to manage your identities.

OperationMethodDescription
Create an identityPOSTCreate a new identity.
List identitiesGETGet a list of existing identities.
Get an identity by IDGETGet an identity by its unique ID.
Deactivate an identityDELETEDeactivate an identity.
Operations

Payments

Use these API operations to manage your payments.

OperationMethodDescription
Search paymentsPOSTSearch for payments based on filtering criteria.
Create a paymentPOSTCreate a payment by accepting a quote.
Get payment by payment IDGETGet a specific payment by payment ID.
Operations

Quotes

Use these API operations to manage your quotes.

OperationMethodDescription
Create quote collectionPOSTCreate a collection of quotes.
Get quote collectionGETGet a quote collection by ID.
Get a quoteGETGet a specific quote by ID.
Operations

Balances

Use this API operation to view your balances.

OperationMethodDescription
Get balancesGETView your existing balances
Operations