> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Sample Flows

## Article: Sample Flows

## Article Link: https://dev.wix.com/docs/api-reference/business-management/payments/refunds/sample-flows.md

## Article Content:

# Sample Use Cases and Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.

## Allow merchants to refund existing charges

A company wants to add functionality to a payment tracking app that allows merchants to refund charges.

### Prerequisites

- You must have an existing app that tracks charges (formerly called transactions) and stores their IDs. For example, by listening for [Payment](https://dev.wix.com/docs/api-reference/business-management/payments/cashier/cashier-pay/payment-event/payment-event.md) events or calling [Transactions List](https://dev.wix.com/docs/rest/business-management/payments/cashier/payments/transaction/transactions-list.md).
- The Wix user must have have onboarded to [accept payments through Wix](https://support.wix.com/en/article/accepting-payments-an-overview).

### Flow

1. When the merchant selects a charge to refund, call [Create Refund](https://dev.wix.com/docs/rest/business-management/payments/refunds/create-refund.md) to start the refund process. Specify a refund object containing the ID of the charge to be refunded.

    ```json
    {
      "refund": {
        "chargeId": "<ID of the charge>"
      }
    }
    ```
2. If there is an error, handle it according to the response message, in case of "Refundability" error inform the merchant and end the flow.
3. Retrieve updated status via [Refund Updated](https://dev.wix.com/docs/rest/business-management/payments/refunds/refund-updated.md) event or via REST API. 
4. If the value of `refund.status` in the response is `"SUCCEEDED"`, confirm to the merchant that refund was successful.
5. If the value of `refund.status` in the response is `"PENDING"`, notify the merchant that the refund is being processed.

## Allow merchants to issue partial refunds for charges, preventing unintended refunds

A company wants to add functionality to a payment tracking app that allows merchants to partially refund charges while preventing unintended refunds. For example, if an order includes several items, the merchant may wish to refund only one of them.

### Prerequisites

- You must have an existing app that tracks charges (formerly called transactions) and stores their IDs. For example, by listening for [Payment](https://dev.wix.com/docs/api-reference/business-management/payments/cashier/cashier-pay/payment-event/payment-event.md) events or calling [Transactions List](https://dev.wix.com/docs/rest/business-management/payments/cashier/payments/transaction/transactions-list.md).
- The Wix user must have onboarded to [accept payments through Wix](https://support.wix.com/en/article/accepting-payments-an-overview).

### Flow

1. When the merchant selects a charge to refund, call [Query Refunds](https://dev.wix.com/docs/rest/business-management/payments/refunds/query-refunds.md) specifying the ID of the charge and `SUCCEEDED` status to get all successful refunds. For more information about queries see [API Query and Search Language](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md).

2. Save `allSuccessfulRefunds[*][amount].sum`.

3. Prompt the merchant to enter a desired refund amount.

4. When the merchant decides to issue a refund, call [Create Refund](https://dev.wix.com/docs/rest/business-management/payments/refunds/create-refund.md), specifying the `previouslyRefundedAmount` along with the refund object.

    ```json
    {
      "refund": {
        "currencyCode": "<currencyCode of the charge, for example, USD>",
        "amount": "<amount entered by merchant, for example, 49.95>",
        "chargeId": "<ID of the charge>"
      },
      "previouslyRefundedAmount": "<allSuccessfulRefunds[*][amount].sum>"
    }
    ```

   If you encounter a network error, retry the request.

   If the request is unsuccessful and an error code `PREVIOUSLY_REFUNDED_AMOUNT_MISMATCH` is returned, it means that another refund was issued for the same charge after the merchant saw the previously refunded amount in step 4 and elected to proceed. (This can occur if you accidentally send multiple requests for the same refund and the first request succeeds.)
   Inform the merchant that the information they used is outdated to make the refund request. Show the merchant the up-to-date information and prompt for confirmation before retrying the refund request.

5. If the request is successful and `refund.status` is `"SUCCEEDED"`, confirm to the merchant that refund was successful.

## Import refunds to external accounting software

A company wants to build an app that imports refunds from their Wix site to their external accounting software.

### Prerequisites

The Wix user must have onboarded to [accept payments through Wix](https://support.wix.com/en/article/accepting-payments-an-overview).

You must [subscribe your app](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/webhooks/handle-events-with-webhooks-for-self-hosting-using-the-java-script-sdk.md) to the [Refund Created](https://dev.wix.com/docs/rest/business-management/payments/refunds/refund-created.md) and [Refund Updated](https://dev.wix.com/docs/rest/business-management/payments/refunds/refund-updated.md) webhooks in the [app dashboard](https://dev.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fwebhooks-page).

### Flow

1. The first time the app loads after installation, call [Query Refunds](https://dev.wix.com/docs/rest/business-management/payments/refunds/query-refunds.md) using cursor pagination to get an initial list of all previous refunds. For more information about queries see [API Query and Search Language](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md).

2. Upload the returned refunds to the external accounting software.

3. Whenever the Refund Created webhook is triggered, parse the `createdEvent.entityAsJson` object and upload it to the external accounting software.

4. Whenever the Refund Updated webhook is triggered:

    a. Parse the `updatedEvent.currentEntityAsJson` object to get the refund entity. 
  
    b. Compare the `id` from that entity with the ID's of refunds in the external accounting software to find the matching refund.

    c. Overwrite that refund with the refund entity extracted from the event.