# Payment sub-states

Payment sub-states are a type of payment label that is applied to the [Standard RippleNet Payment Object (SRPO)](/products/payments-odl/api-docs/ripplenet/resources/standard-ripplenet-payment-object). 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](/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/settlepayment) 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](/products/payments-odl/introduction/concepts/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](/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/finalizepayment) 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](/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/completepayment) 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](/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/addpaymentsubstate) 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](/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/getpayments) 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](/products/payments-odl/api-docs/ripplenet/reference/openapi/non-orchestration-payments/deletepaymentlabels) 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 user_info array. The amended user_info 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](/products/payments-odl/api-docs/ripplenet/resources/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.