Cancel Payment

This guide explains how to cancel a pre-authorized payment using the appropriate API endpoint. This action is typically performed after a payment has been pre-authorized but before funds are captured or released.

Quick Reference

• Cancel Payment: Releases the pre-authorization hold and cancels the payment.
  • Endpoint: POST v1/payments/{paymentId}/cancel
  • Scope: merchant
  • Key Fields: paymentCancellationReason, paymentCancellationMessage
• When to Use:
  • Cancel: When you want to release the hold and void the pre-authorization (e.g., customer cancels, duplicate, or error).
• Error Codes: See Cancel Payment Error Codes

Overview

• Cancel is used to void a pre-authorization, releasing the hold on the customer's funds. This is useful for customer cancellations, duplicates, or business rule failures.
• Only AUTHORIZED and ACCEPTED payments can be cancelled. This action is irreversible; to collect funds, a new payment must be initiated.

Cancel Pre-Authorized Payment

To cancel a pre-authorized payment, use the following payload:

Sample Request

Sample Request – Cancel Payment

{
  "paymentCancellationReason": "DUPLICATE",
  "paymentCancellationMessage": "string"
}

Typical Cancel Workflow

1. Pre-authorize a payment (status: AUTHORIZED).
2. If the payment should not be completed (e.g., customer cancels, duplicate, error), call the cancel endpoint.
3. The payment status transitions to CANCELLED and the hold is released.
4. If the cancel fails, the status will be FAILED and an error will be returned.

Cancel Statuses

Status	Description
AUTHORIZED	The pre-authorization hold is placed successfully
CANCELLED	The pre-authorization was cancelled
FAILED	The cancel operation failed

Error Handling

• If you attempt to cancel a payment that is not in the AUTHORIZED or ACCEPTED state, an error will be returned.
• See Cancel Payment Error Codes for details on error codes and troubleshooting.

Best Practices

• Always check the payment status before attempting to cancel.
• Cancel unused pre-authorizations promptly to release customer funds.
• Log and monitor all cancel attempts and responses for audit and support.