Payment sub-states are a type of payment label that is applied to the Standard RippleNet Payment Object (SRPO). Sub-states support bi-directional communication between RippleNet Server instances after payments have been settled, but not yet completed. Where labels only provide messaging capabilities, sub-states provide functionality for continuing the payment process until completion.
Within the context of the overall payment process, senders use the Settle payment operation to settle or execute payments in the
LOCKED state, and the payment state for settled payments is
EXECUTED, which indicates that funds have been transferred to the receiver account on all RippleNet ledgers.
Once a payment enters the
EXECUTED state, receivers use sub-states to process and communicate the status of payments for the following scenarios:
- Cash payouts
- Required amended information for beneficiary payout on local rails
- Originator cancels a payment
- Pending due diligence
For more information about payment states in RippleNet, see Payment states.
Keep in mind that there are key differences between payment labels and sub-states:
- Only visible to the party that uses them
Only added to the
internal_infoblock of the RPO
Deletion only removes labels from the
- Used for bi-directional messaging and payment processing between participants
Added to both the
user_info.executedblock of the RPO
Deletion removes sub-states from the
internal_infoblock but not the
The following RippleNet Server API operations provide sub-state functionality:
- Finalize payment
- Add payment sub-state
- Get payments
- Delete payment labels
The Finalize payment operation is used exclusively by receivers to mark payments in the
EXECUTED state with two specific sub-states:
AWAITING_COLLECTION. The receiver 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. The sub-state label is added to both the
user_info.executed arrays of the RPO.
The Add payment sub-state operation is used by both senders and receivers to mark payments in the
EXECUTED state with any of the RippleNet payment sub-states, excluding
AWAITING_COLLECTION, provided in the list below. The sub-state label is added to both the
user_info.executed arrays of the RPO.
The Get payments operation is used by both senders and receivers to retrieve all payments in a RippleNet server instance that meet the criteria defined by the query parameters. For managing payment sub-states, senders and receivers use the Get payments operation to poll for payments in the
EXECUTED state with specific sub-state labels.
The Delete payment labels operation is used to remove an existing label from the
internal_info.labels array in the RPO without removing or altering the sub-state label in the
user_info.executed block. Labels should be removed after an action has been taken, ensuring that the payment does not continue to show up in poller results for past sub-states.
To standardize implementations, the following sub-states are defined based on the currently known use cases. This list will be updated as and when more use cases arise that can use this feature.
||The sender has amended the userinfo array. The amended userinfo array within this sub-state block will have precedence over the original user_info array.|
||For cash pick up when the receiving agent generates a unique code for the payment.|
||The funds are available for the beneficiary to collect.|
||Indicates that the amended information was sent to the agent.|
||Indicates that the amended information was rejected.|
||The cash payout collection failed.|
||The payment has been forwarded to local rails for final payout to the beneficiary.|
||The payout failed, that is the beneficiary hasn't been paid out.|
||The receiver has forwarded payment to a bank but the bank has informed them that settlement will be delayed due to additional compliance activity required by the bank. For example, this sometimes happens with large payments.|
||Additional processes or checks are required to be performed by the receiver prior to payout.|
||The payout to the beneficiary is currently pending.|
||The receiver has requested additional or amended information to perform final payout to the beneficiary.|
||The originator has requested that an executed payment be returned.|
||The receiver has rejected a request to return an executed payment.|
If the sub-states listed above are not sufficient to handle a specific use case, please reach out to your Ripple customer partner engineer.
The following table lists all of the available RippleNet payment sub-states, recommended memo and info field values, and indicates which participant adds the sub-states and which participants polls for the sub-state.
|Memo||Info (Optional)||Added By||Polled By|
||“Instruction is being processed by the clearing channel, awaiting final status.”||Receiver||Sender|
||“Payment has been sent to compliance for manual checks.”||Receiver||Sender|
||“Payment available for the beneficiary to collect.”||Reference or PIN code for the beneficiary to collect cash.||Receiver||Sender|
||“Cash pick-up collection failed.”||Receiver||Sender|
||“Request for this executed payment to be returned.”||Sender||Receiver|
||“The request for returning this executed payment has been rejected.”||Receiver||Sender|
||“Additional information required.”||Errors, array of errors related to the missing field, wrong field, or a document. See Error codes for more information and examples.||Receiver||Sender|
||Include the amended
||“The agent is processing instructions, awaiting final status.”||Receiver||Sender|
||“The amended information led to a payment failure.”||Receiver||Sender|
||“The amended information was sent to the agent, awaiting final status.”||Receiver||Sender|
AWAITING_COLLECTION sub-states should be only triggered by the receiver through the Finalize payment operation. The rest of the sub-states in the list can be triggered by any node through the Add Payment Sub-state operation.
In scenarios where payment failed due to insufficient liquidity, the payment will transition to the
SETTLEMENT_DECLINED state. This is a payment state, not a sub-state.
SETTLEMENT_DECLINED is a transient state that will eventually transition to the
FAILED payment state when payment expires, if the retry process does not succeed.