Cancel a Payment

When a payment is initiated, you have the option to cancel it before the payment is confirmed by the customer. This feature is particularly useful when a customer changes their mind about a purchase or if the payment needs to be aborted for any reason.

Cancel Payment Flow

Initiate Cancel Payment

To cancel a payment, send a DELETE request to the Payments endpoint with the paymentId.

Request

$
curl -X DELETE \
>
     -H 'Content-Type: application/json' \
>
     -H 'API-KEY: YOUR_API_KEY' \
>
     -H 'API-SECRET: YOUR_API_SECRET' \
>
     -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
>
     YOUR_API_URL/payments/:paymentId

Response

The response returns the paymentStatus indicating the state of the cancel request.

1
{
2
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
3
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
4
  "paymentStatus": "CANCELLED"
5
}

Payment Status Values

After calling the cancel endpoint, the payment status will transition to one of the following:

Cancel vs Void vs Refund

Understanding when to use each operation:

Error Handling

If you attempt to cancel a payment that has already been completed or settled, you will receive an error response:

1
{
2
  "error": "CANNOT_CANCEL",
3
  "message": "Payment has already been completed and cannot be cancelled",
4
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
5
  "paymentStatus": "COMPLETED"
6
}

In such cases, consider using Void or Refund operations instead.