Belcart Payment System Integration

Belcart Payment System Integration

Belcart is Belarus national payment system. Belcart cards issued by all major Belarusian banks and main payment instrument for significant population share. For Belarusian online stores accepting Belcart cards is not option but necessity.

Connection Features

Belcart doesn't provide own payment gateway for internet acceptance. Internet Belcart card acceptance performed via banks-acquirers with payment system certification. Main options:

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

When connecting to any of these banks Belcart automatically included in accepted cards list along with Visa and Mastercard. Separate "Belcart integration" as such doesn't exist — it's one payment scheme within standard acquiring.

Connection via Webpay (BSB Bank)

Most technically mature variant for Belarus. Protocol described in "Integration Guide for Internet Stores" on webpay.by.

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, '.', '');

    // Belcart accepted automatically via same gateway
    // Customer chooses card type on 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' => 'https://example.com/webhook/webpay',
        'wsb_return_url' => 'https://example.com/payment/success',
        'wsb_fail_url'   => 'https://example.com/payment/fail',
        'wsb_version'    => '2',
        'wsb_lang'       => 'russian',
        '*scart'         => '',
    ];
}

Belcart-Internet vs Belcart Offline

Important difference: regular Belcart card (with magnetic stripe) cannot be used for online payments. For internet payment, card with Belcart-Internet support required (CVV2 presence or equivalent). Most cards issued since 2018 support this. Customers with old cards may face rejection — this card-side behavior, not gateway.

3D Secure for Belcart

Belcart supports own 3D Secure protocol called Belcart-3D. Works like Verified by Visa / Mastercard SecureCode — additional confirmation via SMS code or push. Bank-acquirers include it automatically.

If bank's payment page doesn't initiate 3DS for Belcart card — it's bank configuration problem, not integration.

Card Type Detection on Client

For UX improvement, card type can be determined by first BIN digits and logo shown:

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';
}

Actual Belcart BIN range list published by NBRB; basic ranges listed above, but list may expand.

Logo Display

Belcart provides official logo set on belcart.com. Logo usage regulated by payment system terms — logo placement mandatory 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="MIR" />
</div>

Timeline

Internet-acquiring connection via Belarusian bank supporting Belcart takes 5–10 business days: contract conclusion, site security check by bank, terminal setup. Testing 1–2 days. Total full cycle 7–14 business days from application to first real payment.