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 events or calling Transactions List.
• The Wix user must have have onboarded to accept payments through Wix.

Flow

1. When the merchant selects a charge to refund, call Create Refund to start the refund process. Specify a refund object containing the ID of the charge to be refunded.

   Copy

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 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 events or calling Transactions List.
• The Wix user must have onboarded to accept payments through Wix.

Flow

1. When the merchant selects a charge to refund, call Query Refunds 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.

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, specifying the previouslyRefundedAmount along with the refund object.

   Copy

   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.

You must subscribe your app to the Refund Created and Refund Updated webhooks in the app dashboard.

Flow

1. The first time the app loads after installation, call Query Refunds using cursor pagination to get an initial list of all previous refunds. For more information about queries see API Query and Search Language.

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.