> 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/cancel-a-pending-payment-request.md).

# Cancel a pending payment request

Cancels a Request to Pay (RTP) that is still in **Pending** status.\
The request cannot be cancelled if it has already been **Accepted**, **Rejected**, or **Expired**.

***

### Request

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

```
/v2/rtp/{id}/cancel
```

**Headers**

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

***

#### Path Parameters

| Parameter | Type          | Required | Description                      |
| --------- | ------------- | -------- | -------------------------------- |
| `rtpId`   | string (GUID) | Yes      | RTP unique identifier (`rtpId`). |

***

#### Request Body Parameters

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

***

### Example Request

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

{
  "reason": "Customer requested cancellation"
}
```

*(curl)*

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

***

### Response

#### Response Parameters

| Field                 | Type          | Description                                    |
| --------------------- | ------------- | ---------------------------------------------- |
| `result`              | object        | Response result object.                        |
| `result.rtpId`        | string (GUID) | RTP unique identifier.                         |
| `result.status`       | string (enum) | RTP status. Possible value: `Cancelled`.       |
| `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": {
    "rtpId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Cancelled"
  },
  "ok": true
}
```

***

### Notes & Best Practices

* Cancellation is only allowed while the RTP is **Pending**.
* After cancellation, the RTP cannot be paid; create a **new** RTP if payment is still required.
* Log both `rtpId` and `reason` for auditability and support workflows.
* Repeating the same cancellation call is safe; the RTP remains `Cancelled` (idempotent behavior on the server side).