Payment sub-states

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.

Payment labels vs. sub-states

Keep in mind that there are key differences between payment labels and sub-states:

Labels

  • Only visible to the party that uses them
  • Only added to the internal_info block of the RPO
  • Deletion only removes labels from the internal_info block

Sub-states

  • Used for bi-directional messaging and payment processing between participants
  • Added to both the internal_info block and user_info.executed block of the RPO
  • Deletion removes sub-states from the internal_info block but not the user_info.executed block

API operations for payment sub-states

The following RippleNet Server API operations provide sub-state functionality:

  1. Finalize payment
  2. Add payment sub-state
  3. Get payments
  4. Delete payment labels

Finalize payment

The Finalize payment operation is used exclusively by receivers to mark payments in the EXECUTED state with two specific sub-states: FORWARDED and 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 internal_info.labels and user_info.executed arrays of the RPO.

Add payment sub-state

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 FORWARDED and AWAITING_COLLECTION, provided in the list below. The sub-state label is added to both the internal_info.labels and user_info.executed arrays of the RPO.

Get payments

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.

Delete payment 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.

List of payment 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.

Sub-state
 Description
AMENDED 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.
AWAITING_AGENT_PROCESS For cash pick up when the receiving agent generates a unique code for the payment.
AWAITING_COLLECTION The funds are available for the beneficiary to collect.
AMENDMENT_PROCESSING Indicates that the amended information was sent to the agent.
AMENDMENT_REJECTED Indicates that the amended information was rejected.
COLLECTION_FAILED The cash payout collection failed.
FORWARDED The payment has been forwarded to local rails for final payout to the beneficiary.
PAYOUT_FAILED The payout failed, that is the beneficiary hasn't been paid out.
PENDING_BANK_DUE_DILIGENCE 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.
PENDING_DUE_DILIGENCE Additional processes or checks are required to be performed by the receiver prior to payout.
PENDING_PAYOUT The payout to the beneficiary is currently pending.
REQUEST_INFO The receiver has requested additional or amended information to perform final payout to the beneficiary.
REQUEST_RETURN The originator has requested that an executed payment be returned.
REQUEST_RETURN_REJECTED The receiver has rejected a request to return an executed payment.
Note

If the sub-states listed above are not sufficient to handle a specific use case, please reach out to your Ripple customer partner engineer.

Recommendations for sub-state field values

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.

Sub-state
 Memo Info (Optional) Added By Polled By
FORWARDED “Instruction is being processed by the clearing channel, awaiting final status.” Receiver Sender
PENDING_DUE_DILIGENCE “Payment has been sent to compliance for manual checks.” Receiver Sender
AWAITING_COLLECTION “Payment available for the beneficiary to collect.” Reference or PIN code for the beneficiary to collect cash. Receiver Sender
COLLECTION_FAILED “Cash pick-up collection failed.” Receiver Sender
REQUEST_RETURN “Request for this executed payment to be returned.” Sender Receiver
REQUEST_RETURN_REJECTED “The request for returning this executed payment has been rejected.” Receiver Sender
REQUEST_INFO “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
AMENDED “user_info has been amended. The amended user_info within this sub-state block will take precedence over the original user_info.” Include the amended user_info. Sender Receiver
AWAITING_AGENT_PROCESS “The agent is processing instructions, awaiting final status.” Receiver Sender
AMENDMENT_REJECTED “The amended information led to a payment failure.” Receiver Sender
AMENDMENT_PROCESSING “The amended information was sent to the agent, awaiting final status.” Receiver Sender
Caution

The FORWARDED and 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.

Note

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.