API Reference

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.

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.

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.

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:

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.