> For the complete documentation index, see [llms.txt](https://docs.maibmerchants.md/request-to-pay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/initiate-a-refund-for-a-completed-payment.md).

# Initiate a refund for a completed payment

Initiates a refund for an RTP **payment** that has already been accepted/executed. The path parameter is the **payment identifier** (`payId`), not the `rtpId`.

***

### Request

**HTTP Method**: `POST`\
**Endpoint**:

```
/v2/rtp/{payId}/refund
```

**Headers**

```http
Authorization: Bearer {access_token}
Content-Type: application/json
```

***

#### Path Parameters

| Parameter | Type          | Required | Description                    |
| --------- | ------------- | -------- | ------------------------------ |
| `payId`   | string (GUID) | Yes      | **Payment** unique identifier. |

***

#### Request Body Parameters

| Parameter | Type         | Required | Description                   |
| --------- | ------------ | -------- | ----------------------------- |
| `reason`  | string (500) | Yes      | Reason for initiating refund. |

***

### Example Request

```http
POST /v2/rtp/123e4567-e89b-12d3-a456-426614174000/refund HTTP/1.1
Host: api.maibmerchants.md
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reason": "Refund reason"
}
```

*(curl)*

```bash
curl -X POST "https://api.maibmerchants.md/v2/rtp/123e4567-e89b-12d3-a456-426614174000/refund" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Refund reason"}'
```

***

### Response

#### Response Parameters

| Field                 | Type          | Description                                    |
| --------------------- | ------------- | ---------------------------------------------- |
| `result`              | object        | Response result object.                        |
| `result.refundId`     | string (GUID) | Refund unique identifier.                      |
| `result.status`       | string (enum) | Payment status. Possible value: Created.       |
| `ok`                  | boolean       | Request processing status (`true` on success). |
| `errors`              | array         | Present only if `ok = false`.                  |
| `errors.errorCode`    | string        | Error code.                                    |
| `errors.errorMessage` | string        | Error description.                             |

***

#### Example Successful Response

```json
{
  "result": {
    "refundId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Created"
  },
  "ok": true
}
```

***

### Notes & Best Practices

* The path uses **`payId`** (payment) rather than the **`rtpId`** (request). Ensure you store both identifiers after a successful payment.
* Provide a clear, auditable `reason` for the refund in your back-office systems.