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:

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 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	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 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:

Log into the Ripple Payments UI.
In the left navigation menu, click Settings.
Under Administration, click API Credentials.
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.
In the upper right corner of the page, click New Credential.
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.

Servers

Mock server

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

Authentication

Use these API operations to manage your authentication tokens.

Operation	Method	Description
Request an access token	POST	Request an access token for authentication with Ripple APIs.
Test access token	GET	Test if an access token can be used for authentication.

Operations

Identities

Use these API operations to manage your identities.

Operation	Method	Description
List identities	GET	Get a list of existing identities.
Create an identity	POST	Create a new identity.
Get an identity by ID	GET	Get an identity by its unique ID.
Delete an identity	DELETE	Delete an identity.

Operations

Payments

Use these API operations to manage your payments.

Operation	Method	Description
Get payments	GET	Get a list of existing payments.
Get payment by payment ID	GET	Get a specific payment by payment ID.

Operations

Quotes

Use these API operations to manage your quotes.

Operation	Method	Description
Accept quote	POST	Accepts a quote ID to start the payment process.
Create quote collection	POST	Create a collection of quotes.

Operations

Routing

Use this API operation to look up a payout method.

Operation	Method	Description
Get payout method	GET	Look up a payout method.

Operations

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	GET	Retrieve data requirements.

Operations

Get data requirements

Request

Returns the fields required to make a payout using the given payout method.

Security

Bearer

Query

payout-countrystringrequired

The beneficiary's country in ISO 3166-1 alpha-2 code format.

Example: payout-country=AT

use-casestringrequired

The use case for the payment.

Enum Value	Description
B2B	A business pays another business
B2C	A business pays an individual
B2B2B	A business pays another business on behalf of a business
B2B2C	A business pays an individual on behalf of a business
C2B2B	A business pays another business on behalf of an individual
C2B2C	A business pays an individual on behalf of another individual

payout-currencystring^[A-Z]{3,4}$required

The beneficiary's account currency in ISO-4217 alpha-3 code format.

Example: payout-currency=EUR

payout-categorystringrequired

The payout category for the payment. This field corresponds to payoutMethodName in the 200 response.

Value"BANK"

Example: payout-category=BANK

partner-namestringrequired

The name of Ripple's payout partner. Please reach out to your Ripple liasion to get the value.

field-categorystringrequired

Field category specifies the type of party involved in the transaction.

Field category	Description
ORIGINATOR	The identity corresponds to a payment originator
BENEFICIARY	The identity corresponds to a payment beneficiary

Example: field-category=BENEFICIARY

flowstringrequired

The only supported value is RPD.

Example: flow=RPD

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/data-requirements?payout-country=AT&use-case=B2B&payout-currency=EUR&payout-category=BANK&partner-name=string&field-category=BENEFICIARY&flow=RPD' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Returns all the data requirements for the payout method identified by its id

Bodyapplication/json

supportedUseCasestringrequired

The use case for the payment.

Example: "B2B"

payoutCountrystringrequired

The beneficiary's country in ISO 3166-1 alpha-2 code format.

Example: "AT"

payoutCurrencystringrequired

The beneficiary's account currency in ISO-4217 alpha-3 code format.

Example: "EUR"

payoutMethodNamestring

The payout method determined using the provided data.

Example: "sepa"

dataRequirementsArray of objectsrequired

Example: [{"fieldCategory":"ORIGINATOR","fieldName":"Dbtr.Nm","fieldType":"REQUIRED","fieldDataType":"STRING","fieldMinLength":2,"fieldMaxLength":100,"fieldDescription":"Business originator's name","fieldHelpText":"The business originator's legal name."},{"fieldCategory":"BENEFICIARY","fieldName":"CdtrAgt.FinInstnId.Nm","fieldType":"REQUIRED","fieldDataType":"STRING","fieldMinLength":0,"fieldMaxLength":50,"fieldDescription":"Beneficiary's bank name","fieldHelpText":"Name by which the party is known and which is usually used to identify the party."}]

fieldCategorystringrequired

The data requirements apply to the identity type displayed

Enum Value	Description
ORIGINATOR	Fields related to the sender
BENEFICIARY	Fields related to the beneficiary
ORIGINATOR_AGENT	Fields related to the sender's agent
INTERMEDIARY	Fields for the intermediary party that is facilitating the transaction. Example - Ripple in case of B2B2B
TRANSACTION	Fields that are not associated with any entity but transaction. Example - `Purp.Cd`, `SourceOfCash`

fieldNamestringrequired

The name of the JSON property.

Example: "Dbtr.Id.OrgId.DtAndPlcofIncorprtn"

fieldTypestringrequired

Indicates whether this property is optional or required.

Example: "OPTIONAL"

fieldDataTypestringrequired

The data type of this data requirement.

Enum Value	Description
STRING	Indicates the field accepts a sequence of characters.
BOOLEAN	Indicates the field accepts either `true` or `false`.
INTEGER	Indicates the field accepts whole numbers.
FLOAT	Indicates the field accepts single-precision floating-point numbers.
DOUBLE	Indicates the field accepts double-precision floating-point numbers.
ENUM	Indicates the field accepts a set of predefined enumerated values.

fieldMinLengthintegerrequired

The minimum amount of characters this field requires.

Example: 2

fieldMaxLengthintegerrequired

The maximum amount of characters this field allows.

Example: 2

fieldDescriptionstringrequired

The name of this property.

Example: "Country of incorporation"

fieldRegexValidatorstring

The RegEx pattern for this property.

Example: "^[A-Z]{2}$"

fieldHelpTextstring

The description for this property.

Example: "Country of incorporation as it appears in the certificate of incorporation"

fieldValuesArray of objects

Lists the allowed enum values and their descriptions.

labelstringrequired

Provides a description of the enum value.

valuestringrequired

Provides the enumerated value allowed for the field.

overlappingFieldsArray of strings

Response

application/json

{
  "dataRequirements": [
    { … },
    { … }
  ],
  "payoutCountry": "AT",
  "payoutCurrency": "EUR",
  "payoutMethodName": "sepa",
  "supportedUseCase": "B2B"
}

Balances

Use this API operation to get your account balance information.

Operation	Method	Description
Get spendable balance	GET	Retrieve account balances.

Operations

Internal

Operations

Reports

Use these API operations to get payment reports.

Operation	Method	Description
List reports	GET	Returns an array of reports available for download.
Create a report	POST	Create a report.
Get a report	GET	Get the download link for a specific report.
Delete a report	DELETE	Delete a specific report.
Download a report	GET	Download a transaction report.

Operations

Payments Direct 1.0 API ( )

API environments

Base URL

URL format

Example base URL

Example fully-qualified URL

API authentication

Generate client ID and client secret

Request an access token

Authentication

Identities

Payments

Quotes

Routing

Data requirements

Get data requirements

Request

Responses

Was this page helpful?

Balances

Internal

Reports