# Payment states This topic explains the **payment state** function in RippleNet integrated payments. The `state` field of the payment object defines the payment status. Each subsequent state overrides previous states. ![RippleNet Payment States](/assets/payment-states.5f50ee91b375e5b80a9ca57dfb2344024020025854e38a739a65a2137285c62a.35e5bcbb.svg) ## RippleNet payment states Refer to the following table for all possible states. | State | Description | | --- | --- | | `ACCEPTED` | The first state of the payment object. The sender has made a successful **Accept quote** request to its RippleNet instance, generating a `payment_id`, which is applied to the quote and persisted as a payment object. In this state, the receiver can lock, reject, or fail the payment. | | `LOCKED` | The receiver has agreed to proceed with the payment by making successful **Lock payment** requests. When the payment is still in a *partially* `LOCKED` state (that is, not locked on all RippleNet nodes across the payment chain), the receiver can Reject Payment or Fail Payment. Once fully `LOCKED` across the payment chain, the sender can either Fail Payment or Settle Payment. | | `LOCK_DECLINED` | The receiver has made a successful **Reject payment** request. For institutions that have not yet locked the payment, the state changes from `ACCEPTED` to `LOCK_DECLINED`. For institutions that have locked the payment, the state changes from `LOCKED` to `LOCK_DECLINED`. The sender must repair the rejected payment and make a Retry Accept Payment request. The sender can fail payments in the `LOCK_DECLINED` state. | | `PREPARED` | The sender has made a **Settle payment** request, which created the crypto-transaction and put the payment within the "crypto-transaction boundary". In this state, funds have been transferred to the **hold account** on the sender's RippleNet ledger. A payment cannot expire in the `PREPARED` state; if the payment does not settle before the crypto-transaction expires, it moves to the `SETTLEMENT_DECLINED` state. When a payment is in the `SETTLEMENT_DECLINED` state, the sender can Retry Settle Payment which, if successful, moves the payment back to the `PREPARED` state and generates a new crypto-transaction. | | `EXECUTED` | The receiver has signed the `execution_condition` creating a "payload" and sent 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 RippleNet ledgers. Only the receiver can fail payments in the `EXECUTED` state. The general use case for failing an executed payment is to return the payment to the originating institution in fiat only transactions. | | `SETTLEMENT_DECLINED` | The receiver has not been able to fulfill the payment due to insufficient liquidity. Once the problem is addressed, and if the payment has not expired, senders can resubmit the Settle Payment request. If this request is successful, RippleNet moves the payment back to the `PREPARED` state and generates a new crypto-transaction. Payments that expire before being settled move automatically to the `FAILED` state. | | `FAILED` | The payment has been actively stopped by a participating institution, or the payment has failed automatically because the payment has expired. An institution can only fail a payment in turn. Failed payments *can be* returned in fiat flows. | | `COMPLETED` | After verifying that the funds have reached the end beneficiary, the payment state gets updated to `COMPLETED`. Depending on your use case, this verification happens either outside the RippleNet payment flow by the receiver or within; hence, the `COMPLETED` state may be triggered outside of RippleNet but can still be returned in fiat flows. | | `RETURNED` | **For fiat payments only** A final state. The receiver has sent a **Return payment** request, generating a new payment object, in reference to the original payment from the sender. Return Payment initiates a quote collection response and follows normal payment flow but in reverse order. When this new payment is successfully moved to the `COMPLETED` state and the money is returned, the *original* payment automatically moves to the `RETURNED` state from either the `EXECUTED`, `COMPLETED` or `FAILED` state. | ### Request for payment states The `state` field of the `RequestForPayment` object defines the end-to-end payment request status. Each subsequent state overrides previous states. | State | Description | | --- | --- | | `REQUESTED` | The first state of the `RequestForPayment` object. The payment beneficiary institution has made a successful **Send request for payment** request. In this state, the payment sender institution knows to initiate a payment to the beneficiary. | | `ACCEPTED` | The final state of a successful request for payment. The payment sender has sent an **Accept request for payment** request and populated the RequestForPayment object with the `payment_id` of the settled payment. | | `FAILED` | The request for payment had been actively terminated with a **Fail request for payment** request. | ## Payment state transitions Once all parties agree upon a payment contract and the payment state is `LOCKED`, RippleNet uses a two-phase commit to execute the payment. On all RippleNet ledgers in the payment chain (sender, intermediaries, receiver): 1. Funds transfer to a hold account and the payment state moves from `LOCKED` to `PREPARED`. 2. Funds transfer to a transactional account and the payment state moves from `PREPARED` to `EXECUTED`. Once a payment is `PREPARED` it moves into a logical area called the *crypto-transaction boundary*. Within the boundary, payment state changes are determined by the state of the crypto-transaction, which can be `PENDING`, `EXECUTED`, `EXPIRED` or `CANCELLED`. Outside of the boundary, the payment succeeds or fails based on the payment expiration time. Most payments are executed as expected and payment state transitions are near simultaneous on all RippleNet instances. There may be times, however, when each RippleNet instance *temporarily* reflects a different payment state. Whether the payment is successful or not, background processes ensure that the payment state is *eventually* consistent across all RippleNet instances. ### Scenarios Both scenarios below assume: * The payment chain is `Sender` > `Receiver`. * The payment is `LOCKED` on all nodes in the payment chain. * The [validator](/products/payments-odl/glossary#validator) on the sender's RippleNet host is used for the payment. #### Happy path The happy path assumes that **all RippleNet ledgers have enough liquidity** to execute the payment. 1. Sender sends a **Settle payment** request: * The [validator](/products/payments-odl/glossary#validator) creates a crypto-transaction using the execution condition created with **Accept quote**. * Funds on the sender RippleNet ledger transfer to a hold account. * Payment state on the sender RippleNet instance moves to `PREPARED`. **Payment states across payment chain:** | Sender | Receiver | | --- | --- | | `PREPARED` | `LOCKED` | 1. The sender sends a message to the receiver that the payment is `PREPARED`: * Funds on the receiver RippleNet ledger transfer to a hold account. * Payment state on the receiver RippleNet instance moves to `PREPARED` (and all parties have consistent states). * Receiver sends a `200 OK` response up the payment chain (and spawns a background process to send the fulfillment). **Payment states across payment chain:** | Sender | Receiver | | --- | --- | | `PREPARED` | `PREPARED` | 1. The receiver creates the payment fulfillment (using its private key) and sends it to the [validator](/products/payments-odl/glossary#validator). * Validator cryptographically verifies the fulfillment. * Validator executes the crypto-transaction and the **crypto-transaction state moves to** `EXECUTED`. 2. The [validator](/products/payments-odl/glossary#validator) sends the `EXECUTED` crypto-transaction to the receiver: * Funds on the receiver RippleNet ledger transfer from the hold account to the transactional account. * Payment state on the receiver RippleNet instance moves to `EXECUTED`. **Payment states across payment chain:** | Sender | Receiver | | --- | --- | | `PREPARED` | `EXECUTED` | 1. The sender sends a message up the payment chain that the payment has been executed: * Funds on the sender RippleNet ledger transfer from the hold account to the transactional account. * Payment state on the sender RippleNet instance moves to `EXECUTED`. **Payment states across payment chain:** | Sender | Receiver | | --- | --- | | `EXECUTED` | `EXECUTED` | Note If a payment is in the `PREPARED` state and within the crypto-transaction boundary, a background process continually queries the [validator](/products/payments-odl/glossary#validator) for the state of the crypto-transaction. If the crypto-transaction is `EXECUTED`, but the happy path message does not reach the other RippleNet nodes so that they seem "stuck" in the `PREPARED` state, the background process takes over and triggers payment execution. #### Unhappy path In this path, the **receiving RippleNet ledger does *not* have enough liquidity** to execute the payment and the crypto-transaction is cancelled. 1. Sender sends a **Settle payment** request: * The [validator](/products/payments-odl/glossary#validator) creates a crypto-transaction (using the execution condition created with **Accept quote**). * Funds on the sender RippleNet ledger transfer to a hold account. * Payment state on the sender RippleNet instance moves to `PREPARED`. **Payment states across payment chain:** | Sender | Receiver | | --- | --- | | `PREPARED` | `LOCKED` | 1. Sender sends a message to the receiver that the payment is `PREPARED`: * Funds on the receiver RippleNet ledger are not available and *no funds move*. * The [validator](/products/payments-odl/glossary#validator) does not receive fulfillment from the receiver and the **crypto-transaction state moves to CANCELLED**. * Payment state on the sender and receiver instances moves to `SETTLEMENT_DECLINED`. * Funds on the sender RippleNet ledger **rollback** from the hold account. **Payment states across payment chain:** | Sender | Receiver | | --- | --- | | `SETTLEMENT_DECLINED` | `SETTLEMENT_DECLINED` | 1. Receiving institution repairs liquidity issue out-of-band. Payment expiration If the payment expires while waiting in the `SETTLEMENT_DECLINED` state, it transitions to the `FAILED` state on all RippleNet instances. 1. Sender resubmits a **Settle payment** request against the same payment ID. * The [validator](/products/payments-odl/glossary#validator) creates a **new** crypto-transaction. * Funds on the sender RippleNet ledger transfer to a hold account. * Payment state on the sender RippleNet instance moves to `PREPARED` and the happy path takes over.