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

Report data fields

View the data fields for the different report types.

Schemas

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

{
  "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": "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_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"

payment_statestring[ 1 .. 128 ] characters

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

Example: "COMPLETED"

internal_payment_statestring[ 1 .. 128 ] characters

[Ripple internal]

Ripple uses this information for troubleshooting purposes.

Example: "DONE"

quote_tsstring(date-time)

The ISO-8601 timestamp of the quote.

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

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"

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"

transaction_idstring[ 1 .. 128 ] characters

Unique identifier of the balance change between two accounts.

Example: "a557eb2d-abcd-1234-a9a0-fdb5b52aaa02"

transaction_typestring[ 1 .. 128 ] characters

The type of transaction.

Enum Value	Description
CRYPTO_TRANSFER	Transfer of digital assets.
FIAT_TRANSFER	Transfers of fiat.
TRADE	Trade transfers.

Example: "TRADE"

transaction_statestring[ 1 .. 128 ] characters

The transaction state of the overall payment when it's queried.

Enum Value	Description
COMPLETED	Transaction is complete.
EXECUTED	Transaction has executed.
FAILED	Transaction has failed.

Example: "COMPLETE"

venue_idstring[ 1 .. 128 ] characters

The unique identifier associated with a transaction involving an exchange account. Sometimes it's called "exchange id" or "order id".

Example: "8eef087a-abcd-1234-922d-e802b1126ea0"

source_result_amountnumber

Fiat amount before deduction of source exchange fee.

source_result_adjusted_amountnumber

Fiat amount after deduction of source exchange fee.

source_result_proceedsnumber

XRP amount after exchange of the source_result_adjusted_amount at the source_exchange.

source_result_adjusted_proceedsnumber

XRP amount after deduction of the conversion fees from source_result_proceeds.

withdrawal_result_idstring[ 1 .. 128 ] characters

[Sender only]

Unique identifier for the withdrawal transaction at the source_exchange.

Example: "2b325317-abcd-1234-9aa2-0d5eb2c3c0e1"

withdrawal_result_details_transaction_idstring[ 1 .. 128 ] characters

XRP transaction hash if there is on-ledger movement.

Example: "5b0a25b79595123d80dd27c0808fb554"

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

withdrawal_result_fee_amountnumber

[Sender only]

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

withdrawal_result_incentive_valuenumber

[Sender only]

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

deposit_result_idstring[ 1 .. 128 ] characters

[Receiver only]

Unique identifier for the deposit at the destination_exchange.

Example: "18700e69-1234-abcd-5678-cb17d5ccdbca"

deposit_result_amountnumber

[Receiver only]

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

deposit_result_fee_amountnumber

[Receiver only]

Deposit fee charged in XRP by the destination_exchange.

balance_change_currencystring[ 1 .. 128 ] characters

The ISO 4217 currency code associated with the transaction account.

Example: "usd"

balance_changenumber

The change in account balance caused by the corresponding transaction.

balance_resultnumber

Account balance after the transaction.

destination_result_idstring[ 1 .. 128 ] characters

Unique identifier for the destination trade at the destination_exchange.

Example: "2c3367d2-ab12-3456-78c9-d9edbf6bcbc5"

destination_result_amountnumber

[Receiver only]

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

destination_result_adjusted_amountnumber

[Receiver only]

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

destination_result_incentive_valuenumber

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

destination_result_proceedsnumber

[Receiver only]

Amount of fiat currency received for payout without fee.

destination_result_adjusted_proceedsnumber

Amount of fiat currency received for payout including fees.

liquidation_statusstring[ 1 .. 128 ] characters

Reserved for future use.

liquidation_trade_request_statusstring[ 1 .. 128 ] characters

Reserved for future use.

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.

{
  "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,
  "balance_result": 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",
  "liquidation_trade_request_status": "string",
  "payment_batch_id": "string"
}

Failure conversion & SSA

These are the data fields for the FAILURE_CONVERSION_SSA report you download from the Get a report operation. Use this information to investigate failed payments.

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"

execution_result_typestring[ 1 .. 128 ] characters

The type of failure conversion transaction.

execution_timestampstring(date-time)

The timestamp for when the failure conversion transaction happened.

fx_ratenumber

The foreign exchange rate associated with the failure conversion transaction.

intermediary_deltanumber

payment_statestring[ 1 .. 128 ] characters

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

Example: "COMPLETED"

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"

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"

transfer_currencystring[ 1 .. 128 ] characters

The three-letter code of the currency associated with this transfer.

venue_idstring[ 1 .. 128 ] characters

The unique identifier associated with a transaction involving an exchange account. Sometimes it's called "exchange id" or "order id".

Example: "8eef087a-abcd-1234-922d-e802b1126ea0"

ssa_accountstring[ 1 .. 128 ] characters

The SSA account name and address of the sender in accountname@ripplenetaddress format.

sender_customerstring[ 1 .. 128 ] characters

The name of the sending institution.

Example: "examplecorp_sf"

ssa_remote_transfer_idstring[ 1 .. 128 ] characters

The unique identifier of the SSA transfer from the SSA funding account to the SSA account.

ssa_transfer_amountnumber

The SSA transfer amount.

ssa_balance_changenumber

The change in SSA balance caused by the corresponding transaction.

ssa_balance_resultnumber

The SSA account balance after the transaction is complete.

ssa_transfer_currencystring[ 1 .. 128 ] characters

The three-letter code of the currency associated with this SSA transfer.

ssa_transfer_statestring[ 1 .. 128 ] characters

The state of the SSA transfer.

{
  "end_to_end_id": "string",
  "ripplenet_payment_id": "70eccd4f-abcd-1234-a655-3aeddff19e4a",
  "execution_result_type": "string",
  "execution_timestamp": "2019-08-24T14:15:22Z",
  "fx_rate": 0,
  "intermediary_delta": 0,
  "payment_state": "COMPLETED",
  "sent_amount": 40,
  "sent_currency": "USD",
  "received_amount": 39.45,
  "received_currency": "PHP",
  "transfer_currency": "string",
  "venue_id": "8eef087a-abcd-1234-922d-e802b1126ea0",
  "ssa_account": "string",
  "sender_customer": "examplecorp_sf",
  "ssa_remote_transfer_id": "string",
  "ssa_transfer_amount": 0,
  "ssa_balance_change": 0,
  "ssa_balance_result": 0,
  "ssa_transfer_currency": "string",
  "ssa_transfer_state": "string"
}