Payment states

The state field of the payment object defines the payment status. Each subsequent state overrides previous states.

Ripple Payments Direct payment states

Refer to the following table for all possible states.

State
 Description
ACCEPTED The first state of the payment object. The originator has made a successful Accept quote request, generating a payment_id, which is applied to the quote and persisted as a payment object.
PROCESSING_COMPLIANCE Ripple's compliance service ensures that the transaction(s) is compliant with local, national, and international regulations.
PREPARED The payment has settled automatically, 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 when it is in the PREPARED state.
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.
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.
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.

Payment state transitions

Once all the payment quote was successfully accepted and the payment state is PROCESSING_COMPLIANCE, 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 PROCESSING_COMPLIANCE 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 CANCELED. 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.