Cancel a payment
Cancels a payment and returns an object with the updated status cancelled.
When cancellation is allowed
| Current status | Can cancel? |
|---|---|
created | Yes |
pending | Yes |
completed | No — payment_not_cancellable |
expired | No — payment_not_cancellable |
cancelled | No — payment_not_cancellable |
Always check the current status before calling this endpoint — if the payment is already in a terminal state, the request will fail.
Idempotency
This endpoint supports an optional X-Idempotency-Key header (UUID). Retrying with the same key within 24 hours is safe — the server returns the cached response without cancelling the payment a second time.
JWT token signed with the EdDSA algorithm. Obtain the token from the HexPay
merchant dashboard and pass it via the Authorization: Bearer <token> header.
In: header
Path Parameters
Unique identifier of the payment (UUID).
uuidHeader Parameters
Optional UUID key for idempotent request processing. If the server receives two requests with the same key within a 24-hour window, the second returns the cached response from the first without creating a duplicate resource. Generate a fresh key for each logically distinct operation.
uuidResponse Body
curl -X POST "https://api.hexpay.io/v1/payments/019327c6-2058-7901-b234-56789abcdeff/cancel" \ -H "X-Idempotency-Key: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"{
"status": "cancelled"
}{
"error": {
"type": "invalid_request_error",
"message": "paymentID must be a valid UUID",
"code": "invalid_payment_id",
"param": "paymentID"
}
}{
"error": {
"type": "authentication_error",
"message": "Invalid or expired authentication token",
"code": "auth_invalid"
}
}{
"error": {
"type": "not_found_error",
"message": "No payment found with the specified ID",
"code": "payment_not_found"
}
}{
"error": {
"type": "api_error",
"message": "An unexpected error occurred. Please retry the request or contact support.",
"code": "internal_error"
}
}