Skip to main content

Cancel Checkout Order

Cancel an incomplete or pending checkout order by order reference

​
Overview

The Cancel Order API allows you to invalidate a checkout order that has not yet been completed. This is useful when a customer abandons a payment flow, an order expires, or you need to programmatically void a pending transaction before any funds are captured.
Cancel Order applies only to orders that have not been paid. For completed transactions where funds have already been collected, use the Refund API instead.

​
When to Use

ScenarioAction
Customer abandons the checkout pageCancel the pending order
Order session expires on your platformCancel to clean up the order
Merchant needs to void an order before paymentCancel the order
Transaction completed and funds capturedUse Refund instead

​
Cancel an Order

To cancel an order, send a POST request to /v1/checkout/order/cancel with the orderReference of the order you want to cancel. 
  curl --request POST \
    --url https://api.nomba.com/v1/checkout/order/cancel \
    --header 'Content-Type: application/json' \
    --data '{
      "orderReference": "OD-69923-2e102708-ee34-4a29-b713-a826ca928a12"
    }'

​
Request Parameters

ParameterTypeRequiredDescription
orderReferencestringYesThe unique reference of the checkout order to cancel. This is the orderReference returned when the order was created.

​
Important Considerations

​
Order Status

This endpoint only works on incomplete or pending orders. Attempting to cancel an already completed or paid order will return an error.

​
Idempotency

If an order is already cancelled, subsequent cancel requests for the same orderReference will return an error. Always check the success field in the response to confirm the cancellation.

​
Best Practices

  1. Cancel promptly: Cancel orders as soon as you know they will not be completed to keep your order state clean.
  2. Distinguish cancel from refund: Cancel is for pre-payment orders; refund is for post-payment transactions. Using the wrong endpoint will result in an error.

​
Next Steps

Create Checkout Order

Learn how to create a checkout order

Verify Transactions

Verify transaction status after a payment attempt

Refund a Checkout Order

Process refunds for completed transactions