> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Decision guide: Void vs refund

> Use this guide to help you choose between voiding or refunding a Pay In transaction

When you need to cancel a transaction, choosing between void and refund affects both timing and costs. Void cancels unsettled transactions before funds are transferred, while refund returns funds after settlement. This guide helps you determine which method to use based on transaction status and timing.

## Decision tree

Use this interactive decision tree to determine whether to void or refund a transaction based on its current status.

#### Decision guide: Void vs refund

* If the transaction is in an open batch and all void conditions are true (TransStatus = 11 or 1, SettlementStatus = 0, and current time is before batch cutoff) → **Void** the transaction to cancel it before the batch closes, avoiding interchange fees.
* If the transaction is in an open batch but one or more void conditions are false → **Refund** the transaction, even though the batch is still open.
* If the batch is closed and SettlementStatus = 1 (In Transit) → **Refund** — the transaction is locked for processing and can't be voided.
* If the batch is closed and SettlementStatus = 2 (Transferred) or 3 (Funded) → **Refund** — the transaction has settled and funds have been transferred.

### Deciding factor: `SettlementStatus`

A transaction's `SettlementStatus` determines which method you can use. Query the transaction, read its `SettlementStatus`, and apply this rule:

| SettlementStatus                                     | What it means                       | Method     |
| ---------------------------------------------------- | ----------------------------------- | ---------- |
| `0` (Pending)                                        | In an open batch, before the cutoff | **Void**   |
| `1` (In Transit), `2` (Transferred), or `3` (Funded) | Settlement has begun or completed   | **Refund** |

Void is available only while `SettlementStatus` is `0` and the batch is still open (before the cutoff). After settlement begins (`SettlementStatus` is `1` or higher), the transaction can no longer be voided and you refund it instead.

## Recommended strategy by use case

Choose the right cancellation method based on transaction timing and status. Here's a quick reference:

| **Use case**                              | **Method** | **Key requirement**                                           |
| ----------------------------------------- | ---------- | ------------------------------------------------------------- |
| Same-day cancellation before batch closes | Void       | Current time \< Batch cutoff (default 5 PM ET)                |
| Cancel authorized transaction             | Void       | TransStatus = 11 (Authorized), SettlementStatus = 0 (Pending) |
| Cancel captured transaction same-day      | Void       | TransStatus = 1 (Captured), SettlementStatus = 0 (Pending)    |
| Cancel after batch closes                 | Refund     | SettlementStatus = 1 (In Transit) or higher                   |
| Return funds after settlement             | Refund     | SettlementStatus = 2 (Transferred) or 3 (Funded)              |
| Partial amount return                     | Refund     | Any settled transaction                                       |
| Customer requested cancellation next day  | Refund     | Batch already closed                                          |

## Void

Void immediately cancels a transaction before the batch closes and before funds are transferred. This is the preferred method for same-day cancellations because it avoids interchange fees and ensures funds never leave the customer's account.

Use void when:

* The transaction is still in an open batch before the cutoff time
* You need to cancel an authorized or captured transaction same-day
* You want to avoid interchange fees on the cancelled transaction
* The customer requests cancellation before end of business day

Void is available when:

* `TransStatus` is 11 (Authorized) or 1 (Captured)
* `SettlementStatus` is 0 (Pending)
* Current time is before batch cutoff (default 5 PM ET, configurable per merchant)
* `BatchStatus` is 0 (Open)

### Void implementation

Call the void endpoint with the transaction ID to immediately cancel the transaction:

```bash
POST /v2/MoneyIn/void/{transId}
```

The transaction will be marked as voided and removed from the settlement batch. No funds will be transferred from the customer's account.

### Void best practices

Follow these best practices when implementing void functionality:

* Check transaction status before attempting void to verify eligibility
* Implement void functionality in your customer service or admin interfaces
* Set up monitoring for batch cutoff times to alert staff of void deadlines
* Log all void attempts including successes and failures for audit trails
* Display clear messaging to users about void vs refund timing differences

## Refund

Refund creates a new offsetting transaction that returns funds to the customer after settlement has begun or completed. Use refunds for any transaction that can no longer be voided due to batch closure or settlement status.

Use refund when:

* The batch has closed and transaction is in transit for settlement
* The transaction has already settled and funds were transferred
* You need to return a partial amount to the customer
* The customer requests a return after the void window has passed

Refund is required when:

* `SettlementStatus` is 1 (In Transit), 2 (Transferred), or 3 (Funded)
* The batch cutoff time has passed
* Any transaction that can't meet void eligibility criteria

### Refund implementation

Call the refund endpoint with the transaction ID and amount to process the refund:

```bash
POST /v2/MoneyIn/refund/{transId}/{amount}
```

Both `transId` and `amount` are **URL path parameters**. There's no amount field in the request body.

* `transId` — original transaction ID to refund.
* `amount` — refund amount in the transaction's currency (for example, `25.00`), not in cents. Pass `0` for a full refund, or a non-zero value for a partial refund. The amount can't exceed the original total minus any service fees.

Because the amount is in the path, a full refund and a partial refund call the same endpoint with a different value:

```bash
# Full refund — 0 refunds the original total, minus any service fee
POST /v2/MoneyIn/refund/10-3ffa27df-b171-44e0-b251-e95fbfc7a723/0

# Partial refund — return 25.00 of a larger original transaction
POST /v2/MoneyIn/refund/10-3ffa27df-b171-44e0-b251-e95fbfc7a723/25.00
```

In v2, a full refund also has a dedicated endpoint with no amount segment: `POST /v2/MoneyIn/refund/{transId}`. The `{transId}/{amount}` form is the partial-refund endpoint, where passing `0` performs a full refund as a convenience.

The refund creates a new transaction that offsets the original payment. Funds typically return to the customer's account in 2 to 3 business days, though it may take up to 5 to 7 business days depending on the customer's bank.

### Refund best practices

Follow these best practices when implementing refund functionality:

* Store original transaction IDs to enable easy refund processing
* Implement partial refund support for flexible customer service
* Set up webhooks to track refund processing status and completion
* Communicate refund timeline to customers (2-3 business days typical)
* Log all refund transactions with reasons for audit and reporting purposes
* Consider implementing refund approval workflows for large amounts

## Status field reference

Understanding transaction and settlement status codes helps you determine void or refund eligibility programmatically.

### Transaction status

Use the `TransStatus` to help determine if a transaction can be voided.

| Code | Status     | Description                                                                 |
| ---- | ---------- | --------------------------------------------------------------------------- |
| 11   | Authorized | Payment authorized but not yet captured, eligible for void if in open batch |
| 1    | Captured   | Payment captured and will be settled, eligible for void if in open batch    |

### Settlement status

Use the `SettlementStatus` to understand if a transaction has been settled and how to handle canceling it.

| Code | Status      | Description                                     | Void eligible?         | Refund required? |
| ---- | ----------- | ----------------------------------------------- | ---------------------- | ---------------- |
| 0    | Pending     | Transaction in open batch awaiting settlement   | Yes (if before cutoff) | No               |
| 1    | In Transit  | Batch closed, transaction locked for processing | No                     | Yes              |
| 2    | Transferred | Transaction settled to merchant account         | No                     | Yes              |
| 3    | Funded      | Funds available in merchant account             | No                     | Yes              |

### Batch status

Use `BatchStatus` to determine if the batch is still open for voids.

| Code | Status | Description                                           |
| ---- | ------ | ----------------------------------------------------- |
| 0    | Open   | Batch accepting transactions, void still possible     |
| 1    | Closed | Batch closed for processing, void no longer available |

## Timing considerations

Batch cutoff time is critical for void eligibility. Understanding your merchant's cutoff schedule ensures you use the correct cancellation method. Here are key timing considerations:

* **Default cutoff**: 5 PM ET
* **Configurable**: Per merchant account settings
* **Timezone**: Always Eastern Time regardless of merchant location
* **Weekend/holiday**: Batches may close earlier or follow modified schedules

Processing timelines differ between voids and refunds:

**Void timeline:**

* Immediate cancellation when executed
* Funds never leave customer account
* No return timeline needed
* Must be executed before batch cutoff

**Refund timeline:**

* Refunds are initiated immediately
* Settlement completes in 1 business day (if transaction was in transit)
* Funds are typically returned to customer in 2 to 3 business days
* May take up to 5 to 7 business days for the funds to be returned depending on customer's bank

**Implementation tips for timing**

Implement these features to handle timing correctly:

* Query current batch status before presenting void option to users
* Display countdown timer showing time remaining until batch cutoff
* Automatically switch UI from void to refund option after cutoff passes
* Store merchant-specific cutoff times if they differ from defaults
* Account for timezone conversions when displaying cutoff times to users

## Quick reference

This section provides quick links to relevant API endpoints and integration guides mentioned in the decision tree and throughout this guide.

#### Transaction Cancellation APIs

**API References:**

* [Void transaction API](/developers/api-reference/moneyinV2/void-a-transaction)
* [Refund transaction API](/developers/api-reference/moneyinV2/refund-a-settled-transaction)
* [Get transaction details API](/developers/api-reference/moneyin/get-details-for-a-processed-transaction)
* [Query Batch status API (org)](/developers/api-reference/query/get-list-of-batches-for-an-organization)
* [Query Batch status API (paypoint)](/developers/api-reference/query/get-list-of-batches-for-an-entrypoint)

**Integration Guides:**

* [Make a sale transaction](/guides/pay-in-developer-transactions-create)
* [Cancel a Pay In transaction with the API](/guides/pay-in-developer-transactions-cancel)
* [Cancel a Pay In transaction (Portal)](/guides/pay-in-portal-transactions-cancel)

#### Status Codes & Reference

* [Transaction statuses](/guides/pay-in-status-reference#money-in-transaction-status)
* [Settlement status codes](/guides/pay-in-status-reference#payment-funding-status)

#### Reporting & Monitoring

**API References:**

* [List transactions for paypoint](/developers/api-reference/query/get-list-of-transactions-for-an-entrypoint)

**Integration Guides:**

* [Reporting overview](/guides/pay-ops-reporting-overview)