When an NFT purchase appears stuck, reverted, replaced, or paid without delivering the asset, support should follow evidence rather than guesswork. This workflow helps marketplace teams verify the transaction on the correct chain, separate wallet and network problems from marketplace state errors, protect against duplicate fulfillment, and explain the next step clearly to the buyer.
Overview
A failed NFT transaction is not one condition. A wallet may show a transaction as pending while the network has not included it; an explorer may show a successful payment while the marketplace has failed to update its order; or a transaction may have reverted before the NFT moved. Cross-chain marketplaces add another layer: the same address can exist on several networks, while a transaction hash is meaningful only on the chain where it was submitted.
Begin every investigation by recording four identifiers:
- Order or checkout ID: the marketplace record and item involved.
- Network: the chain selected by the buyer and the chain expected by the order.
- Transaction hash: copied from the wallet or payment provider, not retyped from memory.
- Relevant addresses: the buyer, seller or treasury, NFT contract, and token contract where applicable.
Do not mark an order complete solely because a wallet displayed a success message. Confirm the transaction on the correct chain, check the actual recipient and asset details, and reconcile the result with the marketplace's state-transition rules. A sound NFT checkout solution should move through explicit states such as created, payment detected, confirmed, fulfillment started, fulfilled, failed, or refunded. It should also make repeated webhook deliveries safe through idempotent processing.
For broader operational controls, pair this workflow with the NFT payment gateway monitoring and incident response runbook and the NFT marketplace payment integration testing checklist.
Checklist by scenario
1. The transaction is pending
- Confirm that the hash belongs to the expected network. Search it in that network's recognized block explorer or the explorer supplied by your infrastructure provider.
- Check whether the transaction is actually pending, absent, dropped, or already confirmed. Wallet labels are helpful but are not the final source of network state.
- Review the sender address, destination contract, nonce, gas settings, and transaction type where the explorer exposes them.
- Look for a newer transaction from the same sender using the same nonce. A replacement transaction may have superseded the original.
- Keep the order unfulfilled until the required confirmation policy is met. If the marketplace uses different rules by chain, apply the rule associated with the transaction's network.
Tell the buyer not to submit a second purchase until the first transaction's state is understood. A second attempt can create duplicate orders, additional gas costs, or two valid purchases if both transactions later confirm.
2. The transaction reverted or failed
- Verify the final status on the explorer rather than relying on the wallet notification.
- Record the provider or wallet error code and the human-readable message, if available. Codes vary by wallet, RPC provider, payment gateway, and chain.
- Inspect the call path when possible: insufficient balance, insufficient gas, expired listing, approval failure, invalid signature, paused contract, unavailable inventory, or a contract-level condition can produce different recovery paths.
- Confirm whether the marketplace created an order or reservation before the failed transaction. Release any reservation only through the documented state transition.
- Do not promise a gas refund unless the marketplace's published policy and operating controls support it.
A reverted transaction generally should not be treated as completed NFT delivery. However, the marketplace must still reconcile any off-chain payment record, authorization, or fiat-onramp event before closing the case.
3. The transaction was replaced, sped up, or cancelled
Wallets may allow users to speed up or cancel a transaction by submitting another transaction with the same nonce. Search for all relevant hashes and compare their final states. If the replacement confirms the intended contract call, use the confirmed transaction as the source for fulfillment. If it confirms a cancellation or a different call, leave the original order unresolved until the marketplace's recovery rule is applied.
Support should never ask a buyer to share a seed phrase or private key to resolve a nonce conflict. A legitimate NFT wallet management process needs transaction evidence, not secret credentials.
4. The buyer was charged but did not receive the NFT
- Confirm whether the payment transaction succeeded and identify the exact recipient, amount, token, and chain.
- Check the NFT contract, token ID, ownership record, and destination wallet. The asset may have arrived in a different wallet connected during checkout.
- Compare the on-chain result with the marketplace order. Look for a failed mint, a transfer to an escrow or custodial wallet, a delayed indexing event, or a fulfillment worker error.
- Pause automated retries if they could mint or transfer the asset twice.
- Escalate to engineering or the payment provider when the chain result and marketplace record disagree.
Separate financial recovery from asset recovery. If the payment is final but fulfillment cannot be completed, the team must follow its stated refund, replacement, or manual-delivery policy. Any manual transfer should use controlled approvals and a documented destination address.
5. A duplicate order or duplicate payment exists
Link every transaction to an idempotency key, order ID, wallet address, and item identifier. Determine which transaction, if any, produced the intended asset. Do not automatically refund the first transaction simply because it was created first; ordering can differ between marketplace events and on-chain confirmation. Review both transactions, lock the affected inventory, and route the case through the duplicate-payment policy.
What to double-check
- Chain identity: Network names can look similar in wallets and interfaces. Store a canonical chain identifier in the order record and display the expected network before signing.
- Explorer evidence: Capture the explorer status, block or confirmation information, sender, recipient, contract, token, and event details. A hash alone is not enough.
- Nonce conflicts: Compare pending and confirmed transactions from the sender. Provider mempool views may differ, so use the marketplace's configured RPC and a recognized explorer when checking.
- Gas and native balances: A buyer can hold the payment token but lack the network's native asset for gas. This is different from an insufficient NFT purchase balance.
- Webhook ordering: Payment, transfer, mint, and confirmation events may arrive out of order or more than once. Your NFT payments API should reconcile events against current chain state rather than blindly applying each message.
- Custody boundaries: For custodial wallets, verify the internal ledger, signing queue, and approval record. For non-custodial wallets, do not imply that the marketplace can reverse a final blockchain transfer.
- Refund destination: Confirm whether refunds are sent to the original payment address, the account balance, or another approved destination. Record authorization for any exception.
Marketplace teams can also review the NFT wallet signing policies guide and the custodial versus non-custodial wallet decision guide when defining escalation boundaries.
Common mistakes
- Using the wrong explorer: A valid-looking hash on the wrong chain can create a false “not found” result.
- Fulfilling from a wallet notification: The marketplace should rely on verified chain data and its confirmation policy.
- Retrying automatically after an ambiguous failure: Retries can duplicate mints, transfers, or charges unless each operation is idempotent.
- Confusing payment success with delivery success: A confirmed payment does not prove that the NFT reached the buyer.
- Promising reversibility: Blockchain transfers may be final. Explain what the marketplace can investigate, refund, replace, or manually correct instead.
- Requesting wallet secrets: Support should never request a seed phrase, private key, or unrestricted signing approval.
- Closing tickets without a ledger trail: Store the decision, evidence, operator, timestamps, refund reference, and final order state.
When to revisit
Review this workflow before seasonal planning cycles and whenever the marketplace adds a chain, changes an RPC or payment provider, introduces an embedded wallet, modifies confirmation rules, or changes its refund and payout policy. Re-test pending, reverted, replaced, duplicate, and successful-delivery paths in a controlled environment before a production migration.
During scheduled operations reviews, group incidents by cause rather than only by ticket volume. Track the chain, wallet type, provider, error code, transaction state, time to resolution, duplicate rate, and whether the marketplace or network produced the failure. Use those findings to improve checkout messages, webhook reconciliation, alert thresholds, and escalation ownership.
For each review, verify that explorer references, provider error mappings, supported networks, confirmation guidance, and state-transition rules are still accurate. Keep a customer-facing response ready:
“We are checking the transaction on the network you selected and comparing it with your marketplace order. Please send the order ID, wallet address, network, and transaction hash, but never send a recovery phrase or private key. We will confirm whether the transaction is pending, reverted, replaced, or complete before advising on a retry, delivery, or refund.”
That combination of chain verification, controlled state changes, and clear communication gives support teams a repeatable response without treating every failed NFT transaction as the same problem.