# Non-orchestration payments ## Get payments - [GET /payments](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/getpayments.md): Retrieves all payments in an instance of xCurrent 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 ## Get payment by payment ID - [GET /payments/{payment_id}](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/getpaymentbypaymentid.md): Gets a payment by ID. ## Lock payment - [POST /payments/{payment_id}/lock](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/lockpayment.md): Locks a payment. The beneficiary and all intermediary institutions agree to proceed with the payment by making successful Lock Payment requests. When the payment is still in a _partially_ LOCKED state, the beneficiary and all intermediary institutions who have _not_ locked, can reject lock payment or fail payment. Once fully LOCKED, the originating institution can either fail payment or Settle payment. If the originating institution sends a Settle payment request, one of three things will happen: * Successful payments move to the PREPARED state. * Payments with insufficient liquidity automatically move into state SETTLEMENT_DECLINED, or * Payments that are not settled before the crypto_transaction_id expires move to the FAILED state. Note: Currently, when making a Create quote to return payment to a RippleNet Cloud account on a RippleNet ledger, the RippleNet user must lock and complete the payment. This means that the RippleNet user takes all action on the return: Get and Accept Quote, Lock, Settle, and Complete payment. ## Reject lock payment - [POST /payments/{payment_id}/reject](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/rejectlockpayment.md): Rejects a payment from being locked. This temporarily stops the payment and keeps it in a recoverable state so that user_info can be corrected. If the payment is incorrect for reasons outside of the user_info object, use Fail payment. After a payment has been created by an Accept quote request, the beneficiary or an intermediary can choose to reject the payment, rather than Lock payment, with corrections to user_info in the reasons array. A rejected payment moves the payment state to LOCK_DECLINED from which it can be recovered by the originating institution with a Retry accept payment request. If any one institution in the payment chain is configured to _auto-fail_, the payment automatically fails when the payment is rejected, moving to the FAILED state rather than the LOCK_DECLINED state. ## Retry accept payment - [POST /payments/{payment_id}/retry_accept](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/retryacceptpayment.md): Returns a rejected payment from the LOCK_DECLINED state to the ACCEPTED state. The payment sender must include repaired user_info in the request body. ## Fail payment - [POST /payments/{payment_id}/fail](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/failpayment.md): Fails a payment. Fail payment is a deliberate action that permanently stops the payment and puts it into a non-recoverable state. An institution _rejects_ a payment to solicit changes to user_info; it _fails_ a payment to stop it altogether. After a payment has been created by an Accept quote request, you can fail the payment if it is your institution's turn to take an action on the payment. The originating institution can fail a payment in states LOCKED and LOCK_DECLINED. The beneficiary and intermediary institutions can fail a payment in the ACCEPTED state. Beneficiary institutions can also fail a payment in the EXECUTED state. The general use case for failing an executed payment is to Create quote to return payment to the originating institution. Payments in states PREPARED and SETTLEMENT_DECLINED can fail _automatically_—PREPARED when the crypto-transaction expires and SETTLEMENT_DECLINED when the payment expires. ## Settle payment - [POST /payments/{payment_id}/settle](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/settlepayment.md): Executes a payment in the LOCKED state. Payment senders can also retry settling a payment in the SETTLEMENT_DECLINED state, after the error is corrected (and before the payment expires).Settle payment sends a _prepare payment transfer_ message, which travels to all participants in the payment. This sets the payment state to PREPARED, which means that funds have been transferred to the hold account on that xCurrent ledger. The beneficiary institution then signs the execution_condition (creating a payload) and sends an _execute payment transfer_ message, which travels to all participants in the payment). When the payment is fully executed, funds have been transferred from the hold account to the receiver account on all xCurrent ledgers and the payment state is set to EXECUTED. ## Finalize payment - [POST /payments/{payment_id}/finalize](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/finalizepayment.md): Marks a payment with finalized sub-states that reflect what is happening to the payment while it is in the EXECUTED state. The receiving institution can make this request multiple times to provide a log of each subsequent sub-state until it is ready to make the Complete payment request. ## Add payment sub state - [POST /payments/{payment_id}/sub_state](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/addpaymentsubstate.md): Adds a sub-state to a payment that reflects what is happening to the payment while it is in the EXECUTED state. All nodes on the payment chain can make this request multiple times to provide a log of each subsequent sub-state until the receiver is ready to make the Complete payment request.This operation is especially useful for completing cash payouts—sending institutions can add clarifying user information to a payment after it has been executed (and money has been moved). ## Complete payment - [POST /payments/{payment_id}/complete](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/completepayment.md): Marks a payment as complete by placing it in the COMPLETED state. Typically, the receiving institution makes this request when it has delivered payment funds to the final beneficiary on its internal systems outside of xCurrent. ## Add payment labels - [PUT /payments/{payment_id}/labels](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/addpaymentlabels.md): Adds a list of labels to the payment. To retrieve payments by label, see Get payments. ## Delete payment labels - [DELETE /payments/{payment_id}/labels](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/deletepaymentlabels.md): Deletes an existing label from a payment. The label you provide is deleted from the labels array in the Payment object. ## Get payment node status - [GET /payments/{payment_id}/node-status](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/getpaymentnodestatus.md): Senders can query for the RippleNet instances (in a given payment chain) that have payments in the LOCKED state. This information is only stored on the sender's RippleNet instance. ## Get filtered payment by payment ID - [GET /payments/filtered/{payment_id}](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/getfilteredpaymentbypaymentid.md): Returns a sanitized payment with sensitive content filtered from the user_info object. Filtering user_info is customizable in rnn.properties. Content that is denylisted by default: /Cdtr, /CdtrAcct, /Dbtr, /DbtrAcct, /InitgPty, /InstForCdtrAgt, /Purp, /RgltryRptg, /RltdRmtInf, /RmtInf, /UltmtCdtr, /UltmtDbtr, /outbound_instructions/beneficiary_info ## Create quote to return payment - [POST /quote_collections/return](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/createquotetoreturnpayment.md): Creates a collection of quotes that can be used to return a payment. The receiver can make this request while the payment is in states EXECUTED, COMPLETED, or FAILED. When the returned payment is successfully moved to the COMPLETED state, the original payment is moved to the RETURNED state. Note: Currently, when making a Return Payment to a RippleNet Cloud account on a RippleNet ledger, the RippleNet user must lock and complete the payment. This means that the RippleNet user takes all action on the return: Get and Accept Quote, Lock, Settle, and Complete payment. ## Create quote to reverse payment - [POST /quote_collections/reversal](https://docs.ripple.com/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/createquotetoreversepayment.md): Creates a quote collection containing at most one quote that can be used to reverse a payment. The receiver can make this request while the payment is in states EXECUTED, COMPLETED, or FAILED. When the returned payment is successfully moved to the COMPLETED state, the original payment is moved to the RETURNED state. Note: Currently, when making a Reversal Payment to a RippleNet Cloud account on a RippleNet ledger, the RippleNet user must lock and complete the payment. This means that the RippleNet user takes all action on the reverse: Get and Accept Quote, Lock, Settle, and Complete payment.