Cancel Payment

Cancel a payment before it has been fully processed

POST/v1/payments/:id/cancel

When Can You Cancel?

A payment can only be canceled when its status is pending or initiated. Once a payment reaches processing, succeeded, or failed, it cannot be canceled.

For payments that have already succeeded, use the Refund endpoint instead.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API secret key

Path Parameters

Parameter	Type	Description
id	string	The payment ID to cancel (e.g., `pay_abc123xyz`)

Request Body (Optional)

Field	Type	Description
reason	string?	Optional cancellation reason for your records

Response

Returns the updated payment object with status: "canceled":

{
  "id": "pay_abc123xyz",
  "object": "payment",
  "amount": 9999,
  "currency": "USD",
  "status": "canceled",
  "payment_method": "card",
  "customer_email": "customer@example.com",
  "cancellation_reason": "customer_requested",
  "canceled_at": "2024-06-15T10:32:00Z",
  "created_at": "2024-06-15T10:30:00Z",
  "updated_at": "2024-06-15T10:32:00Z"
}

Code Examples

Node.js

import { HedgePayments } from '@hedgepayments/node'

const hedge = new HedgePayments({
  apiKey: process.env.HEDGE_API_KEY,
  apiSecret: process.env.HEDGE_API_SECRET
})

try {
  const payment = await hedge.payments.cancel('pay_abc123xyz', {
    reason: 'customer_requested'
  })

  console.log('Payment canceled:', payment.id)
  console.log('Status:', payment.status) // 'canceled'
} catch (err) {
  if (err.code === 'payment_not_cancelable') {
    console.error('Payment has already been processed')
    // Use refund endpoint instead
  }
}

cURL

curl -X POST https://api.hedgepayments.com/v1/payments/pay_abc123xyz/cancel \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "customer_requested"
  }'

Error Responses

Code	Error	Description
401	unauthorized	Invalid or missing API key
404	not_found	Payment not found with the given ID
412	payment_not_cancelable	Payment status is not `pending` or `initiated`

// 412 error example
{
  "error": {
    "code": "payment_not_cancelable",
    "message": "Payment pay_abc123xyz cannot be canceled. Current status: succeeded.",
    "details": {
      "payment_id": "pay_abc123xyz",
      "current_status": "succeeded",
      "cancelable_statuses": ["pending", "initiated"]
    }
  }
}