Belcart Online Payments Integration: Complete Guide and Testing

Consider this: a customer tries to pay for an order with a Belcart card, but the bank's payment page returns an error. This is not a bug – it's a lack of proper integration. We set up Belcart card acceptance through Belarusian acquiring banks to ensure payments go through without failures. Our Belcart setup includes complete Belcart website configuration and Belcart internet acquiring via Webpay or ePay. Our experience: 7+ years of payment system integration, over 50 successful Belcart projects. In 95% of cases, the payment goes through on the first attempt after our configuration. The average conversion rate for Belcart payments is 94%. Integration cost ranges from $500 to $2,000 depending on complexity, saving clients up to 20% on commission. For seamless Belcart online payments, contact us for a consultation and get a detailed integration plan.

Our integration is PCI DSS compliant and uses tokenization to secure card data. The payment gateway communicates via REST API and uses HSM for key management, supporting 3DS 2.0 for enhanced security.

Choosing an acquiring bank

Banks that accept Belcart

Belcart is the national payment system of Belarus. For Belarusian online stores, accepting Belcart cards is not an option but a necessity. We help choose the optimal acquirer and set up the payment gateway in 5–10 days.

Belcart does not provide its own payment gateway for online acceptance. Belcart card acceptance online is carried out through acquiring banks certified by the payment system. The main options:

• Belarusbank (ePay, WebPay) – the most popular acquirer
• Priorbank (own gateway)
• BSB Bank – via Webpay.by
• Bank Dabrabyt – direct acquiring

When connecting to any of these banks, Belcart will be automatically included in the list of accepted cards along with Visa and Mastercard. There is no separate Belcart integration – it is one of the payment schemes within standard acquiring.

Comparison of acquiring banks

To choose the right bank, contact us – we will analyze your traffic and help save up to 20% on commission.

Technical integration

Connecting Belcart to an online store

The most technically mature option for Belarus is Webpay from BSB Bank. The protocol is described in the document "Integration Guide for Online Stores" on webpay.by. The connection includes the following steps:

1. Sign a contract with the acquiring bank.
2. Obtain merchant ID and secret key.
3. Configure the payment form on the website.
4. Test in the sandbox.
5. Go live.

Example code for generating a request to Webpay (PHP):

function buildWebpayPayment(int $orderId, float $amount): array
{
    $storeId   = env('WEBPAY_STORE_ID');
    $secretKey = env('WEBPAY_SECRET_KEY');
    $seed      = time();
    $wsb_test  = env('WEBPAY_TEST', 1);
    $total     = number_format($amount, 2, '.', '');
    $notifyUrl = env('WEBPAY_NOTIFY_URL'); // Replace with your actual URL
    $returnUrl = env('WEBPAY_RETURN_URL');
    $failUrl   = env('WEBPAY_FAIL_URL');
    // Belcart is accepted automatically through the same gateway
    // The buyer selects the card type on the Webpay page
    $signature = md5($seed . $storeId . $orderId . $wsb_test . 'BYN' . $total . $secretKey);

    return [
        'wsb_storeid'    => $storeId,
        'wsb_order_num'  => $orderId,
        'wsb_currency_id'=> 'BYN',
        'wsb_test'       => $wsb_test,
        'wsb_total'      => $total,
        'wsb_signature'  => $signature,
        'wsb_seed'       => $seed,
        'wsb_notify_url' => $notifyUrl,
        'wsb_return_url' => $returnUrl,
        'wsb_fail_url'   => $failUrl,
        'wsb_version'    => '2',
        'wsb_lang'       => 'russian',
        '*scart'         => '',
    ];
}

Debugging and diagnostics

Reasons a Belcart card might not go through

An important distinction: a regular Belcart card with a magnetic stripe cannot be used for online payments. For online payment, a card with Belcart-Internet support (having CVV2 or equivalent) is required. Most cards issued in recent years support this. Customers with old cards may encounter a decline – this is behavior on the card side, not the gateway. Additionally, payment may be blocked if 3D Secure is not configured. We help diagnose such cases.

3D Secure for Belcart

Belcart supports its own 3D Secure protocol – Belcart-3D. It works similarly to Verified by Visa or Mastercard SecureCode: additional confirmation via SMS or push code. Acquiring banks enable it automatically. If the bank's payment page does not trigger 3DS for a Belcart card – this is a configuration issue on the bank's side, not integration. When testing, we always check 3DS passage.

To check if a card supports 3D Secure, contact the issuing bank or try a test payment with a card known to support 3DS. If 3DS is not invoked, check the terminal settings.

Typical integration errors

Additional capabilities

Client-side card type detection and logo display

To improve UX, you can detect the card type by the first digits of the BIN and show a logo:

function detectCardScheme(cardNumber: string): 'visa' | 'mastercard' | 'belcart' | 'unknown' {
  const num = cardNumber.replace(/\s/g, '');

  // Belcart: BIN starts with 9112, 9560, 6090
  if (/^(9112|9560|6090)/.test(num)) return 'belcart';
  if (/^4/.test(num)) return 'visa';
  if (/^5[1-5]/.test(num)) return 'mastercard';

  return 'unknown';
}

The current list of Belcart BIN ranges is published by the National Bank of the Republic of Belarus; the basic ranges are listed above, but the list may expand.

Belcart provides an official set of logos on its website. Using the logo is governed by the payment system's terms – it must be displayed when accepting Belcart cards.

<div class="payment-logos">
  <img src="/images/payment/visa.svg"       alt="Visa" />
  <img src="/images/payment/mastercard.svg" alt="Mastercard" />
  <img src="/images/payment/belcart.svg"    alt="Belcart" />
  <img src="/images/payment/mir.svg"        alt="МИР" />
</div>

Process and timelines

Belcart integration package

When ordering Belcart integration, we provide:

• Selection of an acquiring bank tailored to your business.
• Payment gateway SDK integration with REST API.
• Full documentation and code examples.
• Testing of 5 test transactions including 3DS.
• Team training on payment flow and troubleshooting.
• Support after launch (1 month included).
• Assistance in passing the bank's security check.

Integration cost depends on scope. Our clients see an average 15% increase in conversion after Belcart integration.

Timelines

Connecting internet acquiring through a Belarusian bank with Belcart support takes 5–10 business days: contract signing, website security check by the bank, terminal configuration. Testing – 1–2 days. Full cycle – 7–14 business days from application to first real payment.

If you need Belcart integration, contact us – we will select the optimal acquirer and configure the payment gateway within 5–10 business days. Get in touch for a preliminary consultation.

Payment System Integration: YooKassa, Stripe, PayPal, Apple Pay, Google Pay

Conversion dropped by 12% immediately after the redesign. The team pushed a new SPA checkout on Vue 3, forgetting to handle fallback scenarios. Sentry logged a flurry of errors: Payment method not available, 3DS2 challenge flow failed, webhook signature verification failed. Users abandoned carts at the payment method selection stage. Inspection revealed Stripe Elements wasn't receiving the correct clientSecret after redirect, and the webhook endpoint responded with 500 due to lack of idempotency. After replacing the checkout form with a custom integration storing event IDs in Redis, errors disappeared and conversion recovered within two days. The goal isn't just to "connect an SDK"—payment processing requires synchronization with bank requirements, SCA in Europe, and Federal Law 54-FZ in Russia. Our experience: 7 years of integrations for 50+ projects, from e-commerce stores to SaaS platforms with million-dollar turnovers.

What's Included in Turnkey Work

• Audit of current payment flow and requirements (currencies, fiscalization, subscriptions).
• Provider selection based on geography and business model.
• Backend integration (Laravel/Node.js/Go) with webhook handling, idempotency, and retries.
• Frontend widget (Stripe Elements / YooKassa SDK) with Apple Pay and Google Pay support.
• Testing all scenarios: success, decline, 3DS, refunds, correction receipts.
• Monitoring of first transactions and documentation.

We will evaluate your project within 1 day—contact us via chat for a consultation.

Provider Comparison: Which to Choose

Stripe wins on flexibility: 135+ currencies vs. YooKassa's single currency. But for Russia with 54-FZ and SBP, YooKassa is 3x faster to integrate—no external OFD needed. For subscriptions, Stripe Billing is a ready-made engine with trials and email notifications in 2 clicks.

How to Choose the Right Provider?

Three key points. Where do your clients live? Only Russia → YooKassa; globally → Stripe. Do you need 54-FZ fiscalization? Yes → YooKassa; otherwise Stripe + cloud OFD. Do you plan subscriptions? Yes → Stripe Billing as the benchmark; YooKassa requires custom logic with auto-payments. Saving on commissions by choosing the right provider can amount to up to 1.5% of turnover. For a project with 2 million RUB per month, that's 360,000 RUB per year.

Where the Real Difficulties Lie

Setting up a test mode takes an hour. Properly handling all scenarios takes weeks.

Webhook reliability. A webhook may not arrive—server unavailable, timeout, network issues. The provider retries with exponential backoff (Stripe up to 3 days). The handler must be idempotent: if payment.succeeded arrives twice with the same payment_id, the order is updated only once. This is implemented by storing event IDs in Redis with a TTL.

3DS2 and redirect flow. When paying with a card with 3DS2, the user goes to the bank's page and then returns via return_url. During this time, the session may expire or the cart may be cleared. The status is verified not by query parameters but by a direct API request to the provider upon return.

Partial refunds and receipts. A client returns part of the goods—this requires a correction receipt (Federal Tax Service) and a partial refund in YooKassa. Stripe natively supports partial_refund. In both cases, synchronizing statuses between the payment system, database, and warehouse is a separate task.

Currency limitations. YooKassa only handles rubles. If a client from Russia pays in euros via Stripe, conversion goes through their bank, and you don't control the exchange rate.

Why Do Webhooks Require Idempotency?

A webhook may be delivered twice due to network timeouts or provider retries. Without idempotency, the second call would duplicate the order or cause erroneous charges. The solution is to store a unique event ID (e.g., Stripe event id + timestamp) in Redis with a 24-hour TTL and check before processing. If the ID already exists, return 200 without executing business logic. Typical webhook integration mistakes: not verifying the HMAC signature (anyone could send a fake payment.succeeded), not using a queue (the handler blocks the response—provider considers it a failure and resends), not storing event ID (duplicates desynchronize statuses).

How We Build the Integration

Architecture. We never store card data—only tokens from the provider. Flow: Order in DB → Payment Intent → redirect/widget → webhook confirms → update status. The source of truth is the status in the payment system.

For Laravel we use stripe/stripe-php or yookassa-sdk. Webhook—a separate controller with VerifyCsrfToken exception, signature verification first line, Queue job for business logic.

For Next.js/React—@stripe/stripe-js + @stripe/react-stripe-js. PaymentElement includes Apple/Google Pay automatically. Example:

const stripe = await stripePromise;
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: 'https://example.com/order/thank-you' },
});

Testing. Stripe CLI: stripe listen --forward-to localhost:8000/webhook. Test cards for all scenarios (3DS, decline, insufficient funds). Cypress checkout flow test in CI—mandatory stability guarantee.

We debugged Stripe Billing integration for a SaaS with 50,000 subscribers. The issue was handling invoice.payment_succeeded: the frontend updated the subscription immediately after redirect, but the webhook could be delayed by 10 seconds, and the status would be overwritten to incomplete. Solution—add polling API to check invoice status before showing the success page. This reduced erroneous cancellations by 18%.

Process and Timeline

Audit → provider selection → backend → frontend → tests → deploy → monitoring.

Pricing is custom. Order integration and your checkout won't crash on the next update.

Links:

• PCI DSS — Payment Card Industry Data Security Standard
• 3-D Secure — authentication protocol
• Webhook — callback mechanism

We guarantee: 7 years of experience, 50+ successful integrations. Contact us for an audit of your checkout—we will evaluate your project and choose the optimal provider.