What to Do if A Transaction is Pending or Failed

What to do when a transaction doesn't complete as expected.

Most transactions on YellowCard are completed within a few minutes. If a transaction stays

pending longer than expected or fails, this article walks you through the most common causes and the steps to take.

Understanding Transaction Statuses

Status / Error	What It Means	What to Do
PENDING	The transaction is being processed. This is normal within the standard processing window.	Wait up to the standard processing window. If it persists, check your dashboard for updates.
PENDING_LIQUIDITY	There was an insufficient balance in your YellowCard wallet to complete the transaction.	Top up your wallet balance. The transaction will retry automatically if topped up within 2 hours, after which it will expire.
FAILED	The transaction did not complete. This can be caused by several reasons (see below).	Review the error message or code returned in the API response or your dashboard.
EXPIRED	The transaction timed out before it could be completed.	Retry the transaction after resolving the underlying cause (e.g., low balance, invalid details).

Pending Transactions

My transaction has been pending for a while

Transactions typically complete within minutes. If a transaction remains pending beyond your expected timeframe, here's what to check:

If the transaction shows a PENDING_LIQUIDITY status, your YellowCard wallet balance may

have been too low at the time. Top up your balance to allow the transaction to complete.

Some transactions may be slightly delayed due to provider-side processing. Allow a reasonable

window before escalating.

If the transaction remains stuck and no error is visible on your dashboard, reach out to the

YellowCard support team with the transaction ID for investigation.

PENDING_LIQUIDITY: What you need to know

When a transaction enters PENDING_LIQUIDITY status, it will be held for up to 2 hours.

If your wallet is topped up within that window, the transaction will complete automatically. If not, it will expire, and you will need to retry it.

To avoid this in the future:

• Monitor your wallet balance regularly and set up balance alerts.

• Configure your webhook to listen for the pending_liquidity status so you can act quickly.

• Maintain a sufficient buffer in your YellowCard wallet for expected transaction volumes.

Failed Transactions

Common reasons a transaction fails

Here are the most common causes of failed transactions and how to resolve each:

Unsupported bank or payment method	The destination bank or payment option is not supported for the selected corridor. Review the list of supported banks and payment options for your target country, then retry using a supported option.
Invalid phone number format	The phone number provided was too long, too short, or incorrectly formatted for the destination country. Confirm the correct format and retry with the right number.
Insufficient wallet balance	Your end user's mobile money balance was too low to complete the send request. They should top up their wallet and retry the transaction.
Unsupported country or corridor	The destination country may not be supported at this time. Check the YellowCard coverage page to confirm supported corridors before initiating a transaction.
Error with no visible code	If a transaction fails without a clear error code, contact the YellowCard support team with the transaction ID. The team will investigate and provide an update.

When to Contact Support

Contact the YellowCard support team if a transaction has been pending for an unusually long time

with no status update, a transaction fails repeatedly with no clear error, or you cannot find the

transaction in your dashboard at all. When reaching out, always include your transaction ID, the

destination country, and the error message (if visible).