Cancel Transaction

Cancel Transaction lets you stop a payment flow that was initiated but should no longer be completed—such as when:

• A customer abandons checkout and you want to treat the order as cancelled
• The order is cancelled before payment finishes
• You detect suspicious behavior and want to stop the payment flow

Cancellation typically results in a webhook event like:

• payment.cancelled (with cancelled_by: USER or SYSTEM)

Important Note About API Support

Chapa API v2 does not expose a dedicated "Cancel Payment" endpoint.

That means cancellation is typically handled by:

• The customer canceling checkout, or
• The system canceling due to abandonment/timeout, or
• Your own merchant-side order state rules (mark order cancelled and ignore late signals)

How Cancellation Is Reflected

When a transaction is cancelled, you should expect one or more of the following:

• Verification may show the payment status as cancelled (depending on lifecycle)
• A webhook is delivered:
  • payment.cancelled
  • or sometimes payment.incomplete (with a reason such as TIMEOUT / ABANDONED)

Payment Cancelled Webhook Example

{
  "webhook_type": "payment",
  "event": "payment.cancelled",
  "status": "cancelled",
  "mode": "live",
  "payment_type": "Donation",
  "currency": "ETB",
  "amount": "40000",
  "service_fee": "1200",
  "merchant_reference": "TXN123CANCELLED",
  "chapa_reference": "CHREF123",
  "cancelled_by": "USER",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "251722927727"
  },
  "meta": {
    "order_id": "ORD-99821"
  },
  "created_at": "2025-11-07T13:00:00Z",
  "updated_at": "2025-11-07T13:00:00Z"
}

Recommended Cancellation Handling (Merchant Side)

Even if your system does not actively call a cancel API, you should support cancellation behavior safely.

1) Mark the Order as Cancelled Internally

When your customer cancels the purchase:

• Mark the internal order as cancelled
• Prevent fulfillment
• Decide your policy for late payments (recommended: reject/flag them)

2) Ignore Late Signals Safely

Your system should ensure:

• Once an order is cancelled, you don't fulfill it accidentally
• Webhook processing is idempotent (no double actions)

3) Verify if Needed

If you receive a payment.cancelled webhook, you may still verify the payment reference:

GET /v2/payments/{reference}/verify

Verification is useful if:

• Your customer disputes the cancellation
• You need audit logs for support
• You want to confirm final state before closing the order permanently

Key Fields to Store

When tracking cancelled payments, store:

Common Cancellation Scenarios

User Cancels During Checkout

System Cancels Due to Timeout or Abandonment

Order State Management

Design your order system to handle these states clearly:

Best Practices

• Cancellation is for pending/incomplete flows
• Refunds are for successful payments
• Webhooks are the main way you learn about cancellation outcomes
• Handle all payment states in your order system
• Use idempotent webhook processing to avoid duplicate actions

Next Steps

• Webhooks - Handle payment events in real-time
• Verify Payments - Confirm payment status
• Accept Payments - Full payment integration guide