The Payment Provider Platform supports refunds initiated by Wix and by the Payment Service Provider (PSP). Wix-initiated refunds happen when a merchant requests a refund using the Wix dashboard. When this happens, Wix sends a request to the PSP's Refund Transaction endpoint. This article includes general information about implementing the Refund Transaction endpoint and supporting PSP-initiated refunds. To learn more about specific refund flows, see Sample Refund Flows.
In general, an implementation of the Refund Transaction endpoint must do 2 things:
Here are some important things to keep in mind when implementing the Refund Transaction endpoint:
200
and the appropriate response body. Any response body that includes a reasonCode
indicates that the refund attempt has failed. Otherwise, it has succeeded.Digest
header whose value is a JSON Web Token. The PSP should use this value to validate all requests to the endpoint. Learn more about JWT validation.When Wix sends a request to the Refund Transaction endpoint, it includes a wixRefundId
field. This field is a unique identifier for the refund. When the PSP receives this request, it must create an internal ID for the payment and include it in the response in the pluginRefundId
field. Each wixRefundId
must be idempotent. This means that if the PSP receives a request with a wixRefundId
that it already processed, it must not initiate a new refund. Instead, it must respond with the latest refund state. In the case of partial refunds, Wix sends a different wixRefundId
for each partial refund request.
When a PSP initiates a refund using the Submit Event API, it must provide a pluginRefundId
identifier in the request. Wix treats this ID as idempotent. This means only the first request with a particular pluginRefundId
creates a corresponding refund entity on the Wix side. All subsequent requests can only update the details of that refund.
In addition to responding to requests to the Refund Transaction endpoint, the PSP must send webhooks to Wix to confirm refund events. For PSP-initiated refunds, the PSP must send a webhook to notify Wix about the refund. Webhooks are sent using the Submit Event API.
Notes:
wixRefundId
from the request and the pluginRefundId
from the response. For PSP-initiated refunds, include only the pluginRefundId
.pluginRefundId
is allowed as long as the payload remains the same, especially reasonCode
.Here are some sample webhooks:
When confirming a refund event, the webhook request body is the same as the response body for the Refund Transaction endpoint with the wixRefundId
added. This webhook is sent immediately after the PSP responds to the Refund Transaction request.
Here is an example webhook:
When a PSP initiates a refund, it sends a webhook with the following format: