DEV Community: Payneteasy

Your webhook handler assumes the order row already exists. What if it doesn't yet?

Payneteasy — Wed, 16 Sep 2026 07:24:34 +0000

Provider webhooks and your own write path are two separate async processes, and nothing guarantees which one finishes first. Fire off a charge, get a 200 back, kick off the DB write to create the order — and the provider's webhook can land on your endpoint before that write commits, especially under load or a slow transaction.

If the handler does a lookup-or-404, you just told a payment provider your endpoint is broken, and depending on their retry policy you might not see that event again for minutes.

Options I've seen: retry-with-backoff inside the handler, an upsert that tolerates arriving first, or a short queue that holds unmatched events for a few seconds before giving up. Each trades latency for complexity differently.

Genuinely curious what other teams landed on — especially anyone who measured how often this race actually fires in production versus how much handling code it justified.

The authorization hold expires before you capture, and the window is different for every network

Payneteasy — Mon, 14 Sep 2026 18:19:00 +0000

Debugging a delayed-capture flow for a marketplace that holds funds until a courier confirms delivery, sometimes 5-6 days out. Captures started failing with generic decline codes for a subset of orders, no pattern by amount or issuer.

Turned out the auth hold had simply expired. Visa gives you roughly 7 days on a standard hold, Mastercard closer to 30, but issuers can and do shorten that window on their end regardless of what the network default says. Once the hold drops, the processor doesn't send you a webhook telling you it's gone. You just find out when the capture call bounces.

The fix ended up being boring: track hold creation timestamp per network, re-authorize automatically at day 5 for Visa transactions instead of waiting for the courier, and treat capture failures past that window as "needs re-auth" rather than "payment failed" in the retry logic. Customer sees nothing, ledger stays clean.

What surprised me is how little of this is documented anywhere central. Every gateway I checked either buries the expiry window in a PDF or doesn't mention it at all, and you only find the real number by hitting the wall in production.

Anyone tracking hold expiry per-network as a first-class field in their payment state machine, or is everyone just reacting to the decline like I was?

Retrying declines too fast looks like fraud, not persistence

Payneteasy — Sun, 13 Sep 2026 13:42:15 +0000

Soft decline (code 51, insufficient funds) came back on a subscription renewal. Retry logic fired again in 90 seconds because that was the default backoff someone copied from a Stripe blog post years ago. Renewal failed again, and the issuer's risk engine started tagging the card for velocity — three attempts inside five minutes on the same card, same amount, from the same merchant ID reads like a testing pattern to most fraud models, not a legitimate retry.

Pulled six months of retry logs across a billing system: recovery rate on soft declines barely changed between a 4-hour wait and a 24-hour wait. What did change was the false-positive velocity flag rate, which dropped by more than half once retries were spaced past 6 hours. Insufficient funds resolves on payday or when a balance clears, not in the next few minutes, so hammering the network faster buys nothing except a worse risk score on the card.

Ended up mapping backoff intervals to decline code instead of using one universal retry schedule — do-not-honor gets a different curve than insufficient-funds, and both get capped at three attempts before falling back to dunning email.

Curious what intervals other teams landed on for soft-decline retries, and whether anyone has actual conversion data broken out by decline code rather than a flat retry count.

Webhook signatures failed on ~2% of requests until we stopped touching the body

Payneteasy — Sat, 12 Sep 2026 23:04:49 +0000

Spent two days chasing intermittent HMAC verification failures on inbound payment webhooks. Staging passed every time. Production failed roughly 1 in 40 requests, no pattern in payload size or endpoint.

Traced it to Express's body-parser. It parses the raw request into a JS object before our verification middleware runs. We were re-serializing that object with JSON.stringify to compute the HMAC, assuming it would match what the provider signed. It doesn't, reliably.

JSON.stringify doesn't guarantee the same key order, whitespace, or number formatting as whatever serializer the provider used server-side. Most of the time the object happens to stringify back to identical bytes. Sometimes a field with a trailing zero, a differently ordered object, or unicode escaping changes just enough to flip the signature.

The fix was mundane: capture the raw body as a Buffer before any parsing touches it, verify against those exact bytes, then parse for business logic. Two lines of middleware ordering, and the failure rate went to zero over three weeks of traffic.

The provider's docs did say "verify against the raw request body." I read that as a suggestion, not a byte-for-byte requirement.

Anyone else lose time to a framework silently reserializing something before a signature check?

Webhook order is not guaranteed, even from one provider

Payneteasy — Thu, 10 Sep 2026 13:33:38 +0000

Assumed webhooks would arrive in the order events happened. They don't, and the gap shows up on refunds.

Sequence that broke a reconciliation job: charge succeeds, provider fires the charge webhook, our endpoint is slow and times out, provider queues a retry with backoff. Merchant issues a refund seconds later. Refund webhook has no retry needed, goes out immediately, lands before the delayed charge webhook retry completes. Our handler processes "refund" for a charge that, according to our own database, does not exist yet.

Fix was not bigger retries or a longer timeout. It was making the handler check current state before applying any event instead of assuming events arrive as a sequence. Refund webhook checks: does this charge exist as completed? If not, park the event and reprocess after the charge webhook lands, don't drop it and don't error into a dead letter queue silently.

Provider docs list delivery guarantees (at-least-once, retry schedule) but almost none document ordering guarantees between different event types tied to the same object. Timestamps in the payload help, but only if you're willing to hold and resequence, which most webhook handlers aren't built to do.

Anyone handling this with a full event-sourced ledger instead of state checks per event type? Curious if that's overkill for a mid-volume system or the actual right answer.

The 3DS timeout that isn't a timeout

Payneteasy — Thu, 10 Sep 2026 07:00:15 +0000

Set a 10-second timeout on the 3DS challenge step because that's what the gateway docs suggested. Started seeing declines tagged as "customer abandoned challenge" at a rate that didn't match support tickets — users weren't complaining about failed payments nearly as often as the logs implied.

Pulled ACS response times across issuers for one week. Median challenge render was 2.3s. 94th percentile was 11.8s. A handful of issuing banks, mostly outside the US, were consistently rendering the challenge frame past the 10-second mark, then completing authentication successfully a few seconds after our client had already given up and shown the user a decline.

So the customer sees "payment failed," retries, gets charged twice for a split second until the first auth finally lands, and now you're refunding a transaction that technically succeeded on the issuer's side after you'd already told everyone it failed.

Bumped the timeout to 20s for known-slow issuer ranges and the abandonment numbers dropped by more than half. The actual customer abandonment rate — people closing the tab, not opening their banking app — turned out to be much smaller than what the arbitrary timeout was manufacturing.

Anyone tracking ACS response time by issuer BIN as its own metric, separate from overall auth success rate? Feels like it should be standard and I've never seen it in a dashboard by default.

The hold expired before we tried to capture it

Payneteasy — Wed, 09 Sep 2026 09:38:57 +0000

Ran into this reconciling a subscription billing system: authorize now, capture in 48 hours after fraud review clears. Worked fine in testing. In production, roughly 2% of captures started failing with a decline code that looked like insufficient funds but wasn't.

Turned out the issuer had already released the authorization hold. Visa's guideline is 7 days for most MCCs, but individual issuers set their own expiry, and we saw holds die anywhere from 3 to 10 days depending on the card's bank. Nothing in the original auth response tells you when that hold actually dies. You find out when the capture bounces.

Our fraud review queue had a 72-hour SLA on paper. Average was fine. The tail wasn't. A subset of manual reviews sat for 4-6 days, long enough to cross into issuer-specific expiry windows we had no visibility into.

Fix ended up being boring: track auth timestamp separately from order status, re-authorize automatically if capture attempt fails with that specific decline pattern and the auth is older than 3 days, and stop treating "authorized" as a stable state past 72 hours.

Curious how other teams handle this. Do you re-auth automatically, or push the delay back to the review queue instead?

A timeout is not a decline

Payneteasy — Mon, 07 Sep 2026 16:14:19 +0000

A request to the processor times out after 30 seconds. Your code catches the exception and shows the user an error. But the processor might have received the request, processed it, and returned success — the response just never made it back before your timeout fired.

Now you have three states, not two: success, failure, unknown. Most integration code only handles the first two. Retry logic reuses the idempotency key (correct), fires again (also correct) — but the UI already told the customer "payment failed," so they open a new tab and try with a fresh key. Now there are two authorizations against the same card for the same order. Idempotency did exactly what it was built for: protecting against duplicate keys, not duplicate intent.

Fixed this by adding a mandatory reconciliation query before any retry: on timeout, hit a status endpoint with the same key before touching the UI state. Added about 400ms to the worst-case path. Phantom duplicate authorizations from flaky-network merchants dropped to nearly zero — the number matters less than the fact the fix required a network call we'd been skipping to save latency.

Anyone else model "timeout" as its own state in the payment state machine, or does it collapse into failure by default in your stack?

Does your idempotency key cover partial refunds, or just the original charge?

Payneteasy — Wed, 02 Sep 2026 22:16:09 +0000

Most idempotency key discussions stop at "don't double-charge on retry." Fewer teams talk about what happens once a refund enters the picture.

Say a customer gets two partial refunds on the same charge, submitted a few seconds apart by two different support agents — or by one agent double-clicking through a slow UI. If the refund endpoint keys idempotency off (charge_id, amount) alone, the second request looks identical to a retry of the first and gets silently deduped. The customer expected two refunds. They got one.

The fix isn't complicated once you see the gap: the key needs to include something that distinguishes intent, not just the target — a client-generated request ID, a ledger-entry reference, whatever ties the call back to "this specific refund action," not "any refund on this charge."

Curious how other teams have handled this: separate idempotency scope for refunds vs charges, or one scheme that just happens to include enough entropy to avoid the collision?

How to Integrate a Payout API Without the Costly Surprises

Payneteasy — Thu, 27 Aug 2026 11:03:33 +0000

Every withdrawal kickoff starts with the same question: "we already take card payments, how different can sending money out be?"

Different enough that it has its own failure modes. Here is the practical version — what a payout API actually does, where integrations stumble, and the order to do things in so your first real payout is boring.

Paying out is not collecting in reverse

Four things flip when money moves the other way.

There is no authorisation step. A card payment gets authorised, then captured — two moments, and a window between them where you can still walk away. A payout is submitted and then it is in someone else's system. Your "are we sure?" checks have to happen before submission, in your code, because the rail will not hold the door for you.

The failure surface is compliance, not risk. Card payments fail on fraud scoring. Payouts fail on sanctions screening, name mismatch, a closed account, an IBAN that passes checksum but belongs to a different bank. These come back slowly and they come back as text.

Status is asynchronous and multi-step. accepted is not sent and sent is not settled. A payout can sit at "processing" for a business day and then reverse. If your UI shows "Paid" on the API's 200, you will be lying to your users at some point this quarter.

Money leaves an account that must have money in it. Collections top your balance up; payouts drain it. Funding, cut-off times, and weekends become your problem.

The go-live sequence

Going live is a sequence, not a switch. Skip a step and you will do it later, under load, at a worse time.

Sandbox with real edge cases. Not just the happy path: rejected beneficiary, insufficient balance, duplicate reference, late reversal.
Beneficiary validation first. Validate account details as a separate call at the moment the user saves them, not at payout time. It converts a failed payout into a form error.
Idempotency on every submit. One idempotency_key per logical payout, generated by you, stored by you, replayed on every retry. This is the single control that prevents double payments after a timeout.
Webhooks before volume. Poll only as a backstop. Verify signatures, respond 2xx fast, process asynchronously, and make handlers idempotent — every provider redelivers.
Reconciliation on day one. A daily job that matches your ledger to the provider's settlement file and alerts on drift. Not a quarter-end project.
Limits and a kill switch. Per-transaction cap, daily cap, and an operator-flippable freeze. Every team that has had a bad day owns one of these.

Single vs mass payouts

Single payouts are simple and fine at low volume: one request, one beneficiary, one status stream.

Mass payouts (a batch file or bulk endpoint) matter once you are paying hundreds or thousands per cycle. The trap is that a batch is not atomic. Some rows will fail while others succeed, so your code has to reconcile at row level, keep the per-row reference stable, and never resubmit the whole batch to fix three rows. Design for partial success from the first line of code.

The failure modes nobody schedules for

The silent failure. Payout returns accepted, then reverses three days later with a reason code nobody parses. Users see "Paid" and open tickets. Fix: never render terminal state until you receive a terminal webhook.
The duplicate. A gateway timeout at 30s, your retry, two payments. Fix: idempotency keys, always.
The stale balance. Your check for available funds ran before three other payouts settled. Fix: reserve against your own ledger, not the provider's last-known balance.
The name mismatch. Confirmation-of-payee schemes reject "J. Smith" against "John Smith". Fix: validate names at capture and store what the rail expects.
The cut-off. 16:00 local means 16:00 in the rail's timezone, not yours; Friday 16:01 lands on Monday. Fix: put cut-offs in config and show users a real ETA.

Where a platform helps

If you are paying out across many countries, the integration count grows faster than the feature list. A payout layer that already covers 122 countries and 100+ currencies turns "add a new corridor" from an integration project into a configuration change, and gives you one status model and one reconciliation file instead of one per rail.

Full guide, with the FAQ on timing and fees: https://payneteasy.com/blog/payout-api-integration-guide?utm_source=devto&utm_medium=social&utm_campaign=payout-api-integration-guide&utm_content=inline

What is the worst payout bug you have shipped? Mine involved a retry loop and a very patient finance team.

Mastercard adds new controls to virtual card platform, Setting New Integration Standard for PSPs and Merchants

Payneteasy — Tue, 28 Jul 2026 12:59:40 +0000

Mastercard has added Issuer Enforced Controls and upgraded Clearing Controls to its In Control virtual card platform, along with a new Commercial Connect API, with Citi as the first issuer to deploy the full set — a move that sets a new standard for the integration and risk controls PSPs and merchants need to support as virtual card use grows across countries and currencies.

The Commercial Connect API gives customers one integration point to manage virtual cards, addressing what Mastercard calls a common problem. The update also lets companies apply one set of controls across multiple linked virtual cards without exposing card details, and combines card creation with payment initiation in a single step. Issuer Enforced Controls **let issuers set spend limits, transaction caps, and validity periods at the moment a virtual card is created, before it's ever used. **Clearing Controls, upgraded from a 2025 launch, now let corporates and platforms block invalid transactions, apply more detailed rules, and manage payment timing after authorization.

For PSPs and acquiring partners, this is a signal that competitive differentiation in B2B card issuing is shifting toward control granularity and API-first integration rather than the card product itself. Issuer Enforced Controls and upgraded Clearing Controls raise the bar on what issuing/processing partners are expected to offer — pre-authorization risk parameters and post-auth clearing-stage blocking are becoming baseline expectations, not premium features. PSPs working with corporate/B2B card programs should watch whether their own risk and control stack (spend limits, validity periods, granular clearing rules) can match this, since large issuers like Citi are setting the bar.

For merchants, particularly those receiving B2B payments or operating supplier/procurement flows, the embedded VCN expansion (procurement, AP, travel, healthcare) means more of their B2B counterparties will pay via virtual cards embedded directly in ERP/procurement platforms rather than through separate payment steps. Merchants and platforms integrated with PayNetEasy should anticipate more embedded VCN traffic and may need acceptance/reconciliation flows tuned for virtual-card-specific data (dynamic card numbers, controls tied to specific transactions) rather than static card acceptance.

Merchant Services and Credit Card Processing, Explained for Buyers

Payneteasy — Fri, 24 Jul 2026 13:01:11 +0000

What merchant services and credit card processing involve, how the money moves, what the fees pay for, and how to pick a provider.

You sell something. A customer taps their card. Where does that money actually go?

Merchant services and credit card processing are the accounts, software, and bank relationships that let a business accept cards and have the funds land in its bank account. Three parts work together: a way to capture the card at checkout, a card network that routes the authorization request to the customer's issuing bank, and an account that receives the funds. When those three are in place, a sale goes from "approved" to money in your account without you thinking about the plumbing.

This guide is written for the merchant buying services, not for someone starting a payments company. If you take cards or plan to, here is what it really involves — and how to pick a provider you will not have to replace next year.

What is merchant services credit card processing?

"Merchant services" is the umbrella term for everything a business uses to accept electronic payments. Credit card processing is the specific job inside it: moving a card transaction from your checkout, through the card networks, to the customer's bank, and back with an approve or decline.

A few terms you will keep meeting:

Merchant account **— the account that holds card funds before they settle to your business bank account. - Payment gateway** — the software that captures the card at checkout and passes it securely into the processing system. This is the part your customer touches. -** Acquirer (acquiring bank) — the financial institution that enables card acceptance for the merchant and receives settlement through the card network. - Processor, or PSP (payment service provider)** — the company that connects the gateway, the acquirer, and the card networks so the transaction completes.

You don't always buy these separately. Many providers bundle gateway, merchant account, acquiring and processing, which is why labels blur. What matters is that all four roles are covered.

How does a card payment actually move?

The flow is faster to read than it is to run. A single payment passes through roughly five steps.

Capture. The customer enters their card on your checkout. The gateway encrypts and forwards the details.
Authorisation. The processor asks the card network, which asks the customer's issuing bank: is this card valid, and is the money there? The bank answers approve or decline, usually in under a couple of seconds.
Hold. On approval, the amount is held against the customer's balance. No money has moved yet.
Settlement capture. At the end of the day, or when you ship, the held amount is captured and the card networks move the funds.
Settlement to you. The acquirer deposits the funds, minus fees, into your account — typically on a delay of a day or several.

Two practical takeaways. First, "approved" is not "paid." Settlement happens later, which is why refunds and chargebacks (a card payment the customer's bank reverses after the sale) can land after the fact. Second, every one of those steps is a place a payment can fail. That is why processing reliability matters more than the headline rate.

What do the fees actually pay for?

On a statement, card processing fees look like one number. In reality, they consist of three layers.

Only the third layer is negotiable. Only the third layer is where providers truly differ.

A few practical points:

Be wary of a single low "flat rate" without a breakdown. Flat rates can be cheaper for small tickets and more expensive for larger ones, or vice versa.
Ask for the effective rate on your numbers: total fees divided by total processed, using your actual average ticket size and volume. That tells you more than a headline percentage.
Interchange and scheme fees vary by region, card type and merchant category, and card networks publish them. It's worth confirming current rates for your mix rather than relying on one quoted average.

Common pricing models you'll see:

Flat-rate. One blended percentage for all transactions. Simple to understand, variable in true cost.
Interchange-plus. Interchange and scheme fees plus a fixed markup. Transparent, often better at scale.
Tiered. Transactions grouped into "qualified," "mid-qualified," "non-qualified" buckets with different rates. Harder to analyse.

Gateway, full merchant services, or orchestration — which do you need?

Most merchants are really choosing between three setups. The right one depends on volume, where you sell, and how much you want to manage yourself.

A payment gateway only gives you checkout and secure card capture. It fits if you already have a merchant account and an acquirer, and you just need the front door. You assemble the rest.

**Full merchant services **bundle the gateway, a merchant account, and acquiring into one package. This suits a single business in a single market that wants it simple. The trade-off: you are tied to one provider's rails.

A payment orchestration platform is a layer that connects multiple gateways, acquirers, and methods. Orchestration means routing each payment by rules — and it can retry a failed payment on a second provider. It fits merchants who take many methods, sell across markets, or want to avoid single-provider lock-in. You can add methods without re-integrating each one. There is more capability here, and more to configure up front.

Compared with a simple gateway, orchestration:

reduces re-integration work when adding new banks or methods,
lets you shift traffic between acquirers without rewiring your checkout,
and gives finance one normalised view across all routes.

If you sell in one market with familiar cards, a bundled merchant-services package is the simplest start. If you sell across markets, take many payment methods, or want a failed transaction on one acquirer to retry on another, an orchestration platform is built for exactly that.

How do you choose a credit card processing provider?

Six questions help separate a provider you keep from one you replace.

Where does a platform like Payneteasy fit?

Payneteasy is a payment orchestration and gateway platform — payment technology, not an acquirer or PayFac.

That means:

It does not approve, provide or guarantee merchant accounts.
It does not hold your settlement funds or take on settlement risk.
Your acquiring relationships and bank contracts remain yours.

Instead, Payneteasy sits between your checkout and multiple acquirers and payment methods:

You can route transactions by rules — card type, country, amount, merchant segment.
You can cascade failed payments from one acquirer to another automatically, where appropriate.
You can add new methods and banks through configuration rather than new, separate integrations.

This suits merchants who have outgrown a single bundled account — for example:

selling across several markets,
mixing cards with local methods,
wanting to avoid a single point of failure in acquiring.

The platform supports a broad range of card types and alternative payment methods, including major card networks and many local options. For an exact list of supported acquirers, methods and regions, confirm current coverage directly with the Payneteasy team rather than assuming a fixed catalogue.

If you are still at "one market, one provider," you may not need orchestration yet — and an honest provider will tell you that. The point of a layer like Payneteasy is to remove the ceiling: the setup that works at your current volume still works when you add a bank, a method or a region, without you having to tear out and replace your processing stack.