To make a payment using any of the Ripple Payments API operations, you need a valid access token.
\nThis access token is required by all Ripple Payments API operations (except the Authentication operation itself). You must include a valid access token in the Authorization header of each request.
Ripple Payments provides a secure model for authentication and authorization by providing access tokens scoped for a set of credentials.
\nThe Authentication operation returns an access token in the access_token response field. You must include your client_id and client_secret in the JSON body to get a valid access token.
The length of the access token isn't fixed, hence it can vary. Avoid validating tokens based on character length.
You need your client ID and client secret to obtain an access token.
\nIf you don't already have your client ID and client secret, do the following:
\nThe client secret is displayed only once when you are creating new credentials.
You can't 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 authentication operation.
\nWe recommend rotating your API credentials at regular intervals in accordance with your organization's security policy.
\nOnce you have your client ID and client secret, follow these steps to obtain an access token that you can use with Ripple Payments API calls:
\nThe first step to fetching an access token it to determine the environment that you want to access.
\nThe following table describes the differences in types of partners and currency for the environments that provide Ripple Payments API access. Take note of the environment string for the environment you want to access.
\n| Environment | \nRequest URL | \nEnvironment String | \nPartners | \nCurrency | \n
|---|---|---|---|---|
| Test | \nhttps://api.test.ripple.com/v2/oauth/token | \ntest | \nSimulated | \nSimulated | \n
| Production | \nhttps://api.ripple.com/v2/oauth/token | \nprod | \nActual | \nActual | \n
The request format for an authentication request is as follows:
\nPOST https://api.ripple.com/v2/oauth/token\nContent-Type: application/json\n{\n \"grant_type\":\"client_credentials\",\n \"client_id\":\"{YOUR_CLIENT_ID}\",\n \"client_secret\":\"{YOUR_CLIENT_SECRET}\",\n \"audience\": \"urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}\"\n}The expected values are as follows:
\nKey | \nValue | \nDescription | \n
|---|---|---|
grant_type | \nclient_credentials | \nSet the grant-type for this client credentials request. | \n
client_id | \n{YOUR_CLIENT_ID} | \nLog into Ripple Payments UI to retrieve your client ID for Ripple Payments. | \n
client_secret | \n{YOUR_CLIENT_SECRET} | \nRetrieve the client secret for Ripple Payments that was generated when you created the current set of credentials in Ripple Payments UI. | \n
audience | \nurn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID} | \nThe value of the audience field is based on URN syntax. The second component of the URN must refer to the environment which you want to access. Ripple integration engineers provide you your tenant ID (the third component of the URN) during training. | \n
Examples:
\nRequest Example (Production Environment Success) – A successful request to a production environment may look similar to the following example:
\nPOST https://api.ripple.com/v2/oauth/token\nContent-Type: application/json\n{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"{YOUR_CLIENT_ID}\",\n \"client_secret\": \"{YOUR_CLIENT_SECRET}\",\n \"audience\": \"urn:ripplexcurrent-prod:{YOUR_TENANT_ID}\"\n}Response Example (Production Environment Success) – A successful request returns a response similar to the following example:
\n{\n \"access_token\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ\",\n \"expires_in\": 3600,\n \"token_type\": \"Bearer\",\n \"scope\": \"keys:read keys:write payments:create quotes:create identities:create audit:read\"\n}Use the /oauth/token/test endpoint to verify the validity of your access token for a specific Ripple environment and determine the remaining time before it expires.
This example demonstrates how to use the /oauth/token/test endpoint to test an access token.
Here, we apply the access token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ to the Authorization: Bearer header.
GET https://api.ripple.com/v2/oauth/token/test\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJRemember to replace the example token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ with your actual access token, and never share your access token publicly.
The response is a JSON object with the following properties:
\nmessage\n : Indicates the status of the access token.\nseconds_to_expiry\n : Represents the number of seconds remaining until the access token expires.\n{\n\"message\": \"token_ok\",\n\"seconds_to_expiry\": 3600\n}Ripple Payments uses Bearer Token Authorization for all operations (except the Authentication operation itself). To make successful Ripple Payments API requests, include a valid access token in the Authorization header of each request in the following format:
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJTo use this in an in an API request, add the value of the access_token field to the Authorization header for all Ripple Payments API operations (except the Authentication operation itself). Remember to add Bearer (including a space) before the access token.
For example:
\nGET https://api.ripple.com/v2/payments/{YOUR_PAYMENT_ID}\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJAccess tokens are valid for 1 hour. After you get a new token, it is cached for a limited amount of time. To avoid problems caused by double caching, don't cache the token client-side. If you do cache the token, you must clear the cache within the time period specified by the expires_in field (as specified by the exp claim in the JWT) in the response body.