> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unipayfi.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Transaction

> Cancel a pending transaction before it's processed

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

## Path Parameters

<ParamField path="transactionId" type="string" required>
  The unique transaction identifier returned from transaction creation
</ParamField>

## Response

<ResponseField name="transactionId" type="string">
  The cancelled transaction identifier
</ResponseField>

<ResponseField name="status" type="string">
  New status: `cancelled`
</ResponseField>

<ResponseField name="cancelledAt" type="string">
  Cancellation timestamp (ISO 8601)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.unipay.com/v1/transactions/tx_abcdef1234567890" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.unipay.com/v1/transactions/tx_abcdef1234567890', {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.delete(
    'https://api.unipay.com/v1/transactions/tx_abcdef1234567890',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "transactionId": "tx_abcdef1234567890",
    "status": "cancelled",
    "cancelledAt": "2026-04-22T12:35:00Z"
  }
  ```
</ResponseExample>

## 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

<ResponseField name="error.code" type="string">
  Error code identifier
</ResponseField>

<ResponseField name="error.message" type="string">
  Human-readable error message
</ResponseField>

<ResponseField name="error.details" type="object">
  Additional error context
</ResponseField>

### 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     |

<ResponseExample>
  ```json Error Response theme={null}
  {
    "error": {
      "code": "CANNOT_CANCEL",
      "message": "Transaction is already being processed and cannot be cancelled",
      "details": {
        "transactionId": "tx_abcdef1234567890",
        "currentStatus": "processing",
        "allowedStatuses": ["pending"]
      }
    }
  }
  ```
</ResponseExample>

## 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

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Get Transaction Status" icon="magnifying-glass" href="/api-reference/endpoint/get">
    Check the current status of your transactions
  </Card>

  <Card title="Webhook Notifications" icon="bell" href="/api-reference/endpoint/webhook">
    Get real-time updates on transaction status changes
  </Card>
</CardGroup>