Cancel Payment

Mark a pending or processing payment as cancelled in UltraPay.

DELETE/api/v1/payments/:id

When to Use

Use this endpoint when you no longer want a payment you created:

  • Customer cancels their order
  • Cart amount changes (cancel old, create new)

Note: This only works for pending or processing payments. Cancelling a payment in any other status (for example succeeded, expired, or one that is already cancelled) returns 400 with code ALREADY_COMPLETED.

Important: Cancelling does not close the checkout link. It marks the payment as cancelled in UltraPay, but the hosted checkout link (paymentUrl) stays open until it expires, about 30 minutes after the payment was created (around the expiresAt time returned when you created it). Don't reuse or re-share a cancelled payment's link. If a customer completes checkout on a cancelled payment's link, contact support@ultrapay.cc so the payment can be reconciled.

Response

json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled",
    "message": "Payment cancelled successfully"
  }
}

cURL Example

bash
curl -X DELETE https://pay.ultrapay.cc/api/v1/payments/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-Public-Key: upp_your_public_key" \
  -H "X-Secret-Key: ups_your_secret_key"

Handling Cart Changes

If a customer modifies their cart after a payment link has been created, cancel the old payment and create a new one with the updated amount. Send the customer only to the new paymentUrl. Cancelling does not close the old link, so don't reuse or re-share it.

If the cancel request returns ALREADY_COMPLETED, the old payment is no longer pending or processing. Check its status with GET /api/v1/payments/:id before creating a new payment, because the customer may already have paid.

javascript
// Cancel old payment
const cancelResponse = await fetch(`https://pay.ultrapay.cc/api/v1/payments/${oldTransactionId}`, {
  method: 'DELETE',
  headers: {
    'X-Public-Key': 'upp_your_public_key',
    'X-Secret-Key': 'ups_your_secret_key',
  },
});


if (!cancelResponse.ok) {
  const { error } = await cancelResponse.json();
  // ALREADY_COMPLETED: the old payment is no longer pending or processing.
  // Check its status with GET /api/v1/payments/:id before charging again,
  // because the customer may already have paid.
  throw new Error(`Could not cancel old payment: ${error.code}`);
}


// Create new payment with updated amount
const response = await fetch('https://pay.ultrapay.cc/api/v1/payments/create', {
  method: 'POST',
  headers: {
    'X-Public-Key': 'upp_your_public_key',
    'X-Secret-Key': 'ups_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: newAmount,
    currency: 'usd',
    customerEmail: 'customer@example.com',
    successUrl: 'https://yoursite.com/thank-you',
    cancelUrl: 'https://yoursite.com/checkout',
  }),
});


const { data } = await response.json();
window.location.href = data.paymentUrl;
↑ ↓ navigate↵ select