.Klappay

2026-09-08

Non-Custodial Crypto Payments API: What It Means and How to Evaluate One

A non-custodial crypto payments API should not turn a blockchain payment into another processor-held balance. Your customer sends USDC from their wallet, the transaction settles on-chain, and your business receives the funds at an address it controls. The API's job is to create the payment intent, identify the transfer, verify its finality, and report status to your application. It should not become the owner of the money in between.

That distinction changes more than a security diagram. It determines who can move funds, where settlement risk sits, how quickly revenue becomes usable, and whether your payment stack remains composable when the product changes. For teams building custom checkout, marketplaces, SaaS billing, or creator products, custody is not an implementation detail. It is the architecture of the financial relationship.

What a non-custodial crypto payments API actually does

At the application layer, crypto payments look familiar: create a charge, show a payment request, wait for a confirmed result, then fulfill the order. The difference is that the payment rail is an on-chain transfer rather than a card authorization and processor ledger entry.

A capable API creates a charge with the required asset, network, amount, expiration rules, a correlation id for your own records, and recipient configuration. It then produces a deterministic payment address that your checkout can render however you choose. Your customer pays from a compatible wallet. The API monitors the relevant network and emits payment events after it observes and validates the transfer.

The critical boundary is simple: the merchant-controlled recipient address is part of the charge from the start. The infrastructure provider detects the transfer and reports what happened, but never receives the customer's funds into its own wallet before passing them along.

That is different from a custodial crypto processor, even if both products use the phrase "crypto checkout." A custodial processor commonly accepts funds to an address it controls, credits an internal balance, applies its own settlement rules, and later pays out to the merchant. That model can be convenient for a provider. It also inserts a counterparty directly into your revenue flow.

Direct settlement is a product decision, not a slogan

Direct on-chain settlement gives engineering and finance teams a clearer source of truth. The payment transaction, destination address, asset, and block confirmation are independently inspectable. There is no processor balance that must be reconciled before you can establish whether a payment arrived.

It also removes a familiar failure mode: a customer has paid, but the merchant cannot access funds because a provider's account review, payout batch, reserve policy, or withdrawal flow is in the way. If your product depends on fast access to working capital or immediate distribution to participants, that delay is not theoretical.

Self-custody does introduce responsibility. The business must secure its wallet infrastructure, control key access, and define its own treasury operations. A non-custodial API does not eliminate those obligations, nor should it pretend to. It makes the boundary explicit: infrastructure handles payment detection and orchestration; the merchant owns the assets and the operational decisions around them.

For many software businesses, that is the correct trade. They already operate cloud credentials, signing systems, databases, and production access controls. Adding a well-defined wallet policy is preferable to accepting opaque control over incoming revenue.

The integration should fit your checkout, not replace it

Hosted checkout pages are often presented as the fast path. They can be useful for a basic payment link, but they are a poor default for teams that care about conversion, embedded workflows, or product-specific logic. A marketplace may need seller context in the order view. A SaaS product may need to activate an account the moment payment finalizes. A gaming app may need the wallet request inside a custom interface.

An API-first payment system gives you control of that surface. Your frontend can display the amount, network, asset, address, QR code, and payment state in the same language as the rest of the product. Your backend can create charges from its own order record and attach an externalRef that makes reconciliation practical.

The basic lifecycle should be small enough to reason about. Here is what it looks like with Klappay:

const charge = await klap.charges.create({
  amount: 49.00,
  acceptedPayments: [{ token: 'USDC', network: 'base' }],
  expiresIn: 3600,
  externalRef: `order_4821`,
})


await charge.waitForConfirmation()
// on-chain, confirmed. settlement to your wallet follows as its own step.

The contract is straightforward: create a charge server-side, present payment instructions client-side, and treat verified status events as the trigger for fulfillment. Do not infer success from a wallet connection, a submitted transaction screen, or a client-side callback that your server cannot verify.

Events are where payment infrastructure proves itself

Polling a block explorer or running a custom indexer for every order is not a payment integration. It is operational debt disguised as control. The API should give your application reliable, real-time ways to consume charge state.

Server-sent events work well when a checkout needs to update while the customer is waiting — but the stream itself requires your secret API key, so it's your backend that holds it open, not the customer's browser. Your backend relays progress to the page over its own channel as the charge moves from pending to confirmed to settled (or to expired or underpaid). Webhooks are the right mechanism for durable backend actions such as provisioning a subscription, releasing a digital good, or recording an invoice payment. SDK methods remain useful when an operator dashboard or background job needs the current charge state on demand.

Use all three according to their role. SSE improves the customer experience. Webhooks drive server-side business logic. Status reads support reconciliation and recovery.

A webhook handler still needs production discipline. Verify the event signature, make processing idempotent, persist the provider event ID and charge ID, and tolerate retries:

app.post(
  '/webhooks/klappay',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    let event
    try {
      event = klap.webhooks.constructEvent(
        req.body,
        req.headers['x-klappay-signature'],
        process.env.KLAP_WEBHOOK_SECRET,
      )
    } catch {
      return res.sendStatus(400)
    }


    const already = await db.processedEvents.findUnique({ where: { id: event.id } })
    if (already) return res.sendStatus(200)


    await db.processedEvents.create({ data: { id: event.id } })


    if (event.event === 'charge.confirmed') {
      await fulfillOrder(event.data.externalRef)
    }


    res.sendStatus(200)
  },
)

If an event is delivered twice, a customer should not receive two account upgrades or two shipments. If your endpoint is temporarily unavailable, the provider should retry rather than silently dropping the settlement signal.

Confirmation depth itself isn't something your team tunes per order — Klappay fixes a minimum per network based on that chain's own reorg risk, and a charge only reaches confirmed once a transfer clears it. What is your call is what you do at confirmed versus settled: a low-value digital item can fulfill the moment the payment is confirmed on-chain, while a high-value physical order might reasonably wait for charge.settled — the payout actually reaching your wallet, a separate and slightly later step.

Payment addresses and recipient splits need deterministic rules

A shared receiving address makes reconciliation unnecessarily ambiguous. If ten customers pay the same amount to one wallet, identifying which transfer belongs to which order becomes fragile fast. Deterministic addresses or unique charge-level payment instructions give every payment an identity before the customer sends anything.

That design is especially useful for marketplaces and multi-party products. A charge can define native recipient splits at creation time — one portion to the seller, one to the platform, and perhaps another to a collaborator or affiliate. The funds route according to the payment configuration rather than landing in a platform-controlled pool that must later be redistributed.

With Klappay, that looks like this:

const merchant = await klap.recipients.create({
  address: merchantWallet,
  label: 'merchant',
})


const platform = await klap.recipients.create({
  address: platformWallet,
  label: 'platform',
})


const charge = await klap.charges.create({
  amount: 100.00,
  acceptedPayments: [{ token: 'USDC', network: 'base' }],
  expiresIn: 3600,
  splitRecipients: [
    { recipientId: merchant.id, percent: 90, label: 'merchant' },
    { recipientId: platform.id, percent: 10, label: 'platform' },
  ],
})

This is not merely a convenience feature. Holding seller funds centrally can create accounting, liability, and operational complexity. Native distribution keeps the flow legible on-chain and reduces the number of internal balances your product has to maintain.

Splits should be explicit about rounding, fees, failed-recipient behavior, and the network and asset each recipient supports. A good API exposes those rules in typed request and response schemas rather than leaving developers to discover them through failed transactions.

How to evaluate a non-custodial crypto payments API

Start with fund flow, not feature count. Ask where the customer's transaction lands first and whether the provider can freeze, redirect, pool, or delay those funds. If the answer is a provider-controlled address, the system is custodial regardless of its marketing language.

Then inspect the developer contract. Can you create charges from your backend without sending users to a hosted page? Can you control payment presentation? Are addresses deterministic? Are webhook payloads documented and typed? Can you simulate charge events in a sandbox without spending testnet tokens or waiting on a real chain?

Pricing should be equally legible. A transaction fee is easy to model. Monthly platform charges, setup fees, withdrawal fees, custody fees, conversion spreads, and conditional payout fees are not. Transparent infrastructure should let your team calculate payment cost from a single transaction without reading a policy document like a legal puzzle.

Klappay takes the direct-settlement position seriously: it creates and monitors payment flows while never touching the funds. Charge creation, deterministic addresses, real-time events, TypeScript SDK, sandbox testing, and native splits all matter as much as the custody claim itself — because a custody model that is impractical to integrate is not actually useful.

The right starting point is a narrow production path: accept one stablecoin on one network, create charges from your existing order service, and wire a verified webhook into one fulfillment action. Once that path is observable and dependable, add payment links, subscriptions, donations, or marketplace splits without giving up control of the money your product earns.

Start integrating with Klappay →

.Klappay