Crypto Settlement for Developers: How Gateways Pay You, and What to Check in the API

Crypto settlement is how money gets from a gateway to your own wallet after a customer pays. There are three common models: the payment goes straight to your wallet, the gateway holds a balance and pays you out, or the gateway converts the payment into one coin first. For a developer, the deciding questions are who holds the coins in between, what triggers a payout, what each payout costs, and whether your code can see and control it. Crypto Merchant uses the second model: it holds the keys, you choose manual, threshold or scheduled payouts in the portal, and signed webhooks report each one.

Last checked: 7 November 2026.

What are the settlement models?

The models can combine. A custodial gateway can also convert, and some gateways offer both a direct and a custodial route. If custody is the deciding question for you, read custodial vs non-custodial crypto payments first.

How do gateways compare on crypto settlement?

These are published facts, checked on 29 October 2026 unless stated. Rates and terms change, so confirm them with each provider. Crypto Merchant wrote this comparison.

Where Crypto Merchant isn't the right fit:

• You want to start payouts from your own code. Our API has no payout route: you set the rules in the portal.
• You need mass payouts to many recipients.
• You need money in a bank account. We pay out in crypto only.
• You won't let a third party hold your coins, even briefly. A non-custodial tool such as BTCPay Server fits that better.

What triggers a payout at Crypto Merchant?

You choose one of three rules in the portal:

Automatic payouts need a saved payout address for each coin, and only Admins can add or change those addresses. Check them with care: crypto transfers can't be reversed. An automatic rule pays out a coin's whole balance, and skips any coin worth less than $5 until it reaches that, so small amounts don't go on gas fees.

Can I settle everything in one coin?

Crypto Merchant's two payout styles are per coin, where each coin goes to its own wallet with no swap, and one holding coin, where balances are swapped into a coin you choose. Swap rates use live market prices and include a 1% service margin, plus a gas fee. You get the rate when the swap runs, not the rate when the payment arrived, and a balance worth less than $12 isn't swapped. Before you design around a holding coin, open Payouts in the portal: if it says swaps aren't available yet, plan for per-coin payouts.

What will a payout actually cost?

Work it through for one invoice. At a 1% fee, a $100 invoice paid in USDT costs 1 USDT, and 99 USDT is credited to your balance. A payout can then carry a gas fee. For a token such as USDT, it comes from your gas balance if that covers it, and otherwise out of the amount sent. For a network's own coin, such as ETH or TRX, it always comes out of the amount sent.

So record both fields on each payout. amount is what left your balance, and network_fee is the part taken out of it for gas, so your wallet receives amount minus network_fee. When the gas balance pays, network_fee can be 0 and your gas balance falls instead. Compare the result with the transaction on the blockchain.

Fewer payouts mean fewer gas fees, and the cost differs a lot by network. This is what each blockchain itself charged for one USDT transfer, in the snapshot of 05:38 UTC on 7 November 2026 from our network fees page. It isn't a price list for our gas fee.

How does my code know a payout happened?

Through webhooks. payout.sent means the coins were sent. payout.failed means they couldn't be, after a few tries, and the amount has returned to your balance. Your code should do four things:

1. 1Verify the CM-Signature header against the raw body.
2. 2Save the event ID first, so a retried delivery does nothing. Failed deliveries are retried up to eight times over about two days.
3. 3Skip events where partner_share is true. Those are revenue split payments to a partner's wallet, not money reaching you.
4. 4Reply with a 2xx status within 10 seconds, and do slow work afterwards.

import crypto from "node:crypto";

function verifySignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

async function handleEvent(event, db) {
  const firstTime = await db.saveEventOnce(event.id);
  if (!firstTime) return;

  if (event.type !== "payout.sent" && event.type !== "payout.failed") return;
  const p = event.data;
  if (p.partner_share) return; // a partner's money, not yours

  if (event.type === "payout.sent") {
    await db.recordSettlement({
      payoutId: p.id, coin: p.coin, amount: p.amount, takenForGas: p.network_fee,
      toAddress: p.to_address, txHash: p.tx_hash, automatic: p.auto,
    });
  } else {
    await db.alertTreasury(`Payout ${p.id} failed: ${p.amount} ${p.coin} is back in your balance`);
  }
}

This code was run under Node.js against stubs, with valid, altered and expired signatures, a repeated event, a partner share and a failure. It hasn't been run against the live API or a real database. db stands for your own storage.

One case has no event at the time. If a transfer fails after it was already broadcast, it isn't re-sent automatically and gets a manual check, so neither webhook fires then. If a payout you started never reports back, look at it under Payouts in the portal.

How do I reconcile settlement?

Call GET /balances on a schedule, and compare it with your own ledger. It returns what your business holds in each coin, the total in US dollars and your gas balance. For each coin, your ledger should show credited payments, minus refunds, swaps, partner shares and payouts.

Don't expect an exact match. Gas fees taken from your coins lower the balance too, and not every one has its own webhook event. Allow a small tolerance, and look into a gap that keeps growing: it usually means a missed event or a move made in the portal. The webhook retries and reconciliation guide covers the catch-up job, and the Tax CSV under Reports lists every payment, payout, refund, partner share and swap for a period.

What should I test before going live?

Our production site runs on real networks, so test with a real invoice on a low-fee network. The minimum is $0.50.

• A small invoice is paid, and invoice.paid arrives.
• GET /balances shows the amount after the fee.
• One small manual payout reaches your wallet, and payout.sent carries the transaction ID.
• A repeated webhook changes nothing in your ledger.
• Your alert fires on payout.failed, at least with a hand-made signed event.

Next, see the API reference, webhooks, payouts and swaps and pricing, or read the crypto payment API guide and accepting USDT TRC-20 through the REST API. Payment confirmation times are on the network status page, and proof of reserves lists the addresses that hold coins. Competitor facts come from each vendor page linked in the table; BitPay's fee comes from a search snippet of its support page, which we could not open.