MMashDiv

Payment Gateway

The merchant payment gateway addon — let sellers on your platform accept crypto and fiat wallet payments through a hosted checkout and a REST API, with fees, payouts and refunds handled for you.

4 min readUpdated 3 August 2026gateway, merchants, api, webhooks

Payment Gateway turns your Bicrypto install into a payment processor. A user registers a merchant account, gets a pair of API keys, and can then create payment sessions from their own website. Their customers land on a checkout page hosted by you, pay out of their platform wallet, and the merchant's balance goes up minus your fee.

This is the merchant-facing gateway. It is not the 16 fiat deposit providers (Stripe, PayPal, Adyen and the rest) that let your users top up their own wallets — those are core, and documented under Bicrypto. The two share the word "gateway" and nothing else.

What it requires

The checkout confirms a payment by debiting a wallet that belongs to a logged-in user of your platform. The buyer must already have an account here and a funded FIAT, SPOT or ECO wallet. There is no card form, no external bank rail and no way for an anonymous visitor to pay. A merchant who plugs this into a public shop will find that only your existing users can check out.

  • Bicrypto core. The addon is a licensed extension of the platform. It uses core wallets, the wallet ledger service, users, roles, settings and the cron worker. It cannot run standalone.
  • The cron process. Three scheduled jobs create payouts, retry failed webhooks and expire abandoned sessions. Without a running cron worker, merchants accrue an unpayable balance and every failed webhook is lost.
  • Redis, because core requires it.
  • The Ecosystem addon — only for ECO payments. Pricing an ECO currency goes through the ecosystem matching engine. Without Ecosystem installed the price resolves to zero and the checkout rejects the payment with "Could not determine price". FIAT and SPOT need nothing extra.

How the money moves

Five hops, and the merchant is not paid at any of the first four.

  1. The merchant creates a session. POST /api/gateway/v1/payment/create with an amount, a currency and a return URL. The response carries a checkoutUrl; the merchant redirects the buyer to it.
  2. The buyer pays on your checkout page. They pick one or more of their own wallets. Each wallet is debited through the platform's wallet service, at a rate the server recomputes — the buyer's quote is only checked for staleness, never trusted as the settlement figure.
  3. Your fee is taken immediately. The percentage-plus-fixed fee is credited to the first Super Admin's wallet in the same currency the buyer paid in, and recorded in adminProfit under type GATEWAY_PAYMENT.
  4. The net lands in the merchant's gateway balance as pending. This is a ledger row in gateway_merchant_balance, not the merchant's spendable wallet. They can see it; they cannot use it.
  5. A payout releases it. The hourly payout job creates a PENDING payout for the unclaimed portion of pending. An admin approves it, and only then is the merchant's real wallet credited.

There is no auto-approval anywhere in the payout path. Even a merchant on the INSTANT schedule gets a payout record within the hour and then waits for an admin to press Approve. If nobody works that queue, no merchant is ever paid.

Refunds run the same path backwards: the merchant's pending balance is debited, the buyer's original wallets are credited in their original currencies, and the proportional share of your fee is returned from the admin wallet.

What a merchant gets

  • A dashboard at /gateway/dashboard with 30-day volume, fees, refunds and recent payments, switchable between live and test data.
  • Up to ten API keys, issued in public/secret pairs, per-key permissions, an optional IP allowlist on secret keys, and one-click rotation.
  • A payment list, a payout list and a balance view broken down by currency and wallet type.
  • A downloadable WooCommerce plugin, and an in-app API reference at /gateway/docs.
  • Test mode: sk_test_ keys create payments that move no money at all but walk the full checkout.

What you get as the operator

Admin screens live under Extensions → Payment Gateway (/admin/gateway): a dashboard with volume by currency and an aged payout queue, the merchant approval queue, every payment with an admin refund button, the payout approval queue, and the settings page that sets platform-wide fees, limits and which wallet types may be used at all.

Where to start

Install

Licence the extension, enable it, configure the one setting that blocks everything else, and confirm the three cron jobs are running.

Merchant onboarding

Registration, the two independent status fields, the KYC gate, and why a brand new merchant's keys do not work yet.

API integration

Authentication, creating a session, the redirect, polling status, cancelling and refunding — with the exact paths.

Webhooks

The six events that actually fire, the signature scheme, and the retry ladder.

WooCommerce

The bundled plugin, its settings, and the two places its webhook handler disagrees with what the platform sends.

Admin

Approving merchants, working the payout queue, issuing refunds on a merchant's behalf, and every gateway setting.

Two reference pages sit behind these: API and data model lists every endpoint, status, table and permission key, and Troubleshooting covers the failures that look like something else.