Cancel Transaction

Cancel a pending transaction before it’s processed

DELETE /v1/transactions/{transactionId}

cURL

curl -X DELETE "https://api.unipay.com/v1/transactions/tx_abcdef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

{
  "transactionId": "tx_abcdef1234567890",
  "status": "cancelled",
  "cancelledAt": "2026-04-22T12:35:00Z"
}

Cancel a pending transaction that hasn’t been processed yet. Only works for transactions in pending status.

Path Parameters

transactionId · string · required

The unique transaction identifier returned from transaction creation

Response

transactionId · string

The cancelled transaction identifier

status · string

New status: cancelled

cancelledAt · string

Cancellation timestamp (ISO 8601)

cURL

curl -X DELETE "https://api.unipay.com/v1/transactions/tx_abcdef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response

{
  "transactionId": "tx_abcdef1234567890",
  "status": "cancelled",
  "cancelledAt": "2026-04-22T12:35:00Z"
}

Cancellation Rules

When You Can Cancel

Status	Can Cancel	Reason
pending	✅ Yes	Transaction not yet processed
processing	❌ No	Already being processed
completed	❌ No	Transaction confirmed on-chain
failed	❌ No	Transaction already failed

Mode-Specific Behavior

Wallet Mode:

• Can cancel before transaction is broadcast to network
• Once broadcast, cancellation is not possible
• Network fees may still apply if partially processed

Private Mode:

• Can cancel before funds are sent to ephemeral address
• Cannot cancel after deposit is detected
• Routing fees are not charged for cancelled transactions

Refund Policy

Automatic Refunds

Cancelled transactions receive automatic refunds:

• Wallet Mode: No funds were deducted (transaction never broadcast)
• Private Mode: No deposit made, no refund needed

Partial Processing

If cancellation occurs during processing:

• Network fees may be non-refundable
• Routing fees are refunded for private mode
• Original assets remain in sender wallet

Error Responses

error.code · string

Error code identifier

error.message · string

Human-readable error message

error.details · object

Additional error context

Common Errors

Code	Description
TRANSACTION_NOT_FOUND	Transaction ID doesn’t exist
CANNOT_CANCEL	Transaction status doesn’t allow cancellation
ALREADY_PROCESSED	Transaction has been processed
UNAUTHORIZED	Not authorized to cancel this transaction

Error Response

{
  "error": {
    "code": "CANNOT_CANCEL",
    "message": "Transaction is already being processed and cannot be cancelled",
    "details": {
      "transactionId": "tx_abcdef1234567890",
      "currentStatus": "processing",
      "allowedStatuses": ["pending"]
    }
  }
}

Best Practices

When to Cancel

• Quote Expiration: Cancel if quote expires before signing
• Price Changes: Cancel if market conditions change significantly
• User Error: Cancel if wrong recipient or amount entered
• Network Issues: Cancel if experiencing connectivity problems

Monitoring Cancellations

// Check if cancellation is possible
const transaction = await getTransactionStatus(transactionId);

if (transaction.status === 'pending') {
  // Safe to cancel
  await cancelTransaction(transactionId);
} else {
  console.log('Cannot cancel - status:', transaction.status);
}

Alternative Actions

If cancellation isn’t possible:

• Monitor Status: Track transaction to completion
• Contact Support: For urgent issues, contact support
• Future Prevention: Use shorter quote expiration times

Rate Limits

Cancellation requests are subject to the same rate limits as other API endpoints:

Tier	Cancellations/Minute
Free	10
Pro	50
Enterprise	200

Next Steps

Get Transaction Status

Check the current status of your transactions

Webhook Notifications

Get real-time updates on transaction status changes