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

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

List reports

Request

Returns an array of reports available for download. Each array element represents an available report, and contains the reportId, reportType, and reportFormat fields associated with that report.

To get the download link for a specific report, store the reportId for the report you want, and use it with the Get a report operation.

Security

Bearer

Query

created-bystring

Query for report types based on the entity that initiated report creation.

Value	Description
SCHEDULER	Get automated system-generated reports.
USER	Customized reports generated by users through the UI.
API	Customized reports generated using the API.

Enum"USER""SCHEDULER""API"

Example: created-by=USER

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports?created-by=USER' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Returns an array of report metadata for the calling tenant

Bodyapplication/json

reportsArray of objects>= 0 itemsrequired

reportIdstring(uuid)required

Unique identifier for a report.

Example: "497f6eca-6276-4993-bfeb-53cbbbba6f08"

reportNamestring[ 1 .. 256 ] characters

User defined name of the report.

Example: "My custom report"

reportTypestringrequired

The report type of the downloadable report.

Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting.

reportFormatstringrequired

The report format of the downloadable report.

Enum Value	Description
CSV	A CSV file is a text file that uses a comma to delimit values. Each line of text corresponds to a unique record.
JSON	JSON (Javascript Object Notation) is a file format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and arrays.

reportStatusstringrequired

The status of the report.

Enum Value	Description
PENDING	Report isn't ready for download.
READY	Report is ready for download.
FAILED	Unable generate the report.
EMPTY	Report has no transactions for the date range.

Example: "READY"

startDatestring(date-time)required

The ISO-8601 start date (inclusive) of the report.

Example: "2018-04-06T20:33:35Z"

endDatestring(date-time)required

The ISO-8601 end date (inclusive) of the report.

Note: Must be after startDate, but no more than 90 days after.

Example: "2018-04-06T20:33:35Z"

createdOnstring(date-time)

Report creation time

Example: "2018-04-06T20:33:35Z"

reportCreatedBystring[ 1 .. 128 ] characters

Identifies the entity that initiated the report creation.

Value	Description
SCHEDULER	Automated system-generated report initiated by the scheduler.
API	User-generated report initiated through the API.
[full name]	Full name of the user who initiated the creation of the report through the UI.
null	Legacy support for older reports.

Example: "Norma Jean"

Response

application/json

{
  "reports": [
    { … }
  ]
}

Create report

Request

Request the generation of a custom report based on the specified parameters.

Report duration

Reports can contain up to 90 days of transactions from the previous 9 months.

Minimum report duration is 1 day.
Maximum report duration is 90 days.

Report retention

Reports are retained for 6 months after the endDate specified in your request. After this period, the report is purged and will no longer be accessible.

Security

Bearer

Bodyapplication/json

Parameters defining the requested report

reportNamestring[ 1 .. 256 ] charactersrequired

User defined name of the report.

Example: "My custom report"

startDatestring(date-time)required

The ISO-8601 start date (inclusive) for the requested report.

Example: "2018-04-06T19:33:35Z"

endDatestring(date-time)required

The ISO-8601 end date (inclusive) for the requested report.

Note: Must be after startDate, but no more than 90 days after.

Example: "2018-04-06T20:33:35Z"

reportTypestringrequired

The report type of the downloadable report.

Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting.

reportFormatstringrequired

The report format of the downloadable report.

Enum Value	Description
CSV	A CSV file is a text file that uses a comma to delimit values. Each line of text corresponds to a unique record.
JSON	JSON (Javascript Object Notation) is a file format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and arrays.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reportName": "My custom report",
    "startDate": "2018-04-06T19:33:35Z",
    "endDate": "2018-04-06T20:33:35Z",
    "reportType": "PAYMENT_OPS",
    "reportFormat": "CSV"
  }'

Responses

Returns the JSON record for the posted report

Bodyapplication/json

reportIdstring(uuid)required

Unique identifier for a report.

Example: "497f6eca-6276-4993-bfeb-53cbbbba6f08"

reportNamestring[ 1 .. 256 ] characters

User defined name of the report.

Example: "My custom report"

reportTypestringrequired

The report type of the downloadable report.

Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting.

reportFormatstringrequired

The report format of the downloadable report.

Enum Value	Description
CSV	A CSV file is a text file that uses a comma to delimit values. Each line of text corresponds to a unique record.
JSON	JSON (Javascript Object Notation) is a file format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and arrays.

reportStatusstringrequired

The status of the report.

Enum Value	Description
PENDING	Report isn't ready for download.
READY	Report is ready for download.
FAILED	Unable generate the report.
EMPTY	Report has no transactions for the date range.

Example: "READY"

startDatestring(date-time)required

The ISO-8601 start date (inclusive) of the report.

Example: "2018-04-06T19:33:35Z"

endDatestring(date-time)required

The ISO-8601 end date (inclusive) of the report.

Note: Must be after startDate, but no more than 90 days after.

Example: "2018-04-06T20:33:35Z"

createdOnstring(date-time)

Report creation time

Example: "2018-04-06T20:33:35Z"

Response

application/json

{
  "reportId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "reportName": "My custom report",
  "reportType": "PAYMENT_OPS",
  "reportFormat": "CSV",
  "reportStatus": "READY",
  "startDate": "2018-04-06T19:33:35Z",
  "endDate": "2018-04-06T20:33:35Z",
  "createdOn": "2018-04-06T20:33:35Z"
}

Get a report

Request

Here, you apply the report-id from the List reports operation as the path parameter to get a downloadlink containing the report.

Download the report at the link in the downloadLink field in the response.

Security

Bearer

Path

report-idstring(uuid)required

Unique identifier for a report.

Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/497f6eca-6276-4993-bfeb-53cbbbba6f08 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Returns the JSON record of the report specified in the path parameter

Bodyapplication/json

reportIdstring(uuid)required

Unique identifier for a report.

Example: "497f6eca-6276-4993-bfeb-53cbbbba6f08"

reportNamestring[ 1 .. 256 ] characters

User defined name of the report.

Example: "My custom report"

reportTypestringrequired

The report type of the downloadable report.

Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting.

reportFormatstringrequired

The report format of the downloadable report.

Enum Value	Description
CSV	A CSV file is a text file that uses a comma to delimit values. Each line of text corresponds to a unique record.
JSON	JSON (Javascript Object Notation) is a file format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and arrays.

reportStatusstringrequired

The status of the report.

Enum Value	Description
PENDING	Report isn't ready for download.
READY	Report is ready for download.
FAILED	Unable generate the report.
EMPTY	Report has no transactions for the date range.

Example: "READY"

startDatestring(date-time)required

The ISO-8601 start date (inclusive) for a requested report.

Example: "2018-04-06T19:33:35Z"

endDatestring(date-time)required

The ISO-8601 end date (inclusive) for the requested report.

Note: Must be after startDate, but no more than 90 days after.

Example: "2018-04-06T20:33:35Z"

createdOnstring(date-time)

Report creation time

Example: "2018-04-06T20:33:35Z"

downloadLinkstring(uri)[ 1 .. 2048 ] characters

Link where you can download the report in the available format. This field is available when the report status is READY.

Example: "https://reporting-test.rnc.ripplenet.com/v4/reports/download/497f6eca-6276-4993-bfeb-53cbbbba6f08"

reportCreatedBystring[ 1 .. 128 ] characters

Identifies the entity that initiated the report creation.

Value	Description
SCHEDULER	Automated system-generated report initiated by the scheduler.
API	User-generated report initiated through the API.
[full name]	Full name of the user who initiated the creation of the report through the UI.
null	Legacy support for older reports.

Example: "Norma Jean"

Response

application/json

{
  "reportId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "reportName": "My custom report",
  "reportType": "PAYMENT_OPS",
  "reportFormat": "CSV",
  "reportStatus": "READY",
  "startDate": "2018-04-06T19:33:35Z",
  "endDate": "2018-04-06T20:33:35Z",
  "createdOn": "2018-04-06T20:33:35Z",
  "downloadLink": "https://reporting-test.rnc.ripplenet.com/v4/reports/download/497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "reportCreatedBy": "Norma Jean"
}

Delete reports

Request

Delete a specific report with the report-id path parameter.

Security

Bearer

Path

report-idstring(uuid)required

Unique ID for a report

curl -i -X DELETE \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/{report-id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

The resource was successfully deleted.

Download a report

Request

Download a transaction report. Download the report by applying the report-id from the List reports operation as a path parameter.

Security

Bearer

Path

report-idstring(uuid)required

Unique identifier for a report. Get this report-id from the List reports operation.

Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08

curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/payments-direct-api/reference/payments-direct-api/reports/download/497f6eca-6276-4993-bfeb-53cbbbba6f08 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Returns the JSON record of the report specified in the path parameter.

Bodyapplication/json

end_to_end_idstring[ 1 .. 128 ] characters

The unique ID that the sender specifies. It persists on all RippleNet instances that participate in the payment.

ripplenet_payment_idstring[ 1 .. 128 ] characters

The unique payment identifier.

Example: "70eccd4f-abcd-1234-a655-3aeddff19e4a"

quote_tsstring(date-time)

The ISO-8601 timestamp of the quote.

created_atstring(date-time)

The ISO-8601 timestamp when the transaction was created.

Example: "2022-10-02T20:57:13.606Z"

executed_atstring(date-time)

The ISO-8601 timestamp when the payment was settled.

Example: "2022-10-02T20:57:20.62Z"

sender_addressstring[ 1 .. 128 ] characters

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress.

Example: "new_york@rn.us.ny.new_york"

sender_customerstring[ 1 .. 128 ] characters

The name of the sending institution.

Example: "examplecorp_sf"

sent_amountnumber

The payment amount sent.

Example: 40

sent_currencystring[ 1 .. 128 ] characters

The ISO 4217 currency code of the of sent_amount.

Example: "USD"

receiver_addressstring[ 1 .. 128 ] characters

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress.

Example: "new_york@rn.us.ny.new_york"

receiver_customerstring[ 1 .. 128 ] characters

Name of the receiving institution.

Example: "sf"

received_amountnumber

The payment amount received by the beneficiary.

Example: 39.45

received_currencystring[ 1 .. 128 ] characters

The ISO 4217 currency code of the received_amount.

Example: "PHP"

payment_methodstring[ 1 .. 128 ] characters

[Sender only]

Method for completing the payment. This is a freeform text field that accepts custom strings for payment methods, for example:

CSM_ID_IDR
MSISDN_ID_IDR
CASHPICKUP_ID_IDR
CARD_CN_CNY

Or you can use RippleNet payment method values:

REAL_TIME_GROSS_SETTLEMENT_SYSTEM
REAL_TIME_NET_SETTLEMENT_SYSTEM
MASS_NET_PAYMENT_SYSTEM
BOOK_TRANSFER
CASH_PAYOUT
WALLET_PAYMENT
OTHER

Example: "CSM_TH_THB"

payment_statestring[ 1 .. 128 ] characters

The state of a payment at the moment it is queried.

Example: "COMPLETED"

remitter_namestring[ 1 .. 128 ] characters

Complete name of the person originating the payment.

Note: Values are only viewable by the customer requesting the report.

remitter_accountstring[ 1 .. 128 ] characters

Account number at the sending institution for the payment remitter.

Note: Values are only viewable by the customer requesting the report.

beneficiary_namestring[ 1 .. 128 ] characters

Complete name of the person receiving the payment.

Note: Values are only viewable by the customer requesting the report.

beneficiary_accountstring[ 1 .. 128 ] characters

Account number at the receiving institution for the payment beneficiary.

Note: Values are only viewable by the customer requesting the report.

payment_batch_idstring[ 1 .. 36 ] characters

Unique identifier for a batch of payments.

Note: This field is only populated for payments that are part of a batch.

Response

application/json

{
  "end_to_end_id": "string",
  "ripplenet_payment_id": "70eccd4f-abcd-1234-a655-3aeddff19e4a",
  "quote_ts": "2019-08-24T14:15:22Z",
  "created_at": "2022-10-02T20:57:13.606Z",
  "executed_at": "2022-10-02T20:57:20.62Z",
  "sender_address": "new_york@rn.us.ny.new_york",
  "sender_customer": "examplecorp_sf",
  "sent_amount": 40,
  "sent_currency": "USD",
  "receiver_address": "new_york@rn.us.ny.new_york",
  "receiver_customer": "sf",
  "received_amount": 39.45,
  "received_currency": "PHP",
  "payment_method": "CSM_TH_THB",
  "payment_state": "COMPLETED",
  "remitter_name": "string",
  "remitter_account": "string",
  "beneficiary_name": "string",
  "beneficiary_account": "string",
  "payment_batch_id": "497f6eca-1234-5678-bfeb-53cbbbba6f08"
}

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

Balances

Internal

Reports

List reports

Request

Responses

Was this page helpful?

Create report

Request

Report retention

Responses

Was this page helpful?

Get a report

Request

Responses

Was this page helpful?

Delete reports

Request

Responses

Was this page helpful?

Download a report

Request

Responses

Was this page helpful?