DEV Community: poetic

What edge cases would you test for stablecoin checkout webhooks?

poetic — Sat, 11 Jul 2026 07:27:18 +0000

I'm building ChainPay, a stablecoin checkout for WooCommerce, SaaS products, Telegram sellers, and agent workflows.

The wallet UI is only one part of the problem. The part I keep coming back to is payment state: webhook retries, late payments, partial payments, duplicated events, and what happens when the customer closes the checkout tab.

Here is the checklist I am using right now:

exact payment within the expiry window
payment after expiry
partial payment
overpayment
duplicate webhook delivery
webhook delivered before the customer returns to the merchant site
order cancelled before payment confirmation
chain confirmation delay
customer pays from an exchange and cannot control the exact timing

For state, I am leaning toward:

pending -> confirming -> paid

with separate terminal states for expired, underpaid, overpaid, and cancelled.

I wrote a short implementation note here for context: https://chainpay.hashnode.dev/webhook-idempotency-for-stablecoin-checkout

If you have built crypto checkout, marketplace payments, billing webhooks, or webhook-heavy SaaS integrations: what edge cases would you add before calling this production-ready?

Webhook idempotency for stablecoin checkout

poetic — Fri, 10 Jul 2026 01:47:20 +0000

A stablecoin checkout is usually built around one important event: a transaction was detected and the merchant order can move forward.

That sounds simple until retries, duplicate callbacks, delayed confirmations, and partial payments show up.

If your webhook handler is not idempotent, the same blockchain event can accidentally create two business-side effects:

two paid-order transitions
two emails
two license activations
two shipment requests
two accounting records

The blockchain transaction is final. Your application state still needs protection.

A practical webhook rule

Treat every payment event as an input to a state machine, not as a command to blindly mark an order as paid.

For each incoming webhook, I like to check four things before changing merchant state:

Is the event signature valid?
Have we already processed this event id or transaction hash?
Is the target payment intent still in a state that can change?
Does the observed payment match the expected amount, token, chain, and expiry window?

Only after those checks should the order move to a new state.

Example shape

A minimal handler can look like this:

async function handlePaymentWebhook(event) {
  assertValidSignature(event)

  const alreadyProcessed = await db.webhookEvents.find(event.id)
  if (alreadyProcessed) return { ok: true }

  await db.transaction(async (tx) => {
    await tx.webhookEvents.insert({ id: event.id, txHash: event.txHash })

    const payment = await tx.paymentIntents.findForUpdate(event.paymentIntentId)
    if (!payment) return

    if (!["pending", "underpaid"].includes(payment.status)) return

    const nextStatus = classifyPayment(payment, event)

    if (nextStatus !== payment.status) {
      await tx.paymentIntents.update(payment.id, { status: nextStatus })
      await tx.orderEvents.insert({ orderId: payment.orderId, type: nextStatus })
    }
  })

  return { ok: true }
}

The important part is not the exact code. It is the constraint: the event record and the order transition should be committed together.

If the process crashes halfway through, retrying the webhook should either complete the transition once or safely return without repeating side effects.

States worth modeling early

For USDT or USDC checkout, I would avoid only having pending and paid.

At minimum, model:

pending
paid
expired
underpaid
overpaid
wrong_network
manual_review

Those states make support and merchant dashboards much clearer. They also prevent your code from pretending every payment problem is a binary success/failure case.

Why I am thinking about this

I am building ChainPay, a stablecoin checkout for merchants, WooCommerce stores, SaaS apps, Telegram sellers, and API workflows.

The goal is not just to display a QR code. The harder part is making payment state boring and predictable for the merchant.

Docs:
https://chainpay.to/docs?utm_source=devto&utm_medium=article&utm_campaign=webhook-idempotency-2026-07

If you have implemented payment webhooks before, what is the failure case you always design for first?

Designing a stablecoin checkout that does not break order state

poetic — Thu, 09 Jul 2026 01:34:12 +0000

When teams add USDT or other stablecoin payments to a store, the first implementation usually looks simple: show a wallet address, wait for a transaction, then mark the order as paid.

That works for a demo. It breaks down in production.

The hard part is not generating a payment request. The hard part is keeping order state honest when real customers behave like real customers:

they choose the wrong network
they send a partial amount
they pay after the order expires
they send two transactions instead of one
they close the checkout page and come back later
your webhook is delayed or retried
your store needs a clean answer: pending, paid, expired, underpaid, or overpaid

A practical stablecoin checkout needs a small state machine, not just a QR code.

The pattern I prefer

For each checkout session, create one payment intent with:

the requested amount and settlement currency
the chain/network expected for the transfer
the receiving address
an expiry timestamp
the merchant order reference
a server-side status field

Then treat blockchain detection as an input to the state machine, not as the state machine itself.

For example:

The customer opens checkout and the order is pending.
A matching transaction arrives before expiry and the order becomes paid.
A smaller matching transaction arrives and the order becomes underpaid.
A transaction arrives after expiry and the order needs manual review or refund handling.
The webhook retries the same transaction and the system ignores the duplicate.

That last point matters. Payment systems should be idempotent by default. A retry should never create a second successful order.

Where merchants usually get stuck

Most small merchants and SaaS founders do not want to run chain monitors, maintain wallet address logic, write webhook retry handling, or explain network mismatches to customers. They want a checkout link and a clean payment result.

That is the gap I am trying to solve with ChainPay.

ChainPay is a lightweight stablecoin checkout for stores, SaaS products, WooCommerce sites, Telegram businesses, and AI agents. The goal is simple: let a merchant accept USDT payments without building payment infrastructure from scratch.

Current focus:

simple checkout links
USDT payment collection
merchant dashboard
WooCommerce use cases
API-friendly checkout for AI agents and SaaS apps

I am currently collecting early feedback before launch.

Product Hunt pre-launch page:
https://www.producthunt.com/products/chainpay?launch=chainpay

Website:
https://chainpay.to/

If you have built crypto checkout, stablecoin billing, WooCommerce payments, or agent payments, I would be interested in what failure cases you think every checkout should handle from day one.

How to Accept USDT Payments in Your Store or SaaS App

poetic — Mon, 06 Jul 2026 11:46:41 +0000

If you run a cross-border store, SaaS product, digital download business or Telegram-based service, card payments are not always the cleanest option.

Stripe and PayPal are excellent products, but they are not equally available to every merchant, every country, or every product category. Some merchants deal with chargebacks. Some sell to customers who already prefer stablecoins. Some simply need a second payment rail when card payments fail.

That is where USDT and USDC checkout can be useful.

This article walks through the simplest integration model: create a payment order, send the buyer to a hosted checkout page, receive a signed webhook, and mark your own order as paid.

The example uses ChainPay, a stablecoin checkout product I am building, but the architecture applies to most crypto payment gateways.

When stablecoin checkout makes sense

Stablecoin checkout is not a replacement for card payments in every business. It works best when your customers already understand crypto, or when the alternative payment options are painful.

Good examples:

Cross-border ecommerce stores with buyers in multiple regions
SaaS products serving developers, Web3 users or global customers
Digital products where chargebacks are a major risk
Telegram sellers who already settle manually in USDT
AI tools, API products or automation platforms that need programmable checkout

The main benefit is final settlement. Once a USDT or USDC payment is confirmed on-chain, there is no card-network chargeback flow. The tradeoff is user education: the customer must know how to pay with a wallet or exchange account.

Three ways to add USDT checkout

1. Use a plugin

If you run WooCommerce, this is the fastest path. Install a payment gateway plugin, paste your API keys, run a sandbox test, and enable the payment method at checkout.

This is the best option for store owners who do not want to write code.

2. Use a hosted checkout API

This is the best option for SaaS products, custom stores and developer-led businesses.

Your backend creates a payment order through an API. The payment gateway returns a checkout URL. The customer pays on that hosted page. Your backend receives a webhook when the order is paid.

This feels similar to integrating a normal payment gateway, except the settlement happens on-chain.

3. Build your own wallet infrastructure

You can run nodes, generate addresses, monitor blockchains and sweep funds yourself. This gives maximum control, but it is usually not worth it unless crypto payment infrastructure is your core business.

For most merchants, hosted checkout is the fastest safe path.

The integration flow

The core flow looks like this:

Your customer places an order.
Your backend calls POST /v1/orders.
ChainPay returns a payment_url.
You redirect the customer to the hosted checkout page.
The customer pays USDT or USDC.
ChainPay sends a signed webhook to your callback_url.
Your backend verifies the signature and marks the order as paid.

The important part is that your system should trust the webhook only after verifying the signature. Do not mark an order paid just because a random HTTP request says it is paid.

A minimal create-order request

A create-order request contains four required fields:

merchant_order_no: your own unique order ID
chain: TRON, BSC or POLYGON
token: USDT or USDC
amount: the payment amount as a string, for example "100.00"

In a real integration, you should also send:

callback_url: where ChainPay should send status updates
success_url: where the hosted checkout should send the buyer after payment
cancel_url: where the buyer should go if they cancel
Idempotency-Key: usually the same value as merchant_order_no

That last field matters. If your backend retries the request, the idempotency key prevents duplicate payment orders.

Webhook handling

When the customer pays, ChainPay sends a webhook with fields such as:

event: order.paid
order_no: the ChainPay system order number
merchant_order_no: your original order ID
chain
token
amount
status
tx_hash
paid_at

Your webhook handler should do four things:

Read the raw request body.
Verify the X-ChainPay-Signature header using your webhook secret.
Check that the amount and merchant_order_no match your internal order.
Mark the order paid only when status is paid.

This is the difference between a demo integration and a production-ready one. Signature verification is not optional.

Why stablecoins instead of any crypto?

Many crypto payment products advertise support for dozens of coins. That sounds good, but most merchants do not actually want to manage dozens of assets.

For practical commerce, stablecoins are usually enough.

USDT and USDC avoid the volatility problem at checkout. A buyer pays 100 USDT; the merchant expects roughly 100 dollars of value. There is no need to explain why a DOGE, SHIB or BTC amount changed during checkout.

This is why ChainPay is intentionally focused on USDT and USDC instead of trying to support every token.

WooCommerce path

For WooCommerce stores, the fastest path is the plugin flow:

Install the ChainPay for WooCommerce plugin.
Create a test API key in ChainPay.
Paste the API key, API secret and webhook secret into WooCommerce settings.
Run the end-to-end sandbox test.
Switch to a live key when the test order and webhook work.

The sandbox step is important. It lets you test order creation, simulated payment and webhook delivery before accepting real funds.

Common mistakes

Wrong chain

A customer might send BEP20 USDT to a TRON address, or vice versa. Your checkout page should make the selected chain obvious.

Wrong amount

Do not fulfill an order until the exact expected amount is confirmed. If the buyer underpays, keep the order pending and ask them to complete the payment.

Trusting webhooks without verification

Always verify the webhook signature against the raw body. Never parse JSON and re-stringify it before checking the signature, because the byte sequence may change.

No idempotency

Network retries happen. Your create-order endpoint should be safe to call more than once with the same merchant order number.

Who should try this?

Stablecoin checkout is a good fit if:

Your customers already use USDT or USDC
You sell globally and card acceptance is inconsistent
You want a backup rail beside Stripe or PayPal
You sell digital products where chargebacks are painful
You are a developer and want a simple API + webhook model

It is not a good fit if your customers have never touched crypto and you do not want to educate them.

Final thought

A good crypto checkout should feel boring. Create order, redirect, receive webhook, fulfill order. The blockchain part should be hidden behind a reliable payment flow.

That is the direction I am building ChainPay toward: stablecoins only, hosted checkout, WooCommerce support, API-first integration, Telegram Bot, and MCP / OpenAPI for AI-assisted workflows.

You can try the API and sandbox here:
https://chainpay.to/docs?utm_source=devto&utm_medium=article&utm_campaign=api-stablecoin-2026-07&utm_content=footer-cta

WooCommerce plugin guide:
https://chainpay.to/integrations/wordpress?utm_source=devto&utm_medium=article&utm_campaign=woocommerce-plugin-2026-07&utm_content=footer-cta