Invoice status flow

The status of invoices varies depending on the timing and the amount of cryptocurrency sent by the end user to the invoice's receiving address.

When updating payment status on your side, you will want to look for the status, statusContext and paymentStatus attribute values when polling the Read Invoice endpoint that returns invoice details by its ID.

• The status attribute value represents the current status of the invoice, indicating whether Txn is currently waiting for payment, is busy processing payment, or if the invoice has expired

• The paymentStatus attribute value provides information on whether the payment was made on time within 20 minutes or if the payment is late, meaning the cryptocurrency was received after the invoice expired

• The statusContext attribute value provides information on whether the end-user made their payment in full, underpaid, or overpaid the invoice

You will find possible attribute value combinations in the table below.

status	statusContext	paymentStatus	Final state?	Description
pending	unpaid	expecting	no	Invoice created, awaiting transaction.
expired	unpaid	expecting	no	No payment was received within 20 minutes.
processing	unpaid	onTime late	no	Payment detected, awaiting confirmations.
completed	full underpaid overpaid	onTime late	yes	Invoice completed, funds credited to the merchant's account on Txn.
on_hold	unpaid	expecting	no	Txn isn’t comfortable with the payment risk level. The payment is subject to further review by Txn compliance.
cancelled	unpaid	expecting onTime late	yes	No payment was received within 7 days (168hrs)
rejected	unpaid	expecting	yes	Invoice was rejected due to risk payment rejected by Txn Compliance

For better context, below is the generalized invoice process flow that visualizes the flow of invoice statuses.

For more convenience, we've split the above process flow into separate payment flows that you will want to handle on your side.

Happy Flow

• The end-user sends the exact amount of crypto they have been asked to send

• The end-user sends their crypto within 20 minutes

• The merchant receives the invoice amount minus processing fees in their account

Underpaid Flow

• The end-user sends less crypto than they have been asked to send

• The end-user sends their crypto within 20 minutes

• Txn applies the spot exchange rate to the received amount of crypto

• The merchant receives the result of the currency conversion

Overpaid Flow

• The end-user sends more crypto than they have been asked to send

• The end-user sends their crypto within 20 minutes

• Txn applies the spot exchange rate to the received amount of crypto

• The merchant receives the result of the currency conversion

Late Payment Flow

• The end-user sends either the exact amount of crypto, less crypto, or more crypto than they have been asked to send

• The end-user sends their crypto within 20 minutes

• Txn applies the spot exchange rate to the received amount of crypto

• The merchant receives the result of the currency conversion

Risk Payment Flow

• The cryptocurrency payment comes from a source that is connected to illegal activities, e.g., dark markets, drug markets, sanctioned entities, etc

• Txn puts the payment on hold as it is subject to further review by the Txn Compliance team

• The Txn Compliance team decides whether the payment must be rejected and sent back to the originator or if it can be released

• If the latter, Txn applies the spot exchange rate to the received amount of crypto

• The merchant receives the result of the currency conversion