# Make a Refund (Mastercard Settlement Accounts Only)
source: https://developer.mastercard.com/ob-accept-payments/documentation/tutorials-and-guides/make-a-refund-tutorial/index.md

This guide walks you through creating a Refund for a payment you previously received through Mastercard Open Finance Pay. Refer to Refunds for general specifications about integrating refunds.

We will execute a refund only when you have signed up for a Mastercard Settlement Account. For other scenarios, refer to [Obtain PSU Source Account for Refund](https://developer.mastercard.com/ob-accept-payments/documentation/tutorials-and-guides/obtain-psu-source-account-tutorial/index.md).

## Step 1 - Prepare the Necessary Refund Details {#step-1---prepare-the-necessary-refund-details}

To create a refund, you need to prepare the following:

* The `paymentId` for a previous payment made to one of your (Merchants) destination accounts is in at least a `PAYMENT_EXECUTED_CREDITED` or subsequent payment status.
* A clear **reason** for the refund, please see the list of supported refund reasons explained in the [Refunds](https://developer.mastercard.com/ob-accept-payments/documentation/payments/refunds/index.md) specification (Pre-conditions section).
* The **amount** of the refund. Note that the amount for each specific refund request and the cumulative amount of all refunds made for a specific payment cannot exceed a threshold (percentage of the original payment) based on your agreed terms and conditions.

## Step 2 - Call the Create Payment Refund Endpoint {#step-2---call-the-create-payment-refund-endpoint}

Call the following endpoint and provide all required parameters.

API Reference: `POST /payments/{payment_id}/refunds`

### Request {#request}

* Use the `paymentId` of the original payment as `{payment_id}` path parameter.
* Use the amount prepared in the previous step.
* Ensure the currency of the refund matches the currency of the original payment.
* Use the reason prepared in the previous step.

### Response {#response}

If the request is successful, the response will look like this:

```json
{
  "refundId": "79e86ce2-db6f-4ca1-a2bb-5986f32a6073"
}
```

Record the `refundId` for next steps.

In the background we will:

* Verify if the Payment Rail, including the PSU Source Account, is available for the original payment.
* If you signed up for a Mastercard Settlement Account, we will execute the refund and capture the payment status from the bank.

## Step 3 - Refund Status Webhook Notification {#step-3---refund-status-webhook-notification}

When the Refund status changes you will receive webhook notification of `type="RefundStatusUpdated"`.

The content of the webhook will look like this:

```json
{
  "type": "RefundStatusUpdated",
  "data": {
    "refundId": "acb29db6-70df-4c99-888c-d8485cd40c3d",
    "executionTime": "2024-01-01T12:34:56.123456+00:00",
    "status": {
      "code": "PAYMENT_EXECUTED_DEBITED",
      "lastUpdated": "2025-05-12T15:23:39.969894+00:00"
    }
  },
  "retryCount": 0
}
```

Record the `refundId` for the next step.

## Step 4 - Refund Result {#step-4---refund-result}

After you receive the Webhook notification, retrieve the latest status of the refund using the Get Refund endpoint.

API Reference: `GET /refunds/{refund_id}`

### Request {#request-1}

Use the `refundId` retrieved from the second step as the `refund_id` path parameter to get the refund status.

### Response {#response-1}

If the request is successful, the response will look like this:

```json
{
  "refundId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "createdDate": "2023-11-28T00:00:00.0000000+00:00",
  "amount": 0.1,
  "currency": "GBP",
  "reason": "string",
  "status": {
    "code": "string",
    "events": [],
    "lastUpdated": "2023-11-28T00:00:00.0000000+00:00",
    "details": {}
  },
  "clientAssignedReference": "reference",
  "forwardSettlementReference": "string"
}
```

Handle different refund outcomes based on the returned refund status code and reason code (see step 3 in the [Refunds](https://developer.mastercard.com/ob-accept-payments/documentation/payments/refunds/index.md) specification for description of status codes).

The statuses relevant for this step are:

|        **Status**        |                **Scope**                |                                **Description**                                 |
|--------------------------|-----------------------------------------|--------------------------------------------------------------------------------|
| PREPARING                | All requests                            | The refund request details have been captured and it is ready to be processed. |
| PENDING                  | Only for Mastercard Settlement Accounts | The refund is being processed by our settlement account provider.              |
| PAYMENT_EXECUTED_DEBITED | Only for Mastercard Settlement Accounts | The payment has been settled and debited from the settlement account.          |
| FAILED                   | Only for Mastercard Settlement Accounts | The refund failed.                                                             |