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

Get a list of identities

Request

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.

Security

Bearer

Query

identityTypestring

The type of identities you want to retrieve

Enum Value	Description
BENEFICIARY	Identity associated with the beneficiary.
ORIGINATOR	Identity associated with the party originating the payment.

Example: identityType=BENEFICIARY

nickNamestring

The nickname of the identity provided at the time of identity creation.

Example: nickName=Successful Beneficiary

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities?identityType=BENEFICIARY&nickName=Successful+Beneficiary' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Requested identity info in JSON format

Bodyapplication/json

dataArray of objects

The list of the identities that match the query parameters

identityIdstring(uuid)required

The unique ID of the identity

Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

nickNamestringrequired

The nickname of the identity provided at the time of identity creation.

Example: "MyCompany"

createdAtstring(date-time)required

The time at which the identity was created

Example: "2023-11-02T18:26:00.000Z"

identityTypestringrequired

The type of the identity

Enum Value	Description
BENEFICIARY	Identity associated with the beneficiary.
ORIGINATOR	Identity associated with the party originating the payment.

Example: "BENEFICIARY"

useCaseTypestringrequired

The use case type for the identity

Enum Value	Description
INDIVIDUAL	Identity associated with an individual
BUSINESS	Identity associated with an institution or business

Example: "BUSINESS"

Response

application/json

{
  "data": [
    { … }
  ]
}

Create a new identity

Request

Create a new identity.

Tutorials

Learn how to Create an identity.
Learn how to Work with the piiData object.

Security

Bearer

Bodyapplication/jsonrequired

One of:

Create a new business or institutional beneficiary identity.

piiDataobjectrequired

PII data for a business or institutional benficiary in JSON format.

The specific properties you need to specify within the Cdtr, CdtrAgt, and CdtrAcct objects depend on the type of payment you plan to make to this beneficiary and the payout country and currency. To get the required properties for your use case, call the GET /data-requirements operation. For more information about the piiData object, see Working with the piiData object.

Note: The piiData.Cdtr.Id.OrgId.Othr.Id value must be unique for every identity you create in your account.

Cdtrobject

Party to which an amount of money is due.

Nmstring[ 1 .. 140 ] characters^[a-zA-Z0-9 \t]+$

Allows the name of the Creditor to be held as a single value.
Requirements

Must include one (1) name string.
Allowable characters: Alphanumeric and space.
Names with multiple words must be separated by a space.
For example, specify "Widgets Org", as Widgets Org.
Provide a truncated name if longer than 140 characters.

CtryOfResstring^[A-Z]{2}$

Allows the Country of Residence of the Creditor to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.

PstlAdrobject

Allows the address of the Creditor to be held.

AdrLineArray of arrays<= 70 characters

Information that locates and identifies the address for the party.

PstCdstring<= 16 characters

Information that locates and identifies postal code for the party, as defined by postal services.

TwnNmstring<= 35 characters

Information that locates and identifies the city / town for the party, as defined by postal services.

CtctDtlsobject

Allows the contact of the Creditor to be held.

MobNbstring<= 15 characters^\+?[1-9]\d{1,14}$

Mobile Phone Number

EmailAdrstring(email)<= 2048 characters

Address for electronic mail (e-mail).

Idobject

Unique and unambiguous way to identify the Creditor.

OrgIdobject

Unique and unambiguous way to identify a business or organization.

CdtrAgtobject

Financial institution servicing an account for the creditor.

FinInstnIdobject

Allows the details of the Creditor Agent to be held

Nmstring[ 1 .. 140 ] characters^[a-zA-Z0-9 \t]+$

Name by which the party is known and which is usually used to identify the party.

Must include one (1) name string.
Allowable characters: Alphanumeric and space.
Names with multiple words must be separated by a space.
For example, specify "Widgets Org", as Widgets Org.
Provide a truncated name if longer than 140 characters.

Othrobject

Unique identification of an agent, as assigned by an institution, using an identification scheme.

BrnchIdobject

Allows the details of the Creditor Agent Branch to be held

PstlAdrobject

Address for the Branch

CdtrAcctobject

Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.

Ccystring^[A-Z]{3,3}$

Currency for the Creditor Account

Idobjectrequired

Identifier for the Creditor account.

IBANstring^([a-zA-Z0-9_-]){15,35}$

Holds the Creditor account number in International Bank Account Number (IBAN) format.

Usage Guidelines:

If you specify IBAN, do not specify Othr.Id.

This field is used in conjunction with CdtrAgt.FinInstnId.BICFI.

Example IBAN: GB29NWBK60161331926819.

Othrobject

identityTypestringrequired

The type of the identity

Enum Value	Description
BENEFICIARY	Identity associated with the beneficiary.
ORIGINATOR	Identity associated with the party originating the payment.

Example: "BENEFICIARY"

nickNamestring

The nickname for the new identity.

Note: Don't include any personally identifiable information in this field.

Example: "MyCompany"

useCaseTypestringrequired

The use case type for the identity

Enum Value	Description
INDIVIDUAL	Identity associated with an individual
BUSINESS	Identity associated with an institution or business

Example: "BUSINESS"

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityType": "BENEFICIARY",
    "nickName": "Successful Business Beneficiary",
    "useCaseType": "BUSINESS",
    "piiData": {
      "Cdtr": {
        "Nm": "Success Co.",
        "CtctDtls": {
          "MobNb": "+11234567890",
          "EmailAdr": "test@test.com"
        },
        "CtryOfRes": "AT",
        "Id": {
          "OrgId": {
            "Othr": {
              "Id": "1234567890",
              "SchmeNm": {
                "Cd": "CINC"
              }
            },
            "RelShipToDbtr": "CUST"
          }
        },
        "PstlAdr": {
          "AdrLine": [
            "1234 Business Beneficiary Ave"
          ],
          "PstCd": "02125",
          "TwnNm": "Boston"
        }
      },
      "CdtrAcct": {
        "Ccy": "US",
        "Id": {
          "IBAN": "1234123412341234",
          "Othr": {
            "SchmeNm": {
              "Cd": "BBAN"
            }
          }
        }
      },
      "CdtrAgt": {
        "BrnchId": {
          "PstlAdr": {
            "Ctry": "US"
          }
        },
        "FinInstnId": {
          "Nm": "Bank of Massachusetts",
          "Othr": {
            "Id": "123456"
          }
        }
      }
    }
  }'

Responses

successful operation

Bodyapplication/json

identityIdstring(uuid)required

The unique ID of the identity

Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

versionintegerrequired

The version number of the identity

Example: 2

Response

application/json

{
  "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  "version": 2
}

Get an identity by ID

Request

Get an identity by its unique ID

Security

Bearer

Path

identity-idstring(uuid)required

The ID of the identity to get.

Example: 2f4ac57f-c5ba-4051-b51f-b3565778717b

Query

versioninteger>= 1

Version of the identity you want to retrieve.

Note: If you don't specify a version, the latest version of the identity is returned.

Example: version=2

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/2f4ac57f-c5ba-4051-b51f-b3565778717b?version=2' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Requested identity info in JSON format

Bodyapplication/json

identityIdstringrequired

The unique ID of the identity

Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

identityTypestringrequired

The type of the identity

Enum Value	Description
BENEFICIARY	Identity associated with the beneficiary.
ORIGINATOR	Identity associated with the party originating the payment.

Example: "BENEFICIARY"

createdAtstring(date-time)required

The time at which the identity was created

Example: "2023-11-02T18:26:00.000Z"

identityStatestringrequired

The state of the identity

Enum Value	Description
ACTIVE	The identity requested exists and is active.
BLOCKED	The identity requested exists, but is blocked.
DELETED	The identity requested has been deleted.

Example: "ACTIVE"

nickNamestring

The nickname of the identity provided at the time of identity creation.

Example: "MyCompany"

piiDataobjectrequired

PII data in JSON format

property name*anyadditional property

versionintegerrequired

The version number of the identity

Example: 2

Response

application/json

{
  "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  "identityType": "BENEFICIARY",
  "createdAt": "2023-11-02T18:26:00.000Z",
  "identityState": "ACTIVE",
  "nickName": "MyCompany",
  "piiData": {},
  "version": 2
}

Delete an identity

Request

Delete an identity

Security

Bearer

Path

identity-idstringrequired

Unique UUID string that maps to the identity to be deleted.

Example: 2f4ac57f-c5ba-4051-b51f-b3565778717b

curl -i -X DELETE \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/identities/2f4ac57f-c5ba-4051-b51f-b3565778717b \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

The identity was deleted successfully

Response

No content

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

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

Get a list of identities

Request

Responses

Was this page helpful?

Create a new identity

Request

Responses

Was this page helpful?

Get an identity by ID

Request

Responses

Was this page helpful?

Delete an identity

Request

Responses

Was this page helpful?

Payments

Quotes

Routing

Data requirements

Balances

Internal

Reports

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

Get a list of identities

Request

Responses

Was this page helpful?

Create a new identity

RequestExpand all

Responses

Was this page helpful?

Get an identity by ID

Request

Responses

Was this page helpful?

Delete an identity

Request

Responses

Was this page helpful?

Payments

Quotes

Routing

Data requirements

Balances

Internal

Reports

Request