Sample Refund Flows

This article shows how to handle refund flows when implementing a Refund Transaction endpoint. For general information about this endpoint, see Processing Refunds.

The Payment Provider Platform supports these refunds flows:

Refunds can be full or partial but cannot exceed the original payment amount.

The following sections include examples of each refund flow. These examples are based on the Refund Transaction request body and the Submit Event request body. The values in these examples are fake. Examples are applicable for both live and sandbox modes.

Wix-initiated refunds

Here are some examples of Wix-initiated refunds flows:

Successful full refund

  1. Wix calls Refund Transaction to initiate a full refund for 10 USD. The request body looks like this:
    Copy
    1
    {
    2
      "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    3
      "wixRefundId": "ce590272-87bf-428f-943a-0ff594059712",
    4
      "pluginTransactionId": "212b7c92-a7db-4dca-94f4-2f7d2dbb5a51",
    5
      "merchantCredentials": {
    6
        "client_id": "john@example.com",
    7
        "client_secret": "asdjdj44-asdd-3445566fdss"
    8
      },
    9
      "refundAmount": 1000,
    10
      "mode": "live"
    11
    }
  2. The PSP responds with an HTTP status code of 200 and this JSON object:
    Copy
    1
    {
    2
      "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5"
    3
    }
  3. The PSP sends this webhook to Submit Event. Note that the amount field is a string:
    Copy
    1
    curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
    2
    -H 'Content-Type: application/json' \
    3
    -H 'Authorization: <AUTH>' \
    4
    -d '{
    5
          "event": {
    6
            "refund": {
    7
              "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    8
              "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5",
    9
              "amount": "1000",
    10
              "wixRefundId": "ce590272-87bf-428f-943a-0ff594059712"
    11
            }
    12
          }
    13
        }'
  4. Wix marks the payment as refunded and responds with an HTTP status code of 200 and an empty JSON object.

Successful partial refund

Requests for partial refunds are handled the same way as requests for full refunds. If Wix initiates a partial refund, the PSP can initiate another partial refund for the same payment.

  1. Wix calls Refund Transaction to initiate a partial refund for 5 USD. The request body looks like this:
    Copy
    1
    {
    2
      "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    3
      "wixRefundId": "ce590272-87bf-428f-943a-0ff594059712",
    4
      "pluginTransactionId": "212b7c92-a7db-4dca-94f4-2f7d2dbb5a51",
    5
      "merchantCredentials": {
    6
        "client_id": "john@example.com",
    7
        "client_secret": "asdjdj44-asdd-3445566fdss"
    8
      },
    9
      "refundAmount": 500,
    10
      "mode": "live"
    11
    }
  2. The PSP responds with a HTTP status code of 200 and this JSON object:
    Copy
    1
    {
    2
      "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5"
    3
    }
  3. The PSP sends this webhook to Submit Event. Note that the amount field is a string:
    Copy
    1
    curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
    2
    -H 'Content-Type: application/json' \
    3
    -H 'Authorization: <AUTH>' \
    4
    -d '{
    5
          "event": {
    6
            "refund": {
    7
              "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    8
              "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5",
    9
              "amount": "500",
    10
              "wixRefundId": "ce590272-87bf-428f-943a-0ff594059712"
    11
            }
    12
          }
    13
        }'
  4. Wix marks the payment as partially refunded and responds with an HTTP status code of 200 and an empty JSON object.
    At a later point, the merchant can request another partial refund.

Failed refund

When a refund attempt fails, the PSP must respond with the appropriate reason code. For a list of reason codes, see Reason Codes. The following example is relevant for both full and partial refunds.

  1. Wix calls Refund Transaction to initiate a full refund for 10 USD. The request body looks like this:
    Copy
    1
    {
    2
      "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    3
      "wixRefundId": "ce590272-87bf-428f-943a-0ff594059712",
    4
      "pluginTransactionId": "212b7c92-a7db-4dca-94f4-2f7d2dbb5a51",
    5
      "merchantCredentials": {
    6
        "client_id": "john@example.com",
    7
        "client_secret": "asdjdj44-asdd-3445566fdss"
    8
      },
    9
      "refundAmount": 1000,
    10
      "mode": "live"
    11
    }
  2. The PSP responds with an HTTP status code of 200 and a JSON object that includes "reasonCode": 3025. This reason code indicates that the refund failed because of insufficient funds. The errorCode and errorMessage fields include PSP-specific data.
    Copy
    1
    {
    2
      "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5",
    3
      "reasonCode": 3025,
    4
      "errorCode": "INSUFFICIENT_FUNDS_FOR_REFUND",
    5
      "errorMessage": "Insufficient funds for refund"
    6
    }
  3. The PSP sends this webhook to Submit Event. Note that the amount field is a string:
    Copy
    1
    curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
    2
    -H 'Content-Type: application/json' \
    3
    -H 'Authorization: <AUTH>' \
    4
    -d '{
    5
          "event": {
    6
            "refund": {
    7
              "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    8
              "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5",
    9
              "amount": "1000",
    10
              "wixRefundId": "ce590272-87bf-428f-943a-0ff594059712",
    11
              "reasonCode": "3025",
    12
              "errorCode": "INSUFFICIENT_FUNDS_FOR_REFUND",
    13
              "errorMessage": "Insufficient funds for refund"
    14
            }
    15
          }
    16
        }'
  4. Wix does not update the payment status and responds with an HTTP status code of 200 and an empty JSON object.

PSP-initiated refunds

PSP-initiated refunds don't involve the Refund Transaction endpoint. Instead, the PSP sends a webhook to Submit Event to notify Wix about the refund. The following examples show how to handle PSP-initiated refunds.

Successful full refund

  1. A merchant successfully refunds a 10 USD payment through the PSP's platform.
  2. The PSP sends the following webhook to Submit Event:
    Copy
    1
    curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
    2
    -H 'Content-Type: application/json' \
    3
    -H 'Authorization: <AUTH>' \
    4
    -d '{
    5
          "event": {
    6
            "refund": {
    7
              "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    8
              "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5",
    9
              "amount": "1000"
    10
            }
    11
          }
    12
        }'
  3. Wix marks the payment as refunded and responds with an HTTP status code of 200 and an empty JSON object.

Successful partial refund

Requests for partial refunds are handled the same way as requests for full refunds. When a PSP initiates a partial refund, Wix can initiate another partial refund for the same payment.

  1. A merchant successfully refunds 6 USD out of a 10 USD payment through the PSP's platform.
  2. The PSP sends the following webhook to Submit Event:
    Copy
    1
    curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
    2
    -H 'Content-Type: application/json' \
    3
    -H 'Authorization: <AUTH>' \
    4
    -d '{
    5
          "event": {
    6
            "refund": {
    7
              "wixTransactionId": "fcd2655f-e261-4c5b-8129-72a241461a27",
    8
              "pluginRefundId": "7178df7c-8b58-42a9-86ed-9dbc143f5ac5",
    9
              "amount": "600"
    10
            }
    11
          }
    12
        }'
  3. Wix marks the payment as partially refunded and responds with an HTTP status code of 200 and an empty JSON object.
Was this helpful?
Yes
No