> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel a payment

> POST /v1/payments/{paymentId}/cancel cancels a held or scheduled payment and says where the money went. Requires an Idempotency-Key.

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

**Scope:** `payments:initiate`  ·  **Idempotency-Key:** required

<ParamField path="paymentId" type="string" required>A `held` or `scheduled` payment.</ParamField>
<ParamField body="reason" type="string">Why it is cancelled, up to 500 characters. Shown on the bill.</ParamField>

```bash theme={null}
curl -X POST https://api.stg.cleo-pay.com/v1/payments/e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b/cancel \
  --header "Authorization: Bearer $CLEO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f" \
  --data '{ "reason": "Vendor will be paid by check" }'
```

## Response

`200`:

```json theme={null}
{
  "payment": { "id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b", "status": "cancelled" },
  "message": "Scheduled payment cancelled. No money moved."
}
```

`payment` is the full [payment](/concepts/payments#the-payment-object) after the cancel (shortened here). `message` says where the money went:

| Cancelled | Money |
| - | - |
| Dwolla hold | Back to the bank in 1 to 3 business days. The payment becomes `refund_pending`, then `refunded`. |
| Cleo Pay hold | The bank debit is stopped, or the money is in (or on its way to) the Cleo Pay balance. The payment becomes `refunded`. |
| Scheduled payment | Nothing moved. The payment becomes `cancelled`. |

## Errors

| Code | When |
| - | - |
| `payment_not_cancellable` | The payment is not held or scheduled, it changed while being cancelled, or its bill has several scheduled payments (cancel those in the Cleo web app). `details.status` is the current status. |
| `not_found` | The payment is not the business's. |
| `payment_unconfirmed` | A cancel failed without confirming the refund. Every retry with this key answers `409 payment_unconfirmed`. Check `GET /v1/payments/{paymentId}` before you use a new key. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.