About the Refunds API

The Refunds API allows you to work with refunds for charges processed by Wix.

With the Refunds API, your app can:

• Create a refund. Creating a refund starts the refund lifecycle.
• Get and query existing refunds.

Refund lifecycle

Refunds can have the following statuses depending on their position in the refund lifecycle:

1. PENDING
2. SUCCEEDED
3. FAILED
4. REVERSED

The Create Refund does not accept the status and always creates PENDING refund. Refunds created due to Payment Service Provider changes have internal flow and can be initialised in any status.

The Refund Created event is always sent with the initial status described above. For instance, always PENDING status for refunds created via Create Refund method or any possible status in flow initialized by the Payment Service Provider.

Transitioning to any status is possible. For example, in rare cases, transitions FAILED -> PENDING or SUCCEEDED -> PENDING can happen due to retries or internal recovery circumstances.

When create refund is called and you get a response the status can either be PENDING, SUCCEEDED, or FAILED.

When a refund's status is PENDING, listen to Refund Updated events to find out the final outcome.

When result of the operation has been determined the status is changed to either SUCCEEDED or FAILED. Be aware that this transition may take time.

Typically, SUCCEEDED is the final status of a successful refund. However, in rare cases, a PSP can reverse a refund or send an error after already declaring a refund successful. In these cases, the status of the refund changes from SUCCEEDED to REVERSED.

Typically, FAILED is the final status of an unsuccessful refund. However, in rare cases, a failed refund can change to the SUCCEEDED due to internal recovery from errors. Listen to events to make sure you are notified of any changes.

Prevent unintended refunds

The Refunds API allows you to issue partial refunds, but they should be handled with care to avoid sending multiple copies of the same request. If the server receives two requests for a full refund of a charge, one of them will be rejected because total refund amount can't exceed the charge amount. If, however, the server receives two requests for a partial refund, it processes both of them.

Repeat refund requests may happen as a result of retries related to network errors, or if a merchant tries to make a refund from a page with outdated charge information.

For example, a merchant may have an order for 4 items priced $25 each, totaling $100. The merchant may want to refund only 1 of the items for $25 out of $100, but accidentally sends the request twice and refunds a total of $50.

The Refunds API provides a way to avoid these kinds of unintended refunds.

Create Refund accepts an optional previouslyRefundedAmount parameter as a way to prevent accidental duplicate requests. This parameter allows you to provide the previously refunded amount for a charge according to your existing SUCCEEDED refunds at the moment of requesting the refund. The server checks previouslyRefundedAmount against the actual amount already refunded for a charge, and returns an error with code PREVIOUSLY_REFUNDED_AMOUNT_MISMATCH if they don't match. You should only specify a previouslyRefundedAmount if your decision to issue the refund is based on your records of the amount already refunded.

For example, to issue a $25 refund for a charge for which no previous refunds have been made, you would call Create Refund with a previouslyRefundedAmount of $0. If you accidentally send the refund request twice:

• The first request succeeds because no amount has been refunded.
• The second request fails because the amount previously refunded is $25 (from the first request).

To get previouslyRefundedAmount you can sum amount of all SUCCEEDED refunds using Query Refunds specifying the ID of the charge and SUCCEEDED status. You can use this to check that your local information is up to date before making a refund request.

Only one pending refund is allowed for a charge. Creating a refund while another is PENDING will return an error with code CHARGE_REFUND_IN_PROGRESS.

Before you begin

This API is for use by Wix users who have onboarded to accept payments through Wix.

Some of the functionality in this API is specific to particular providers. This is always noted in the documentation when it applies.

Use cases

• Allow merchants to refund existing charges
• Allow merchants to issue partial refunds for charges, preventing unintended refunds
• Import refunds to external accounting software

Terminology

• Merchant: A Wix user who owns a website and has onboarded to accept payments through Wix.
• Buyer: A user of a merchant's site who makes a purchase from the merchant.
• Charge: A transfer of funds from a buyer to a merchant. This was previously referred to as a transaction. Charges (or transactions) are currently handled by the Transaction API.
• Refund: The process of returning funds for a charge to a buyer. Refunds are initiated by merchants. A Refund object represents a record of a refunding attempt.
• Refundability: A property of a charge that describes whether it's possible to issue a refund on the charge, and if so, the allowed range of the refund amount.
• Payment Service Provider (PSP): A service that enables merchants to take payments from buyers. For example, Wix Payments is the Wix PSP, and PayPal is a 3rd-party PSP.
• Processing Fee: A fee taken from a merchant by a Payment provider for processing a charge.
• Application Fee: A fee taken from a merchant by a Wix application associated with the charge. For example, Wix Events may charge a ticket service fee.
• Dispute: The process of returning funds for a charge from a merchant to a buyer. Disputes are initiated by the buyer via their bank. This API doesn't handle disputes, but disputes can cause refunds to fail (indicated by the CHARGE_DISPUTED rejection reason).
• Acquirer Reference Number (ARN): A unique number assigned to a refund. This number is shared across all parties involved in processing the refund. It allows the merchant to track refunds with their bank.