Crypto payments do not always produce a simple success-or-failure result. This merchant support workflow helps NFT creators, marketplaces, and storefront operators investigate pending or failed payments, handle duplicate orders and refunds, verify customer claims, and document each decision before releasing an NFT or closing a support case.
Overview
An NFT checkout can involve several separate records: an order in your storefront, a wallet connection or payment session, a blockchain transaction, a payment-provider callback, and a fulfillment or minting event. These records may not update at the same time. A customer may see a wallet prompt succeed while the merchant dashboard still shows “pending,” or a payment may be confirmed on-chain without triggering the callback that marks the order as paid.
The first rule is simple: do not refund, fulfill, or reject an order based on a screenshot alone. Match the customer’s claim to a transaction hash, the correct network, the intended receiving address, the token or coin used, and the exact amount received. A blockchain explorer can help confirm what happened, but the explorer result must be interpreted alongside your checkout and provider records.
Keep a written policy for confirmation thresholds, supported assets, refund destinations, payment-provider status meanings, and fee treatment. These details vary by integration and may change after a provider update, marketplace change, or network upgrade. For broader checkout design decisions, see the NFT Payment Gateway Comparison.
Use the following order of operations:
- Pause fulfillment if payment status is unclear.
- Collect the minimum information needed to identify the order and transaction.
- Check the provider, storefront, wallet, and blockchain records separately.
- Classify the case before choosing a refund, retry, manual fulfillment, or rejection.
- Record the decision and evidence for reconciliation and future support.
Checklist by scenario
1. The transaction is pending
Start by confirming whether “pending” refers to the wallet, payment provider, storefront order, or blockchain transaction. Ask the customer for the order number, wallet address used, transaction hash if available, asset and amount, network, and approximate submission time. Do not ask for a seed phrase, private key, or wallet password.
- Check whether the transaction exists on the stated network.
- Confirm whether it is still in the mempool, has failed, or has been confirmed.
- Compare the destination address with the merchant or provider address recorded for that order.
- Check the provider’s callback or webhook log for delivery, retry, and processing errors.
- Keep the order unfulfilled until your stated confirmation threshold is met.
If no transaction exists, the customer may have closed the wallet prompt, rejected the transaction, or experienced a wallet interface error. Explain that a wallet approval screen is not proof of an on-chain payment. If a transaction is pending, avoid promising a completion time; give the customer a review point instead, such as “we will recheck after the network or provider status changes.”
2. The payment failed or used insufficient gas
A failed transaction may consume a network fee even when the NFT sale does not complete. Your support response should distinguish the payment amount from the network fee. The merchant normally cannot reverse a fee that was paid to a network, so do not describe a failed gas payment as a merchant-held charge unless your records show that it was captured by your checkout or provider.
- Capture the failed transaction hash and failure status.
- Check whether the intended payment amount reached the merchant address.
- Identify whether the failure resulted from insufficient balance, an invalid contract call, a fee setting, an expired checkout session, or another integration error.
- Confirm whether the provider created a replacement payment session.
- Offer a new checkout attempt only after confirming that the original order will not be fulfilled twice.
Never instruct a customer to repeat a payment without explaining how duplicate payments will be identified and handled.
3. The customer paid on the wrong network
A payment sent on an unsupported network may not satisfy the order, even if the asset symbol and amount appear correct. Record the network used, token contract where relevant, transaction hash, receiving address, and whether your business controls that address on that network.
Do not imply that funds can always be recovered or bridged. Escalate internally if recovery requires a technical transfer, a provider action, or access to a wallet that is not part of the normal merchant workflow. If the receiving address is not controlled by the merchant or provider, explain that the payment cannot be treated as a confirmed order payment until its status is resolved.
4. The provider shows success, but the order is incomplete
Compare the provider event with the order ID, payment session ID, transaction hash, amount, asset, network, and recipient address. Check whether the callback was delayed, rejected, duplicated, or processed out of sequence. A temporary dashboard mismatch should not lead to a second charge request from the customer.
Use an idempotent order process where possible: the same confirmed payment event should not mint twice, create two shipments, or generate two access grants. If the payment is confirmed and the callback is missing, a trained administrator can follow the documented manual-review process rather than asking the customer to pay again.
5. The customer claims a duplicate charge
Request both transaction hashes or payment references, not just two screenshots. Determine whether the transactions are separate confirmed transfers, one confirmed transfer plus a failed attempt, or a wallet display that duplicated an authorization message.
- Link each transaction to an order and checkout session.
- Check whether either payment already triggered minting, delivery, or token-gated access.
- Identify the true recipient of each transfer.
- Place any refund on hold until duplicate status is verified.
- Record the refund amount, asset, network, and destination decision.
6. The payment is confirmed, but the order must be refunded
Confirm the reason for the refund under your published merchant policy and verify whether the NFT has already been minted, transferred, or claimed. If the asset is already in a customer-controlled wallet, an NFT payment refund may require a return, burn, transfer reversal under the platform’s process, or a separate agreement. Do not promise that an on-chain transfer can be undone.
Verify the refund destination carefully. A refund should generally be sent only to a destination that has been authenticated through the order or a controlled support process. Treat a request to send funds to a new wallet as a risk signal. Use a small test transfer only if it fits your documented process and does not create additional confusion about the final amount.
7. The customer cannot provide a transaction hash
Search by order ID, payment session, wallet address, provider reference, and approximate time if your tools support those fields. Ask the customer to copy the public transaction details from the wallet rather than sending private credentials. If no matching transfer can be found, keep the case in an unpaid or unverified state and explain what evidence is needed for review.
What to double-check
Before approving fulfillment or a refund, complete a transaction investigation worksheet. Store only information needed for operations and compliance; never store seed phrases or private keys.
- Order: order ID, item or token ID, customer contact, purchase date, and current fulfillment status.
- Payment: asset, amount expected, amount received, network, transaction hash, sender, recipient, and confirmation state.
- Provider: payment session ID, callback status, event timestamp, retry history, and any error code.
- Decision: fulfill, wait, reject, retry, partially refund, or fully refund, with the reason and approver.
- Evidence: explorer link, dashboard record, customer message, screenshots where useful, and the date reviewed.
Double-check the destination address character by character using a trusted record. Verify that the token contract and network match your supported configuration. Check whether fees were deducted before receipt, added separately, or retained by a payment provider. Then compare the case with your payout and bookkeeping records. The NFT Payment Reconciliation workflow can help connect individual support cases to monthly sales and fee reviews.
For refund approvals, use this short checklist:
- Payment and order identity are matched.
- Refund reason is permitted under the current merchant policy.
- Minting, transfer, delivery, and access status are checked.
- Refund asset, amount, network, and fee treatment are documented.
- Destination wallet is verified through an appropriate customer check.
- A second reviewer approves high-value, unusual, or manual refunds.
- Refund transaction hash is added to the case after submission.
Common mistakes
- Refunding before investigating: A pending payment may later confirm, creating a duplicate loss or an order that still requires fulfillment.
- Treating a wallet message as final evidence: “Submitted” or “approved” does not necessarily mean the merchant received funds.
- Ignoring the network: The same token name can exist on multiple networks, while the checkout may support only one.
- Requesting sensitive wallet information: Support should never need a seed phrase, private key, or password.
- Sending refunds to a newly supplied address without verification: This can turn a legitimate case into an avoidable loss.
- Retrying callbacks by creating new orders: A recovery process should update the original order when possible and prevent double fulfillment.
- Promising reversal of confirmed transfers: Explain the available merchant process instead of suggesting that blockchain settlement is automatically reversible.
- Failing to preserve evidence: Provider logs, transaction hashes, and decision notes become harder to reconstruct later.
Train support staff to use consistent language: “unverified,” “pending,” “failed,” “confirmed,” and “refunded” should each have a defined operational meaning. If your team uses embedded or external wallets, document how each checkout path reports payment status; the embedded versus external NFT wallet comparison provides useful context for that decision.
When to revisit
Review this workflow before seasonal sales, collection launches, major token-gated campaigns, or any period when support volume is expected to rise. Revisit it immediately when you change a payment gateway, supported asset, wallet integration, marketplace, minting contract, confirmation threshold, or refund policy.
Also schedule a review after a failed callback incident, duplicate fulfillment, wrong-network payment, unexpected fee pattern, or customer dispute. Compare real cases with the worksheet and update the decision tree where staff had to improvise. Confirm that links to provider documentation, status labels, supported networks, and refund capabilities still match your implementation.
At the end of each review, run a controlled test payment and, where appropriate, a test failure or callback retry in a safe environment. Confirm that the order remains idempotent, evidence is captured, and the support team knows who can approve a manual refund. Keep the current workflow version and effective date visible to anyone handling NFT merchant payments.
For each live case, the practical next step is the same: pause uncertain fulfillment, collect the transaction evidence, classify the scenario, obtain the required approval, and communicate only what the records support. That discipline protects customers, reduces duplicate payments, and gives creators and merchants a repeatable foundation for secure NFT checkout operations.