Skip to main content

​
Overview

The Cancel Payment Intent endpoint allows you to cancel a pending payment intent before the terminal processes the card payment or the intent expires. Once cancelled, the terminal will be notified and the payment request is withdrawn. Common use cases:
  • Customer decides not to pay at the terminal
  • Order was entered with incorrect amount or details
  • User navigates away from the payment screen in your application
  • A new payment intent needs to replace an existing one
Cancellation is permanent and irreversible. Once a payment intent is cancelled, it cannot be reactivated. Create a new payment intent if payment is still needed.

​
Authentication

This endpoint requires API key authentication using the x-api-key header.

​
Cancellation Rules

You can only cancel a payment intent if all of these conditions are met:
1

Status is PENDING

The payment intent must be in PENDING status. You cannot cancel payment intents that are already CONFIRMED or CANCELLED.
2

Payment intent belongs to your organization

You can only cancel payment intents created by your organization.
If a terminalCode was provided when creating the payment intent, cancelling it also notifies the terminal that the payment request has been withdrawn.

​
Request Format

POST /api/payment-intent/{id}/cancel
API reference: POST /payment-intent/{id}/cancel
​
id
string
required
The unique identifier (UUID) of the payment intent to cancel.

​
Response Format

The endpoint returns an empty JSON object on success: 
{}

​
Examples

​
Cancel a payment intent

curl -X POST 'https://api.harmony.compago.com/api/payment-intent/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cancel' \
  -H 'x-api-key: YOUR_API_KEY'

​
Cancel with error handling

async function cancelPaymentIntent(paymentIntentId) {
  try {
    const response = await fetch(
      `https://api.harmony.compago.com/api/payment-intent/${paymentIntentId}/cancel`,
      {
        method: 'POST',
        headers: { 'x-api-key': 'YOUR_API_KEY' }
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error('Payment intent not found');
      } else if (response.status === 400) {
        const error = await response.json();
        throw new Error(`Cannot cancel: ${error.message}`);
      } else if (response.status === 401) {
        throw new Error('Invalid API key');
      }
      throw new Error(`Unexpected error: ${response.status}`);
    }

    return true;
  } catch (error) {
    console.error('Error cancelling payment intent:', error.message);
    throw error;
  }
}

// Usage
try {
  await cancelPaymentIntent('aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');
  console.log('Successfully cancelled');
} catch (error) {
  console.error('Cancellation failed:', error.message);
}

​
Error Responses

​
400
error
Cannot cancel payment intent - The payment intent is not in PENDING status.Common reasons:
  • Payment intent status is CONFIRMED (already paid)
  • Payment intent status is CANCELLED (already cancelled)
​
404
error
Payment intent not found - No payment intent with the specified ID exists in your organization.
​
401
error
Unauthorized - Missing or invalid API key.

​
What Happens After Cancellation

After a payment intent is successfully cancelled:
  1. Status Change: The status changes from PENDING to CANCELLED
  2. Terminal Notification: The associated terminal (if any) is notified
  3. Irreversible: The cancellation cannot be undone
  4. New Intent Required: If payment is still needed, create a new payment intent

​
Next Steps

Create Payment Intent

Create a new payment intent to replace the cancelled one

API Reference

View the full API reference for the cancel endpoint