> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

## [API Reference](/api-reference/transaction)

# Transaction Statuses

When processing payments through Mercoa, transactions go through various statuses that reflect their progress through the payment lifecycle. Understanding these statuses is crucial for tracking payments and troubleshooting issues.

## ACH Transaction Statuses

Mercoa ACH transactions follow a specific lifecycle with the following statuses:

### Created

When a transaction is first initiated, it enters the `created` status. This indicates that:

* The transaction has been successfully recorded in the system
* Payment details have been validated
* The transaction is ready to be processed
* No funds have moved yet

**Invoice Status**: When a transaction is created, the associated invoice(s) typically remain in the `Scheduled` status until the transaction begins processing.

Transactions are not created when the invoice is scheduled, but rather when the payment is initiated on the scheduled date.

### Pending

Once the transaction begins processing, it moves to the `pending` status. This means:

* The payment is in flight through the ACH network
* Funds are being withdrawn from the source account
* The transaction is being processed by the financial institutions involved
* This status may last 2-5 business days depending on the ACH payment speed

**Invoice Status**: When a transaction moves to pending, the associated invoice(s) status changes to `Pending`, indicating that payment is in progress.

### Completed

A transaction reaches the `completed` status when:

* Funds have been successfully withdrawn from the source account
* Funds have been successfully deposited into the destination account
* The payment has fully settled
* No further action is required

**Invoice Status**: When a transaction is completed, the associated invoice(s) status changes to `Paid`, indicating that the payment has been successfully processed and settled.

There are cases where a transaction may be completed but later reversed. This can happen if the destination account is closed or frozen, or if the transaction is disputed.

### Reversed

A transaction enters the `reversed` status when:

* Funds were successfully pulled from the source account
* The system could not deliver funds to the destination account
* Funds are being held in a wallet or intermediate account

Common reasons for reversals include:

* Invalid destination account information
* Destination account is closed or frozen
* Compliance or risk issues with the destination

**Invoice Status**: When a transaction is reversed, the associated invoice(s) status changes to `Failed`. However, since the funds are held in a wallet, these invoices can be rescheduled with an updated destination account.

If a transaction is reversed, the source invoice(s) that were used to create the transaction can be rescheduled for payment with an updated destination account, and Mercoa will automatically use the funds in the wallet to skip the standard two-day ACH hold.

### Returned

A transaction is marked as `returned` when:

* The attempt to withdraw funds from the source account failed
* No funds were successfully moved
* The transaction cannot proceed as initiated

Common reasons for returns include:

* Insufficient funds in the source account
* Invalid source account information
* Source account is closed or frozen
* The account holder has placed a stop payment

**Invoice Status**: When a transaction is returned, the associated invoice(s) status changes to `Failed`. Since no funds were moved, these invoices will need to be rescheduled with a valid source account or sufficient funds.

## Invoice Status Lifecycle

The relationship between transaction statuses and invoice statuses can be summarized as follows:

| Transaction Status | Invoice Status | Description                                                    |
| ------------------ | -------------- | -------------------------------------------------------------- |
| Created            | Scheduled      | Invoice is scheduled for payment but processing hasn't started |
| Pending            | Pending        | Payment is in progress through the ACH network                 |
| Completed          | Paid           | Payment has been successfully processed and settled            |
| Reversed           | Failed         | Funds were pulled from source but couldn't reach destination   |
| Returned           | Failed         | Attempt to withdraw funds from source failed                   |

## Handling Failed Transactions

When a transaction enters either the `reversed` or `returned` status, it's important to:

1. Check the failure reason provided in the transaction details
2. Verify the payment method information for accuracy
3. Ensure sufficient funds are available in the source account
4. Contact the account holders if necessary to resolve any issues
5. Initiate a new transaction once the underlying issue is resolved

## Rescheduling Failed Payments

For invoices with failed payments:

* **Reversed Transactions**: Update the destination payment method and reschedule the payment. Mercoa will use the funds already held in the wallet to expedite the payment.
* **Returned Transactions**: Update the source payment method or ensure sufficient funds are available, then reschedule the payment.