Report Service API

The Report Service API provides an efficient and secure way to download On-Demand Liquidity (ODL) payment transactions on the RippleNet network.

Report types

Three report types are available in either CSV or JSON format when performing a List reports operation:

Report type	Description
`PAYMENT_OPS`	This is a Basic payment report suitable for high-level payment investigation and reporting.
`RECON`	This is a Reconciliation report suitable for reconciliation and detailed state-by-state investigation.
`FAILURE_CONVERSION_SSA`	This is a Failure conversion & SSA report suitable for failed payments investigation.

Note: These On-Demand Liquidity (ODL) statement reports do not include data on fiat payments in RippleNet.

Basic payment report

The Basic payment report (PAYMENT_OPS) provides basic payment data, but not the transaction data within payments.

View the Payment operations reports data fields.

Reconciliation report

The Reconciliation report (RECON) includes all basic payment data, and also includes trade and liquidation data that may be associated with a payment.

A single payment with multiple transactions appears in multiple lines, one line per transaction. Each line includes data that has occurred during the transaction, and all subordinate transactions share the same Payment ID.

View the Reconciliation reports data fields.

Failure conversion & SSA report

The Failure conversion & SSA report (FAILURE_CONVERSION_SSA) includes failed payments data.

View the Failure conversion & SSA report data fields.

Report availability

Reports are available in pre-generated formats for the previous two months and the current month-to-date.

The month-to-date report is generated daily at 00:00 AM (UTC) and is generally available one minute later, at 00:01 AM.

Example: Report availability

On October 16th, you can get:

Full month reports for August and September.
A month-to-date report from October 1st to October 16th.

Month	Example	Description
Current	October 1, 2022 to October 16, 2022 at 00:00 AM	Includes ODL payment data from the first day of the current month up to 00:00 AM (UTC) of the current day.
Previous	September (If the current month is October)	Includes all ODL payment data for the month preceding the current month.
Month Before Last	August (If the current month is October)	Includes all ODL payment data from the month preceding the last month.

API operations

Use these operations to view a list of reports, or download a specific report.

API operation	Description
List reports	View a list of available reports.
Create a report	Create a report.
Get a report	View a specific report.
Delete a report	Delete a specific report.
Download a report	Download an individual report in JSON or CSV format.

Authentication

To use any API operation you need a valid access token. You must include a valid access token in the Authorization header of each request.

For more information about getting an access token, see Authentication.

Environments

You can use the Report Service API with the test and production environments by using different base URLs.

Environment	Base URL	Description
Test	`reporting-test.rnc.ripplenet.com`	Test environment with simulated partners and simulated currency.
Production	`reporting.rnc.ripplenet.com`	Production environment with actual partners and actual currency.

Servers

Mock server

https://docs.ripple.com/_mock/products/payments-odl/api-docs/report_service/reference/openapi/

Test environment<br/>Learn about <a href="https://docs.ripple.com/ripplenet/implementation/baseurls/#base-url-by-api-environment" class="api-console-href">API environments</a>

https://reporting-test.rnc.ripplenet.com/

Production environment

https://reporting.rnc.ripplenet.com/

Reports

The Report Service API provides PAYMENT_OPS, RECON, and FAILURE_CONVERSION_SSA reports in either CSV or JSON format.

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-odl/api-docs/report_service/reference/openapi/v1/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.

Enum Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting. View Payment report data fields.
RECON	Reconciliation report suitable for reconciliation and detailed state-by-state investigation. View Reconciliation report data fields.
FAILURE_CONVERSION_SSA	Failure conversion & SSA report suitable for failed payments investigation. View Failure conversion & SSA report data fields.

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 requested report.

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

endDatestring(date-time)required

The ISO-8601 end date (inclusive) for a 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.

Enum Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting. View Payment report data fields.
RECON	Reconciliation report suitable for reconciliation and detailed state-by-state investigation. View Reconciliation report data fields.
FAILURE_CONVERSION_SSA	Failure conversion & SSA report suitable for failed payments investigation. View Failure conversion & SSA report data fields.

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-odl/api-docs/report_service/reference/openapi/v1/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.

Enum Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting. View Payment report data fields.
RECON	Reconciliation report suitable for reconciliation and detailed state-by-state investigation. View Reconciliation report data fields.
FAILURE_CONVERSION_SSA	Failure conversion & SSA report suitable for failed payments investigation. View Failure conversion & SSA report data fields.

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-odl/api-docs/report_service/reference/openapi/v1/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.

Enum Value	Description
PAYMENT_OPS	Basic payment report suitable for high-level payment investigation and reporting. View Payment report data fields.
RECON	Reconciliation report suitable for reconciliation and detailed state-by-state investigation. View Reconciliation report data fields.
FAILURE_CONVERSION_SSA	Failure conversion & SSA report suitable for failed payments investigation. View Failure conversion & SSA report data fields.

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 a 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/v1/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/v1/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-odl/api-docs/report_service/reference/openapi/v1/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.

Note: Depending on the reportId you specified, the returned report is either a Payment operations report or a Reconciliation report.

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-odl/api-docs/report_service/reference/openapi/v1/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

One of:

Report data fields vary depending on the selected report.

Report type	Data fields
`PAYMENT_OPS`	Payment report data fields
`RECON`	Reconciliation report data fields
`FAILURE_CONVERSION_SSA`	Failure conversion & SSA report data fields

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"

withdrawal_result_amountnumber

[Sender only]

Final amount of XRP at source_exchange wallet to be withdrawn after withdrawal_result_fee_amount fees and withdrawal_result_incentive_value incentives have been applied.

Note: This value can be higher or lower than source_result_proceeds depending on whether the incentives were positive or negative.

Example: 39.846668

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"

fx_spot_ratenumber

[Sender only]

The foreign exchange spot rate sourced from Refinitiv, CurrencyLayer, or another third-party source.

Example: 58.70956379

source_exchangestring[ 1 .. 128 ] characters

[Sender only]

The source exchange where the sender originates the payment.

Example: "bitstamp"

destination_exchangestring[ 1 .. 128 ] characters

[Receiver only]

The destination exchange for the payment.

Example: "independentreserve"

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",
  "withdrawal_result_amount": 39.846668,
  "receiver_address": "new_york@rn.us.ny.new_york",
  "receiver_customer": "sf",
  "received_amount": 39.45,
  "received_currency": "PHP",
  "fx_spot_rate": 58.70956379,
  "source_exchange": "bitstamp",
  "destination_exchange": "independentreserve",
  "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"
}

Report data fields

View the data fields for the different report types.

Schemas

Report Service API

Report types

Basic payment report

Reconciliation report

Failure conversion & SSA report

Report availability

Example: Report availability

API operations

Authentication

Environments

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?

Report data fields