Cancel a payment
Cancels a payment. The response contains only the new status, cancelled.
Use GET /v1/payments/{paymentId} if you need the full payment object.
Cancellation is permitted from created or pending status only. Payments
already in a terminal state (completed, expired, or cancelled) cannot
be cancelled.
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 stored response from the first without creating a duplicate resource. Responses with status 401, 403, 404, 408, 409, 429, 500, 502, 503 or 504 are not stored. 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": "Missing authorization token",
"code": "auth_missing"
}
}{
"error": {
"type": "not_found_error",
"message": "Payment not found",
"code": "payment_not_found"
}
}{
"error": {
"type": "api_error",
"message": "Internal server error",
"code": "internal_error"
}
}