# Get payments

Retrieves all payments that meet the criteria defined by the query parameters. You can use the query parameters to filter payments.

The default parameters are sort_field : MODIFIED_AT , sort_direction : DESC , page : 0 , size : 10'

Endpoint: GET /payments
Version:  
Security: Bearer

## Query parameters:

  - `page` (integer)
    The page number for paginated results.

The value is zero-based, where 0 represents the first page. Set it to 0 to get the first page of results.

  - `size` (integer)
    Number of payments to return per page.

  - `sending_currency` (string)
    Optional parameter to filter results based on the sending_currency_code.

  - `receiving_currency` (string)
    Optional parameter to filter results based on the receiving_currency_code.

  - `internal_id` (string)
    Optional parameter to filter results based on the internal_id.

  - `sender_end_to_end_id` (string)
    Optional parameter to filter results based on the sender_end_to_end_id.

  - `states` (array)
    Returns payments in the specified states.

| State | Description |
| --- | --- |
| ACCEPTED | The sender has made a successful Accept quote request and a payment ID was created. |
| PREPARED | An automatic Settle payment request was made and the crypto-transaction created. |
| PROCESSING_COMPLIANCE| The payment request is going through Ripple's compliance process. |
| EXECUTED | The funds have been transferred to the receiver account. |
| COMPLETED | The funds have reached the end beneficiary. |
| FAILED | The payment has been actively stopped by a participating institution or the payment has failed automatically because it expired. |
    Example: ["ACCEPTED","EXECUTED"]

  - `before` (string)
    Before time stamp

Filters for payments where the range_field column value is before this specified time stamp (inclusive).

You can also specify after to create a time range between after and before.

Dependency: Required if you specify range_field.

Example: 2023-10-13T10:16:29.000Z

  - `after` (string)
    After time stamp

Filters for payments where the range_field column value is after this specified time stamp (inclusive).

You can also specify before to create a time range between after and before.

Dependency: Required if you specify range_field.

Example: 2023-10-13T10:16:29.000Z

  - `range_field` (string)
    Range field

Designates the column name of the payments database table that is used for filtering payments before/after/between time stamps.

The following options are valid:

  | Range field | Description |
  | --- | --- |
  | CREATED_AT | Filter by created date-time |
  | MODIFIED_AT | Filter by modified date-time |
  | ACCEPTED_AT | Filter by quote accepted date-time |
  | EXECUTED_AT | Filter by executed date-time |
  | COMPLETED_AT | Filter by completed date-time |
  | EXPIRES_AT | Filter by quote expiry date-time |

Example usage

If you specify range_field = MODIFIED_AT, you need to specify a time stamp (in the 24 character ISO 8601 format used in payment objects: YYYY-MM-DDTHH:mm:ss.sssZ) as the value for before and/or after to fetch payments before, after, or between the specified time range(s) (inclusive).

Dependency: If you specify range_field, you must also specify before and/or after.

  - `amount_range_field` (string)
    Designates the column name of the payments database table that is used for filtering payments greater/less/between amounts.

For example, if you specify amount_range_field=SENDING_AMOUNT, you would specify an amount as the value for greater and/or less to fetch payments greater, less, or between the specified amounts (inclusive).

| Value | Description |
| --- | --- |
| SENDING_AMOUNT | The amount range to filter payments on is applied to the sending amount |
| RECEIVING_AMOUNT | The amount range to filter payments on is applied to the receiving amount. |

Dependency: Required when minAmount and/or maxAmount is specified.
    Enum: "SENDING_AMOUNT", "RECEIVING_AMOUNT"

  - `min_amount` (number)
    Optional parameter for filtering with min sending/receiving amount.

  - `max_amount` (number)
    Optional parameter for filtering with max sending/receiving amount.

  - `sort_field` (string)
    Sorts results according to the specified field.

| Sort field | Description |
| --- | --- |
| PAYMENT_ID | TBD |
| EXPIRES_AT | Sort by quote expiry date-time  |
| MODIFIED_AT | Sort by modified date-time  |
| CREATED_AT | Sort by creation date-time |
    Enum: "PAYMENT_ID", "EXPIRES_AT", "MODIFIED_AT", "CREATED_AT"

  - `sort_direction` (string)
    Sorts result according to the specified direction.

| Sort direction | Description |
| --- | --- |
| ASC | Sort ascending |
| DESC | Sort descending |

  - `payment_ids` (array)
    List of paymentIds to search for

## Response 200 fields (application/json):

  - `first` (boolean)
    True if  this is the first page.

  - `last` (boolean)
    True if  this is the last page.

  - `number` (integer)
    Page number.

  - `numberOfElements` (integer)
    Number of elements in this request.

  - `size` (integer)
    Page size.

  - `totalElements` (integer)
    Total number of elements for the given request.

  - `totalPages` (integer)
    Total number of pages for the given request.

  - `sort` (array)
    Sort details of this page.

  - `sort.direction` (string)
    Direction of the sort
    Example: "ASC"

  - `sort.property` (string)

  - `sort.ignoreCase` (boolean)

  - `sort.nullHandling` (string)
    Example: "NULLS_FIRST"

  - `sort.ascending` (boolean)
    Example: true

  - `sort.descending` (boolean)

  - `content` (array)

  - `content.payment_id` (string, required)
    Unique identifier of a payment.
    Example: "d485f100-2af7-4e48-9ab1-3c7e28775691"

  - `content.contract_hash` (string, required)
    Hash of all values in the Contract object used to ensure immutability. The values in this object cannot change once a payment transitions into the PROCESSING_COMPLIANCE state.
    Example: "ccb23bd87f13cc13b9d616a9723f76e112aeac8628b2082e0f8bf3b8c670b103"

  - `content.payment_state` (string, required)
    State of the payment.
    Enum: "ACCEPTED", "PROCESSING_COMPLIANCE", "PREPARED", "EXECUTED", "COMPLETED", "FAILED"

  - `content.modified_at` (string, required)
    Date and time at which the payment was last modified, as an ISO-8601 timestamp in UTC.
    Example: "2019-10-01T18:25:47.347Z"

  - `content.contract` (object, required)
    Represents all immutable parts of a payment agreed upon by all participants as a part of the payment compliance processing flow. The values in this object cannot change once a payment transitions to the PROCESSING_COMPLIANCE state.

  - `content.contract.sender_end_to_end_id` (string, required)
    ID that the sender can specify. Persisted on all RippleNet instances that participate in the payment.

  - `content.contract.created_at` (string, required)
    Date and time at which this payment contract was created, as an ISO-8601 timestamp in UTC.
    Example: "2024-03-22T15:24:19.587Z"

  - `content.contract.expires_at` (string, required)
    Date and time after which this payment contract expires, as an ISO-8601 timestamp in UTC.
    Example: "2024-05-21T15:13:31.275Z"

  - `content.contract.quote` (object, required)
    JSON response object that represents a quote for a proposed payment or return payment.

  - `content.contract.quote.quote_id` (string, required)
    Unique identifier for the quote.
    Example: "2a547e56-4aac-4375-86a8-8b3e7014801d"

  - `content.contract.quote.created_at` (string, required)
    Date and time at which the quote was created, as an ISO-8601 timestamp in UTC.
    Example: "2020-01-29T20:59:44.925Z"

  - `content.contract.quote.expires_at` (string, required)
    Date and time after which the quote and its pricing expire.
    Example: "2020-01-29T21:29:44.925Z"

  - `content.contract.quote.type` (string, required)
    Indicates how the amount field should be treated for calculating quote values.
    Enum: "SENDER_AMOUNT", "RECEIVER_AMOUNT", "SENDER_INSTITUTION_AMOUNT", "RECEIVER_INSTITUTION_AMOUNT", "REVERSAL_AMOUNT"

  - `content.contract.quote.price_guarantee` (string, required)
    Indicates whether a quote's pricing is INDICATIVE or FIRM. An INDICATIVE quote allows for price movements between quote issuance and payment execution, such that the quoted amount and delivered amount may differ. A FIRM quote ensures that the quoted and delivered payment amounts are equal.
    Example: "FIRM"

  - `content.contract.quote.sender_address` (string, required)
    RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.
    Example: "sf@rn.us.ca.san_francisco"

  - `content.contract.quote.receiver_address` (string, required)
    RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.
    Example: "sf_gbp@rn.us.ca.san_francisco"

  - `content.contract.quote.amount` (number, required)
    Amount to be sent or received, depending on the type value.
    Example: 1

  - `content.contract.quote.currency_code` (string, required)
    Currency code for the amount value.
    Example: "USD"

  - `content.contract.quote.currency_code_filter` (string, required)
    Currency code that can be used to filter quotes at the opposite end of the quote request. For example, you can filter by this currency code to find the receiving currency for a quote with a SENDER_AMOUNT quote_type. If not sent in the request, this field value is set to null.
    Example: "EUR"

  - `content.contract.quote.service_type` (string, required)
    Returns null.

  - `content.contract.quote.quote_elements` (array, required)
    Transfer and exchange elements. A transfer element represents a movement of funds between two accounts. An exchange element represents the exchange of currencies between two accounts.

  - `content.contract.quote.quote_elements.quote_element_id` (string, required)
    Unique identifier for the quote element.
    Example: "259189e7-cb14-42e7-99ef-375f3285e356"

  - `content.contract.quote.quote_elements.quote_element_type` (string, required)
    Type of quote element. TRANSFER represents the movement of funds between two accounts. EXCHANGE represents the exchange of currencies between two accounts. EXCHANGE_TRADE represents the exchange of fiat to digital currency on a digital exchange. CRYPTO_TRANSFER represents the movement of digital funds between two digital exchanges.
    Enum: "TRANSFER", "EXCHANGE", "EXCHANGE_TRADE", "CRYPTO_TRANSFER"

  - `content.contract.quote.quote_elements.quote_element_order` (integer, required)
    Order of each quote element along the liquidity path. If a quote includes five quote elements, each one is enacted according to its quote_element_order number to make the proposed payment.
    Example: 1

  - `content.contract.quote.quote_elements.sending_amount` (number, required)
    Amount the sender is sending.
    Example: 1

  - `content.contract.quote.quote_elements.receiving_amount` (number, required)
    Amount the receiver is receiving.
    Example: 355

  - `content.contract.quote.quote_elements.sending_fee` (number, required)
    Fees the sender is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

  - `content.contract.quote.quote_elements.receiving_fee` (number, required)
    Fees the receiver is charging. When quote_element_type is set to EXCHANGE, this field value is always set to 0.

  - `content.contract.quote.quote_elements.sending_currency_code` (string)
    Currency code of the sending amount. Included in quote elements with quote_element_type set to EXCHANGE.
    Example: "USD"

  - `content.contract.quote.quote_elements.receiving_currency_code` (string)
    Currency code of the receiving amount. Included in quote elements with quote_element_type set to EXCHANGE.
    Example: "GBP"

  - `content.contract.quote.quote_elements.fx_rate` (object)
    The details of an FX Rate for a quote or payment.

  - `content.contract.quote.quote_elements.fx_rate.rate` (number, required)
    Exchange rate between a base and counter currency.
    Example: 3.25

  - `content.contract.quote.quote_elements.fx_rate.base_currency_code` (string, required)
    Currency code of the base currency.

  - `content.contract.quote.quote_elements.fx_rate.counter_currency_code` (string, required)
    Currency code of the counter currency.

  - `content.contract.quote.quote_elements.fx_rate.type` (string, required)
    Order type of the exchange rate. Valid values are buy or sell.

  - `content.contract.quote.quote_elements.transfer_currency_code` (string)
    Currency code of the transfer. Included in quote elements with quote_element_type set to TRANSFER.

  - `content.contract.quote.liquidity_warning` (string, required)
    Triggered when a quote causes an account to go below its minimum_allowed_balance. Otherwise, this field value is set to null.

  - `content.contract.quote.payment_method` (string)
    Payout method for the quote.
    Example: "LOCAL_RAILS"

  - `content.contract.quote.payment_method_fields` (string)
    JSON object containing payment method metadata.
    Example: "{\"category_id\":\"bank\",\"required_originator_fields\":[{\"field_name\":\"sender_address\",\"field_label\":\"Sender address\"}]}"

  - `content.contract.quote.payout_method_info` (object)
    Details about the payout method.

  - `content.contract.quote.payout_method_info.payout_method_name` (string)
    Payout method for the quote.
    Example: "Cash Payout"

  - `content.contract.quote.payout_method_info.payout_method_category` (string)
    Category of the payout method. Defaults to OTHER if not specified.
    Enum: "REAL_TIME_GROSS_SETTLEMENT_SYSTEM", "REAL_TIME_NET_SETTLEMENT_SYSTEM", "MASS_NET_PAYMENT_SYSTEM", "BOOK_TRANSFER", "CASH_PAYOUT", "WALLET_PAYMENT", "OTHER"

  - `content.contract.quote.payout_method_info.description` (string)
    User defined description of the payout method.
    Example: "local rails"

  - `content.contract.quote.payout_method_info.estimated_time_to_credit` (string)
    The estimated time to credit the beneficiary using this payout method.
    Example: "3 days"

  - `content.contract.fee_info` (object)
    Itemized list of fees charged by each node.

  - `content.contract.fee_info.nodes` (object, required)
    Fees charged by each node participating in the payment.

  - `content.contract.fee_info.total_fees` (array, required)
    Total fees charged in the payment, separated by currency.

  - `content.contract.fee_info.total_fees.total_fee` (number, required)
    Value of the total fee for the currency returned in fee_currency.

  - `content.contract.fee_info.total_fees.fee_currency` (string, required)
    ISO 4217 currency code of the currency the total fee applies to.

  - `content.ripplenet_info` (array)
    Application-provided data explaining actions taken by RippleNet applications.

  - `content.ripplenet_info.node_address` (string, required)
    RippleNet address of the node from which the RippleNetInfo originated.
    Example: "rn.us.ny.new_york"

  - `content.ripplenet_info.settlement_declined` (array, required)
    If applicable, provides an array of RippleNetInfoEntry's explaining transitions into the SETTLEMENT_DECLINED state

  - `content.ripplenet_info.settlement_declined.info` (string)
    Information explaining the action taken by a RippleNet application. Could be a RippleNet error code, or a written explanation of the action taken
    Example: "L001"

  - `content.ripplenet_info.settlement_declined.created_at` (string)
    The DateTime that this quote was created, as an ISO-8601 timestamp in UTC.
    Example: "2018-04-06T20:33:35Z"

  - `content.execution_condition` (string, required)
    A Base64-encoded execution condition for this payment, the fulfillment of which will be presented to the validator to complete this payment. This value must match the execution_condition in the associated crypto transaction.
    Example: "PrefixSha256Condition{subtypes=[ED25519-SHA-256], type=PREFIX-SHA-256, fingerprint=sfGGHCrkyaMsLQNB62w_4zarlPChHKm47JkXVQbs1z0, cost=132360}"

  - `content.crypto_transaction_id` (string, required)
    Unique identifier of the crypto transaction associated with this payment.
    Example: "4e05da26-7872-4a1f-b9b7-db7604757c37"

  - `content.validator` (string, required)
    Address of the validator that validated the payment.
    Example: "rn.us.ca.san_francisco"

  - `content.payment_type` (string, required)
    Payment type.
    Enum: "DIRECT"

  - `content.execution_results` (array, required)
    Represents the actual movement of funds in a payment. Each execution result corresponds to a quote element and represents its execution in a payment.

  - `content.execution_results.execution_result_id` (string, required)
    Unique identifier for this payment result.
    Example: "06f6d4e2-3523-4d17-92fd-53192a06207f"

  - `content.execution_results.execution_timestamp` (string, required)
    Date and time at which this portion of the payment was executed.
    Example: "2019-10-01T18:24:29.867Z"

  - `content.execution_results.execution_result_type` (string, required)
    Type of payment execution result. TRANSFER represents the movement of funds between two accounts. EXCHANGE represents the exchange of currencies between two accounts. EXCHANGE_TRADE represents the exchange of fiat to digital currency on a digital exchange. CRYPTO_TRANSFER represents the movement of digital funds between two digital exchanges.
    Enum: "TRANSFER", "EXCHANGE", "EXCHANGE_TRADE", "CRYPTO_TRANSFER"

  - `content.execution_results.execution_result_order` (integer, required)
    Order in which the payment execution action was taken along the liquidity path. For example, a payment may include five execution results along the liquidity path. Each execution result has an order number that indicates the order in which the execution result was achieved to make the payment.
    Example: 1

  - `content.execution_results.sending_fee` (number, required)
    Fees the sender is charging.
    Example: 2

  - `content.execution_results.receiving_fee` (number, required)
    Fees the receiver is charging.

  - `content.execution_results.sending_currency_code` (string)
    Currency code of the sending amount. Included in execution results with execution_result_type set to EXCHANGE.
    Example: "USD"

  - `content.execution_results.receiving_currency_code` (string)
    Currency of the receiving amount. Included in execution results with execution_result_type set to EXCHANGE.
    Example: "GBP"

  - `content.execution_results.transfer_currency_code` (string)
    Currency of the transfer. Returned in execution results with execute_result_type set to TRANSFER.

  - `content.execution_results.intermediary_delta` (number)
    Amount of XRP representing the difference in FX rate between the moment of quoting and the moment of execution. A positive value is the amount taken out of the incentive pool. A negative value is the amount returned to the incentive pool. (Soon to be deprecated)
    Example: 0.2

  - `content.execution_results.incentive_type` (string)
    Configuration of the incentive pool on the xRapid side. Two values are supported, firm and fx. For firm, xRapid guarantees that the FX rate at the moment of execution is the same as at the moment of quoting. For fx, xRapid guaratees a predefined FX rate.
    Example: "firm"

  - `content.execution_results.incentive_value` (number)
    Amount of XRP representing the difference in FX rate between the moment of quoting and the moment of execution. A positive value is the amount taken out of the incentive pool. A negative value is the amount returned to the incentive pool.
    Example: 0.2

  - `content.execution_results.transaction_hash` (string)
    Hash representing the unique identifier for the transfer of funds in the XRP ledger.
    Example: 5.5467794184785867e+76

  - `content.execution_results.venue_id` (string)
    The id from an exchange associated with a transaction involving an exchange account.
    Example: "nz7RpAujYgnQtjEM"

  - `content.execution_results.fiat_adjusted_value` (number)
    Represents the delta between quoted and received executed amounts, for exchange trades.
    Example: 0.02

  - `content.execution_results.odl_payment_id` (string)
    Payment ID in On-Demand Liquidity (ODL) for an executed ODL payment containing the transaction represented by this execution result.

  - `content.liquidation_execution_results` (array)
    Represents the actual movement of funds in a payment as part of liquidation of a Wallet Receive payment.

  - `content.liquidation_details` (object)
    Payment liquidation details

  - `content.liquidation_details.id` (string)
    Liquidation ID, unique to the liquidation process of this payment

  - `content.liquidation_details.status` (string)
    Liquidation status

  - `content.liquidation_details.failure_reason` (string)
    Reason behind failure of the liquidation, only applicable if the status is failure

  - `content.liquidation_details.failure_count` (integer)
    Number of times the liquidation failed. Irrelevant if status is successful.

  - `content.push_forward_execution_results` (array)
    Represents the movement of funds after an On-Demand Liquidity payment fails at intermediary transfer or destination exchange.

  - `content.accepted_at` (string, required)
    Date and time at which the payment was last accepted, as an ISO-8601 timestamp in UTC.
    Example: "2019-10-01T18:25:47.347Z"

  - `content.executed_at` (string)
    Date and time at which the payment was last executed, as an ISO-8601 timestamp in UTC.
    Example: "2019-10-01T18:25:47.347Z"

  - `content.completed_at` (string)
    Date and time at which the payment was last completed, as an ISO-8601 timestamp in UTC.
    Example: "2019-10-01T18:25:47.347Z"

  - `content.internal_info` (object, required)
    JSON object containing information that only the RippleNet instance that set it can view. These values can be set by the sender when accepting a payment and by an intermediary or receiver when locking the payment.

  - `content.internal_info.connector_role` (string, required)
    Role of the RippleNet node that sets one or more values in the Internal Info object.

Use as follows:

* SENDING: Sending account in the payment resides on this RippleNet instance.
* RECEIVING: Receiving account in the payment resides on this RippleNet instance.
* INTERMEDIARY: Neither sending nor receiving accounts in the payment reside on this RippleNet instance.
* INTERNAL: Both sending and receiving accounts in the payment (usually between RippleNet Cloud and RippleNet) reside on this RippleNet instance.
    Enum: "SENDING", "RECEIVING", "INTERMEDIARY", "INTERNAL"

  - `content.internal_info.labels` (array, required)
    Array of objects that provide label values that are set by including the sub_state field at any stage of the payment's lifecycle. Labels can be used as a filtering mechanism when searching for payments. Labels are visible only to the node that added them to this copy of a payment. If the values that populate this array are not set in the request or if the values set in the request are not viewable by your node, this array is empty.

  - `content.internal_info.labels.label` (string)
    Label to be attached

  - `content.internal_info.internal_id` (string, required)
    ID that is viewable only to the node that set it. This value can be set by the sender when accepting a payment. This value can also be set by any intermediary and the receiver when locking the payment. If this value is not set in the request or if the value set in the request is not viewable by your node, this field value is set to null.

  - `content.user_info` (array, required)
    User-provided data with arbitrary key/value pairs.

  - `content.user_info.node_address` (string, required)
    RippleNet address of the node that provided the user information.
    Example: "rn.us.ca.san_francisco"

  - `content.user_info.accepted` (array, required)
    User information optionally provided when accepting the payment.

  - `content.user_info.accepted.json` (object, required)
    User information provided across the payment lifecycle stored as arbitrary JSON key/value pairs.

  - `content.user_info.accepted.created_at` (string, required)
    Date and time at which the user information was added to the payment, as an ISO-8601 timestamp in UTC.

  - `content.user_info.accepted.subState` (string)
    If provided, this parameter descibes payment state more granularly.
    Example: "EXECUTING"

  - `content.user_info.locked` (array, required)
    User information optionally provided when locking the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.lock_declined` (array, required)
    User information optionally provided when declining to lock the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.retry_accept` (array, required)
    User information optionally provided when retrying acceptance of the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.retry_settlement` (array, required)
    User information optionally provided when retrying settlement of the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.settlement` (array, required)
    User information optionally provided when settling the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.settlement_declined` (array, required)
    User information optionally provided when settlement for the payment is declined. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.failed` (array, required)
    User information optionally provided when failing the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.executed` (array, required)
    Payment sub-state information provided using sub_state and memo fields when finalizing the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.completed` (array, required)
    User information optionally provided when completing the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.forwarded` (array, required)
    If applicable, user information optionally provided when forwarding the payment. For more information, see [User Info Entry Object][user-info-entry].

  - `content.user_info.returned` (array, required)
    If applicable, information optionally provided using return_reasons when returning the payment. For more information, see [User Info Entry Object][user-info-entry].

## Response 400 fields (application/json):

  - `type` (string)
    URL to the error documentation.
    Example: "https://errors.ripplenet.ripple.com/error/json-processing-error"

  - `title` (string)
    Summary of the returned problem.
    Example: "Invalid Request Object"

  - `detail` (string)
    Description of the returned problem.
    Example: "The request parameter [account_id] is not in the correct format."

  - `status` (number)
    HTTP error code.
    Example: 400

  - `ripplenet_error_code` (string)
    RippleNet specific error code.
    Example: "E0104"

  - `finality` (string)
    Specifies if the request can be retried for a successful response.
    Example: "PERMANENT"