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

Two 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.

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.

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.
Get 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.

Reports

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

List reports

Returns an array of reports available for download. Each array element represents an available report, and contains the id, type, and format fields associated with that report.

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

SecurityApiKeyAuth
Responses
200

Returns an array of report metadata for the calling tenant

Response Schema: application/json
required
Array of objects (ReportRecord)
400

Bad Report Request

403

Forbidden

404

Not found

get/reports
Request samples 
Response samples 
application/json
{
  • "reports": [
    • {
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "type": "PAYMENT_OPS",
      • "format": "CSV",
      • "status": "READY",
      • "start_date": "2018-04-06T20:33:35Z",
      • "end_date": "2018-04-06T20:33:35Z"
      }
    ]
}
Get a report
Here, you apply the id from the List reports operation as the path parameter to get a pre-signed download_link containing the report.


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


SecurityApiKeyAuth 
Request 
path Parameters
id
required
string <uuid> 
Unique identifier for a report.


 
 Example:  497f6eca-6276-4993-bfeb-53cbbbba6f08
Responses 
200
Returns the JSON record of the report specified in the path parameter


Response Schema: application/json
id
required
string <uuid> 
Unique identifier for a report.


 
type
required
string (ReportTypeEnum) 
The report type of the downloadable report.


 Enum: 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 Reconiliation report data fields.


 
format
required
string (ReportFormatEnum) 
The report format of the downloadable report.


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


 
status
required
string (ReportStatusEnum) 
The status of the report.


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


 
start_date
required
string <date-time> 
The ISO-8601 start date (inclusive) for a requested report.


 
end_date
required
string <date-time> 
The ISO-8601 end date (inclusive) for a requested report.


Note:  Must be after start_date, but no more than 31 days after.


 
download_link
string <uri> 
Pre-signed link where you can download the report in the available format. This field is available when the report status is READY.


 
400
Bad request


403
Forbidden


404
Not found


get/reports/{id}
Request samples 
Response samples 
Report data fields
View the data fields for the different report types.


Payment operations
These are the data fields for the PAYMENT_OPS report you download from the Get a report operation. Use this report for high-level payment investigation and reporting.


end_to_end_id
string (end_to_end_id) 
Unique ID that the sender specifies. It persists on all RippleNet instances that participate in the payment.


 
ripplenet_payment_id
string (ripplenet_payment_id) 
Unique payment identifier.


 
quote_ts
string <date-time> 
The ISO-8601 timestamp of the quote.


 
created_at
string <date-time> 
The ISO-8601 timestamp when the transaction was created.


 
executed_at
string <date-time> 
The ISO-8601 timestamp when the payment was settled.


 
sender_address
string (sender_address) 
RippleNet account name and address of the sender, in the format accountname@ripplenetaddress.


 
sender_customer
string (sender_customer) 
Name of the sending institution.


 
sent_amount
number (sent_amount) 
The payment amount sent.


 
sent_currency
string (sent_currency) 
The ISO 4217 currency code of the of sent_amount.


 
withdrawal_result_amount
number (withdrawal_result_amount) 
[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.


 
receiver_address
string (receiver_address) 
RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress.


 
receiver_customer
string (receiver_customer) 
Name of the receiving institution.


 
received_amount
number (received_amount) 
The payment amount received by the beneficiary.


 
received_currency
string (received_currency) 
The ISO 4217 currency code of the received_amount.


 
fx_spot_rate
number (fx_spot_rate) 
[Sender only]


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


 
source_exchange
string (source_exchange) 
[Sender only]


The source exchange where the sender originates the payment.


 
destination_exchange
string (destination_exchange) 
[Receiver only]


The destination exchange for the payment.


 
payment_method
string (payment_method) 
[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
    • 



 
payment_state
string (payment_state) 
The state of a payment at the moment it is queried.


 
remitter_name
string (remitter_name) 
Complete name of the person originating the payment.


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


 
remitter_account
string (remitter_account) 
Account number at the sending institution for the payment remitter.


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


 
beneficiary_name
string (beneficiary_name) 
Complete name of the person receiving the payment.


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


 
beneficiary_account
string (beneficiary_account) 
Account number at the receiving institution for the payment beneficiary.


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


 
{
  • "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"
}
Ripple Payments operations
These are the data fields for the PAYMENT_OPS report you download from the Get a report operation. Use this report for high-level payment investigation and reporting.


end_to_end_id
string (end_to_end_id) 
Unique ID that the sender specifies. It persists on all RippleNet instances that participate in the payment.


 
ripplenet_payment_id
string (ripplenet_payment_id) 
Unique payment identifier.


 
quote_ts
string <date-time> 
The ISO-8601 timestamp of the quote.


 
created_at
string <date-time> 
The ISO-8601 timestamp when the transaction was created.


 
executed_at
string <date-time> 
The ISO-8601 timestamp when the payment was settled.


 
sender_address
string (sender_address) 
RippleNet account name and address of the sender, in the format accountname@ripplenetaddress.


 
sender_customer
string (sender_customer) 
Name of the sending institution.


 
sent_amount
number (sent_amount) 
The payment amount sent.


 
sent_currency
string (sent_currency) 
The ISO 4217 currency code of the of sent_amount.


 
receiver_address
string (receiver_address) 
RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress.


 
receiver_customer
string (receiver_customer) 
Name of the receiving institution.


 
received_amount
number (received_amount) 
The payment amount received by the beneficiary.


 
received_currency
string (received_currency) 
The ISO 4217 currency code of the received_amount.


 
payment_method
string (payments_payment_method) 
[This field is for Ripple internal use only]


Ripple uses this information to complete the payment.     


 
payment_state
string (payment_state) 
The state of a payment at the moment it is queried.


 
remitter_name
string (remitter_name) 
Complete name of the person originating the payment.


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


 
remitter_account
string (remitter_account) 
Account number at the sending institution for the payment remitter.


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


 
beneficiary_name
string (beneficiary_name) 
Complete name of the person receiving the payment.


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


 
beneficiary_account
string (beneficiary_account) 
Account number at the receiving institution for the payment beneficiary.


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


 
{
  • "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": "string",
  • "payment_state": "COMPLETED",
  • "remitter_name": "string",
  • "remitter_account": "string",
  • "beneficiary_name": "string",
  • "beneficiary_account": "string"
}
Reconciliation
These are the data fields for the RECON report you download from the Get a report operation. Use this for reconciliation and detailed state-by-state investigation.


end_to_end_id
string (end_to_end_id) 
Unique ID that the sender specifies. It persists on all RippleNet instances that participate in the payment.


 
ripplenet_payment_id
string (ripplenet_payment_id) 
Unique payment identifier.


 
payment_state
string (payment_state) 
The state of a payment at the moment it is queried.


 
internal_payment_state
string (internal_payment_state) 
[Ripple internal]


Ripple uses this information for troubleshooting purposes.


 
quote_ts
string <date-time> 
The ISO-8601 timestamp of the quote.


 
executed_at
string <date-time> 
The ISO-8601 timestamp when the payment was settled.


 
sender_address
string (sender_address) 
RippleNet account name and address of the sender, in the format accountname@ripplenetaddress.


 
sender_customer
string (sender_customer) 
Name of the sending institution.


 
sent_amount
number (sent_amount) 
The payment amount sent.


 
sent_currency
string (sent_currency) 
The ISO 4217 currency code of the of sent_amount.


 
receiver_address
string (receiver_address) 
RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress.


 
receiver_customer
string (receiver_customer) 
Name of the receiving institution.


 
received_amount
number (received_amount) 
The payment amount received by the beneficiary.


 
received_currency
string (received_currency) 
The ISO 4217 currency code of the received_amount.


 
fx_spot_rate
number (fx_spot_rate) 
[Sender only]


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


 
source_exchange
string (source_exchange) 
[Sender only]


The source exchange where the sender originates the payment.


 
destination_exchange
string (destination_exchange) 
[Receiver only]


The destination exchange for the payment.


 
payment_method
string (payment_method) 
[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
    • 



 
transaction_id
string (transaction_id) 
Unique identifier of the balance change between two accounts.


 
transaction_type
string (transaction_type) 
The type of transaction.


 Enum: Description
CRYPTO_TRANSFER
Transfer of digital assets.


FIAT_TRANSFER
Transfers of fiat.


TRADE
Trade transfers.


 
transaction_state
string (transaction_state) 
The transaction state of the overall payment when it's queried.


 Enum: Description
COMPLETED
Transaction is complete.


EXECUTED
Transaction has executed.


FAILED
Transaction has failed.


 
venue_id
string (venue_id) 
Unique identifier associated with a transaction involving an exchange account. Sometimes it's called "exchange id" or "order id".


 
source_result_amount
number (source_result_amount) 
Fiat amount before deduction of source exchange fee.


 
source_result_adjusted_amount
number (source_result_adjusted_amount) 
Fiat amount after deduction of source exchange fee.


 
source_result_proceeds
number (source_result_proceeds) 
XRP amount after exchange of the source_result_adjusted_amount at the source_exchange.


 
source_result_adjusted_proceeds
number (source_result_adjusted_proceeds) 
XRP amount after deduction of the conversion fees from source_result_proceeds.


 
withdrawal_result_id
string (withdrawal_result_id) 
[Sender only]


Unique identifier for the withdrawal transaction at the source_exchange.


 
withdrawal_result_details_transaction_id
string (withdrawal_result_details_transaction_id) 
XRP transaction hash if there is on-ledger movement.


 
withdrawal_result_amount
number (withdrawal_result_amount) 
[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.


 
withdrawal_result_fee_amount
number (withdrawal_result_fee_amount) 
[Sender only]


Withdrawal fee charged by the source_exchange. This is substracted from the total withdrawal_result_amount.


 
withdrawal_result_incentive_value
number (withdrawal_result_incentive_value) 
[Sender only]


The incentive value in XRP applied to source_result_proceeds to arrive at the withdrawal_result_amount value.


 
deposit_result_id
string (deposit_result_id) 
[Receiver only]


Unique identifier for the deposit at the destination_exchange.


 
deposit_result_amount
number (deposit_result_amount) 
[Receiver only]


The total amount of XRP deposited into the destination wallet. Must equal withdrawal_result_amount, minus negligible ledger fees.


 
deposit_result_fee_amount
number (deposit_result_fee_amount) 
[Receiver only]


Deposit fee charged in XRP by the destination_exchange.


 
balance_change_currency
string (balance_change_currency) 
The ISO 4217 currency code associated with the transaction account.


 
balance_change
number (balance_change) 
The change in account balance caused by the corresponding transaction.


 
destination_result_id
string (destination_result_id) 
Unique identifier for the destination trade at the destination_exchange.


 
destination_result_amount
number (destination_result_amount) 
[Receiver only]


The final XRP amount at destination wallet to be liquidated into received fiat currency.


 
destination_result_adjusted_amount
number (destination_result_adjusted_amount) 
[Receiver only]


The final XRP amount at destination wallet to be liquidated including fees.


 
destination_result_incentive_value
number (destination_result_incentive_value) 
The incentive value (XRP) to be added into the total destination_result_amount.


 
destination_result_proceeds
number (destination_result_proceeds) 
[Receiver only]


Amount of fiat currency received for payout without fee.


 
destination_result_adjusted_proceeds
number (destination_result_adjusted_proceeds) 
Amount of fiat currency received for payout including fees.


 
liquidation_status
string (liquidation_status) 
Reserved for future use.


 
{
  • "end_to_end_id": "string",
  • "ripplenet_payment_id": "70eccd4f-abcd-1234-a655-3aeddff19e4a",
  • "payment_state": "COMPLETED",
  • "internal_payment_state": "DONE",
  • "quote_ts": "2022-10-02T20:57:13.593Z",
  • "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",
  • "fx_spot_rate": 58.70956379,
  • "source_exchange": "bitstamp",
  • "destination_exchange": "independentreserve",
  • "payment_method": "CSM_TH_THB",
  • "transaction_id": "a557eb2d-abcd-1234-a9a0-fdb5b52aaa02",
  • "transaction_type": "TRADE",
  • "transaction_state": "COMPLETE",
  • "venue_id": "8eef087a-abcd-1234-922d-e802b1126ea0",
  • "source_result_amount": 0,
  • "source_result_adjusted_amount": 0,
  • "source_result_proceeds": 0,
  • "source_result_adjusted_proceeds": 0,
  • "withdrawal_result_id": "2b325317-abcd-1234-9aa2-0d5eb2c3c0e1",
  • "withdrawal_result_details_transaction_id": "5b0a25b79595123d80dd27c0808fb554",
  • "withdrawal_result_amount": 39.846668,
  • "withdrawal_result_fee_amount": 0,
  • "withdrawal_result_incentive_value": 0,
  • "deposit_result_id": "18700e69-1234-abcd-5678-cb17d5ccdbca",
  • "deposit_result_amount": 0,
  • "deposit_result_fee_amount": 0,
  • "balance_change_currency": "usd",
  • "balance_change": 0,
  • "destination_result_id": "2c3367d2-ab12-3456-78c9-d9edbf6bcbc5",
  • "destination_result_amount": 0,
  • "destination_result_adjusted_amount": 0,
  • "destination_result_incentive_value": 0,
  • "destination_result_proceeds": 0,
  • "destination_result_adjusted_proceeds": 0,
  • "liquidation_status": "string"
}