# Cancel a payment

> Cancels a payment that is still pending, so its checkout page can no longer be used.

Source: https://rais.app/docs/api/cancel-payment

`POST /v1/payments/{payment_id}/cancel`

Required scope: `payments:write`.

A payment in any other state (paid, failed, expired, already cancelled...) cannot be cancelled and answers `409 payment_not_cancellable`. Emits a `payment.cancelled` event.

## Request

### Path parameters

- `payment_id` (string, required): The id of the payment.

### Example request

```bash
curl -X POST https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/cancel \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: The cancelled payment.

Returns the [Payment object](https://rais.app/docs/api/objects/payment.md).

```json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "cancelled",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": null,
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": null,
  "amount_refunded": 0,
  "refunded": false,
  "fees": null,
  "net": null,
  "receipt_url": null,
  "failure": null,
  "payment_method": null,
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": null,
    "response_code": null
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `payment_not_found` | No such payment. |
| 409 | `payment_not_cancellable` | Only a pending payment can be cancelled; this one is paid. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Payments](https://rais.app/docs/payments.md)