Skip to content

Payments Direct 1.0 API ( )

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

API environments

The Ripple Payments Direct 1.0 API offers the following environments:

<div style="width:90px">Environment</div>Base URL
Testhttps://{customer-name}.test.rnc.ripplenet.com/v4
Productionhttps://{customer-name}.rnc.ripplenet.com/v4

Base URL

The base URL for the Ripple Payments Direct 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 Ripple Payments Direct 1.0 API.

https://{domainprefix}.{domain}/v4

Example base URL

This is an example base URL for the Ripple Payments Direct 1.0 API.

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.

https://aperture.test.rnc.ripplenet.com/v4/payments?page=0&size=100
Environment<div style="width:120px;">Domain Prefix</div>DomainBase URL
Testaperture.test.rncripplenet.comhttps://aperture.test.rnc.ripplenet.com/v4
Productionaperture.rncripplenet.comhttps://aperture.rnc.ripplenet.com/v4

API authentication

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

Languages
Servers
Mock server

https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-swagger/reference/payments-direct-swagger-external/

Development environment

https://{{customer-name}}.test.rnc.ripplenet.com/v4/

Production environment

https://{{customer-name}}.rnc.ripplenet.com/v4/

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.

Identities

Payments

Use these API operations to manage your payments.

OperationMethodDescription
Get paymentsGETGet a list of existing payments.
Get payment by payment IDGETGet a specific payment by payment ID.
Operations

Quotes

Use these API operations to manage your quotes.

OperationMethodDescription
Accept quotePOSTAccepts a quote ID to start the payment process.
Create quote collectionPOSTCreate a collection of quotes.
Operations

Routing

Use this API operation to look up a payout method.

OperationMethodDescription
Get payout methodGETLook up a payout method.
Operations

Data requirements

Use this API operation to get the data required for making a payout using a specific currency.

OperationMethodDescription
Get data requirementsGETRetrieve data requirements.

Balances

Use this API operation to get your account balance information.

OperationMethodDescription
Get spendable balanceGETRetrieve account balances.
Operations

Get spendable balance information

Request

Retrieves your spendable balance.

Note: The response contains either the funded_balance or the credit_usage object depending on your funding method. <br/><br/> 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.

Security
Bearer
curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-swagger/reference/payments-direct-swagger-external/spendable_balance \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully returned spendable balance information.

Body*/*
funded_balanceArray of objects

Array of spendable balance information for all applicable currencies.

statement_currencystring

The currency of your funded balance, in USD.

net_balancenumber

Spendable balance in the given currency.

credit_usageobject

Information about your credit limit and use.

statement_currencystring

Currency in which you use your credit. This is currently USD.

net_balance_detailsArray of objects

Information about your net balance.

net_balancenumber

The amount for which Ripple has invoiced you but hasn't received payment yet. Note that this amount may be in a different currency from your statement_currency.

invoice_currencystring

The currency in which the invoice is issued.

balance_last_updated_atstring(date-time)

The time (in UTC) when the net balance amount was last updated either by an invoice being generated or by a balance payment.

Example: "2023-11-02T18:26:00.000123Z"
invoice_frequencystring

The frequency at which your invoice is issued.

unbilled_used_creditnumber

The amount of credit you've used since the last invoice was issued, shown in USD.

total_used_creditnumber

The total credit you've used, which is the sum of your net_balance and unbilled_used_credit shown in USD.

unallocated_creditnumber

Your spendable credit amount, calculated as difference of your credit limit and current credit consumption shown in USD.

credit_limitnumber

Your credit limit shown in USD.