DEV Community: Buhgalter

One merchant account, four side projects: how I keep the payment data from turning into a mess

Buhgalter — Thu, 29 Oct 2026 21:04:03 +0000

Most indie developers I know do not run one product. They run a VPN bot, a paid Discord or Telegram community, a small template shop and maybe a script nobody remembers launching. Each of them takes money. Sooner or later someone asks a very boring question: how much did the template shop actually make in September, after refunds?

If all four projects share one payment account and one webhook handler, that question can eat an evening. This post is about structuring things so it takes a minute instead. I will use the Buhgalter payment API as the concrete example, because it has a notion of storefronts built in, but the design ideas apply to most providers.

Storefronts instead of string prefixes

The tempting shortcut is to put the project name into the order reference: vpn-10231, shop-554. It works until someone renames a project, or a junior developer forgets the prefix, or you need to group by project in a report the provider generates for you.

Buhgalter lets one merchant cabinet hold several storefronts, each with its own store_id. Revenue is split by storefront in the reports, so the provider already knows which project a payment belongs to. Your own database should mirror that:

CREATE TABLE storefronts (
  id          TEXT PRIMARY KEY,   -- store_id from the cabinet
  title       TEXT NOT NULL
);

CREATE TABLE payments (
  id            TEXT PRIMARY KEY, -- provider payment id
  store_id      TEXT NOT NULL REFERENCES storefronts(id),
  reference     TEXT NOT NULL,    -- your own order id
  amount_rub    NUMERIC NOT NULL,
  status        TEXT NOT NULL,
  created_at    TIMESTAMPTZ NOT NULL,
  UNIQUE (store_id, reference)
);

The unique constraint on (store_id, reference) matters. Two projects can both have an order number 1001 without colliding, and a retried request inside one project still lands on the same row.

One webhook endpoint or several?

I tried both. A single endpoint that did all the work with a switch on the storefront felt neat for a week, then one project needed a slow side effect (generating a license file) and started delaying confirmations for the others.

What works better for me: the receiving endpoint stays tiny and identical for every project, and each project gets its own worker behind a queue. The receiver does three things.

Checks the X-Buhgalter-Signature header, an HMAC-SHA256 of the body, before parsing anything.
Writes the event to the payments table using the unique key above, so a duplicate delivery becomes a no-op.
Returns 200 fast and drops a job into that project's queue, picked by store_id.

The provider retries failed deliveries up to 8 times over roughly 13 hours and keeps a delivery log you can resend from. That is generous, but it is not a reason to be slow. A receiver that answers in 50 ms never needs the retries in the first place.

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Currency per project, decided once

Payments come in as rubles through SBP, an NSPK QR code or a card number transfer. The balance on the merchant side is kept in USDT by default or in rubles if you switch it, and the rate is locked when the payment is created.

For multi project setups I store the locked rate on every payment row. It sounds redundant until the day you need to explain why the VPN project's September revenue in USDT does not match a naive conversion at the end of month rate. With the rate on each row, the explanation is a SUM.

You can also pull the current USDT/RUB rate with GET /api/fx for dashboards, but never for historical numbers. History lives in your table.

Refunds belong to the same storefront

Refunds can be full or partial and the platform does not charge a fee on them. The mistake I made early on was logging refunds in a separate global table. Then the template shop looked more profitable than it was, because its refunds were counted against nobody in particular.

Put store_id on refunds too, and compute net revenue per storefront:

SELECT p.store_id,
       SUM(p.amount_rub) FILTER (WHERE p.status = 'paid') AS gross,
       COALESCE(SUM(r.amount_rub), 0)                     AS refunded
FROM payments p
LEFT JOIN refunds r ON r.payment_id = p.id
WHERE p.created_at >= date_trunc('month', now() - interval '1 month')
  AND p.created_at <  date_trunc('month', now())
GROUP BY p.store_id;

Month end without the spreadsheet archaeology

The provider side gives you reports with created, paid, conversion, turnover, fee, credited and refunds, with days counted on Moscow time, plus Excel exports and a CSV aimed at 1C accounting software. Watch out for the Moscow day boundary if your server runs in UTC: a payment at 01:30 Moscow time is still "yesterday" in a UTC query. I keep a generated column with the Moscow date so my numbers and the export line up row for row.

Once a month I diff my per storefront totals against the export. When they match, I am done. When they do not, the culprit has always been one of three things: a webhook that never got processed, a refund filed under the wrong project, or the timezone boundary above.

Testing without real money

Every project gets its own test run before going live. Requests with the X-Buhgalter-Test header create test payments, up to 200 a day, which is plenty for a full flow per storefront: create, pay, receive the webhook, refund, check the report line.

What I would tell myself two years ago

Give every project its own storefront from day one, even the tiny ones.
Make the database key (store_id, reference), not just reference.
Verify the signature first, store the event second, do the slow work last.
Save the locked rate on every payment.
Reconcile monthly against the provider export, on Moscow dates.

None of this is clever. It just turns "how much did project X make" into a query instead of a weekend.

If you want to see how storefronts, webhooks and exports look on the provider side, the docs are public at https://buhgalter.app/docs and the service itself is at https://buhgalter.app.

Running a crypto exchange office in Russia: how we automated the ruble-to-USDT first mile

Buhgalter — Thu, 29 Oct 2026 17:57:48 +0000

Most writing about crypto payments is about wallets and chains. Very little is about the boring part that actually eats an exchanger's margin: getting rubles from a customer and turning them into USDT without a human in the loop.

I work at Buhgalter (buhgalter.app), a payment processing service. Our largest group of clients are exchange offices, and here is what we learned from them.

The manual loop

A typical small exchanger used to work like this. The customer sends rubles to a card. An operator checks the bank app, matches the screenshot, recalculates the rate, sends USDT. Every step is a place for errors and disputes, and the rate keeps moving while the operator looks for the transfer.

What the automated version looks like

The exchanger's site creates a payment request through our API the moment the customer clicks. The customer pays via SBP (Russia's instant payment system), a QR code or a card number transfer. The USDT/RUB rate is locked when the payment is created, and the balance is credited in USDT by default. Auto-withdrawal then sends funds to a USDT wallet on TRC-20.

For exchangers that need to know who is paying, there is a payment method with identity confirmation: the payer shows a passport and a selfie with it, a staff member reviews it once per payment. This cuts the number of disputed transfers a lot. And the crypto that comes out is clean.

Money side

We charge only for successful payments. Expired or cancelled requests cost nothing. The bigger the ticket, the lower the rate, and for serious volumes we build individual and VIP terms. Refunds, full or partial, carry no platform fee.

The human side

Every merchant gets a personal manager on Telegram. That sounds like a perk until you run a business where a stuck payment at 2 a.m. means a lost client. We try to meet people halfway, whether they are a large exchanger, a VPN service selling access through a bot, or a creator selling a course.

If you run something similar and want to compare notes, I am happy to talk in the comments.

Alena Kotenkova, Buhgalter team
https://buhgalter.app

Five questions small online businesses ask before switching payment providers, and our straight answers

Buhgalter — Thu, 29 Oct 2026 14:44:32 +0000

I work on Buhgalter (buhgalter.app), a payment service for small online businesses that sell to Russian-speaking customers: exchange offices, VPN services, digital goods shops, Telegram bots, creators with paid channels. Our line is that the service is for everyone, and we mean the people who usually hear no from bigger providers.

Before anyone connects, the same five questions come up. Here they are with plain answers, because the questions say more about this market than any pitch could.

Will my customers be able to pay at all?

They pay through SBP, by scanning a QR NSPK code, or with a card number transfer. These are the methods people already use in their bank apps every day. Nobody on the customer side needs to know anything about crypto.

What happens to the money after that?

It lands on a balance kept in USDT by default, or in rubles if you prefer. The exchange rate is locked when the payment is created, so a price you set in the morning means the same thing in the evening. You can withdraw to a USDT TRC-20 wallet or to a card or account, and auto-withdrawal can do it for you by a rule you set.

Do I need a developer?

Not to start. You can create a payment in the dashboard and send the link. If you do have a developer, there is a payment link, a widget, or a fully custom screen via API, plus signed webhooks, idempotency keys and a test mode with up to 200 test payments a day.

What does it cost?

Commission is charged only on successful payments. Unpaid or expired ones are free. Larger tickets get a lower rate, and bigger projects get individual or VIP terms. We would rather talk it through than force one rate on a VPN with 300 RUB tickets and an exchanger with 300,000 RUB ones.

What if a customer wants their money back?

Full or partial refunds with no platform fee. Disputes come with a receipt and the full payment history.

Behind all five there is usually a sixth question: will a real person answer me, and can the terms bend? For us the answer is yes on both. Every store gets a personal manager after signup, and individual terms are normal practice, not a favour.

If you run a small online service and have a question I did not cover, drop it in the comments. Happy to answer, including the uncomfortable ones.

Buhgalter team, buhgalter.app

Selling digital goods from a Telegram bot: a test-first payment integration

Buhgalter — Thu, 29 Oct 2026 10:21:13 +0000

Most payment tutorials start with the happy path. Create a payment, get paid, ship the product. Then production happens: a webhook arrives twice, the bot restarts mid-delivery, a buyer pays an expired link. This post walks through how I would wire up payments for a bot that sells game keys or in-game currency, starting from tests instead of from the checkout button.

The examples target the Buhgalter payments API. Field names are simplified; check the public docs for exact schemas.

The shape of the flow

The buyer taps Buy in the bot.
The bot calls POST /api/payments with the amount in rubles and its own order id as the reference.
The API returns a payment link or a ready QR (SBP or NSPK QR).
The buyer pays in their banking app.
A signed webhook hits your server, you verify it and deliver the key.

Five steps, and every one of them can fail independently.

Start in test mode

Send the X-Buhgalter-Test header and you get test payments, up to 200 per day. That is enough to run an integration suite on every push. My suite has four cases:

paid once, key delivered once;
webhook delivered twice, key still delivered once;
link expired, nothing delivered, stock released;
refund issued, key marked revoked.

If those four pass, the rest is mostly UI.

Idempotency on the way in

Buyers double tap. Bots retry on timeouts. Use the order id for both the reference and the Idempotency-Key header:

def create_payment(order):
    return session.post(
        f"{BASE}/api/payments",
        json={"amount": order.rub, "reference": order.id},
        headers={"Idempotency-Key": f"order-{order.id}"},
        timeout=65,
    )

The same key returns the same payment, so the buyer never sees two QR codes for one order.

Idempotency on the way out

Webhooks are retried up to 8 times over roughly 13 hours, and you can resend manually from the delivery log in the dashboard. So the handler must be safe to run twice:

def on_paid(event):
    with db.transaction():
        order = db.orders.lock(event["reference"])
        if order.status == "delivered":
            return
        key = db.keys.reserve(order.sku)
        order.mark_delivered(key)
    bot.send(order.chat_id, f"Your key: {key}")

Lock the row, check the status, then deliver. Sending the message after commit means a crash never leaves a delivered key without a record.

Verify the signature on the raw body

Each webhook carries X-Buhgalter-Signature, an HMAC-SHA256 of the body. Compute it over the raw bytes before any JSON parsing, and compare with a constant-time function. Skipping this step lets anyone forge a paid event and drain your key stock.

Expiry and stock

Payment links live 30 minutes by default, configurable from one minute to a day. For limited keys I reserve stock when the payment is created and release it on expiry. A shorter link lifetime keeps popular items from being locked by people who walked away.

Refunds

Refunds can be full or partial and carry no platform fee. In a key shop the rule I use is simple: unactivated key, full refund; activated key, case by case. Whatever you choose, write it in the bot description before the first sale.

Getting paid out

The balance defaults to USDT, with the rate locked when the payment is created, or you can keep it in rubles. Withdrawals go to a bank account, a card, or a USDT TRC-20 wallet. If your supplier sells keys for crypto, auto payout to a wallet removes a manual step from restocking.

Wrap up

Write the four tests first, then build the button. It is a boring order of work and it saves a lot of late night debugging. The docs, with samples in cURL, PHP, Python, Node.js and Java, are at https://buhgalter.app.

Alena Kotenkova, Buhgalter team

Accepting ruble payments in a Telegram bot: webhooks, idempotency and signature checks

Buhgalter — Thu, 29 Oct 2026 08:58:21 +0000

I am on the team at Buhgalter (buhgalter.app), a payment API for Russian instant payments (SBP, QR codes, card transfers) with payouts and USDT settlement. This post is a practical walkthrough for developers who want to wire payments into a bot or a small web app. Most of it applies to any payment API.

Create a payment

One call: POST /api/payments. Amount is in RUB, from 1 to 100,000,000. You pass your own reference (your order id) and optional return URLs.

You choose between sync and async. Sync keeps the connection open until a payment detail or QR is ready, up to 60 seconds. Async returns immediately and delivers the result to your webhook. For a bot, sync is simpler. For anything with a job queue, go async.

Idempotency done right

Send an Idempotency-Key header. A retry with the same key returns the existing payment instead of a new one. We also dedupe on reference.

Derive the key from your order id. If you generate a fresh UUID on every attempt, a timeout plus a retry still produces two invoices.

Verify the webhook

Every webhook carries X-Buhgalter-Signature, an HMAC-SHA256 of the raw body. In Node.js:

const crypto = require("crypto");
function valid(rawBody, header, secret) {
  const sig = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(header));
}

Use the raw bytes. Express with express.json() will hand you a parsed object, and re-serializing it breaks the signature. Use express.raw() on this route.

Expect duplicates and downtime

Delivery is retried up to 8 times over about 13 hours. The dashboard shows a delivery log and lets you resend any event. Your handler must be idempotent: mark the order paid once, return 200 on repeats.

Grant access only on the paid status. Not on creation, not on redirect back from the payment page.

Test mode

Add the X-Buhgalter-Test header to run in sandbox, up to 200 test payments a day. Run success, cancel and expiry. Payment links live 30 minutes by default, configurable from 1 minute to 24 hours.

Payouts and FX

POST /api/payouts sends money to a card, phone or account. GET /api/fx returns the current USDT/RUB rate. The rate for each payment is fixed at creation, and your balance can be held in USDT and auto-withdrawn to a TRC-20 wallet.

Docs with cURL, PHP, Python, Node.js and Java examples: https://buhgalter.app/docs . A first QR takes about ten minutes, the full setup with webhook verification about an hour.

Questions welcome in the comments.

Alena Kotenkova, Buhgalter team