SDKs & Libraries | PHP, Node, Python

Server libraries

Install with your usual package manager. All server SDKs share the same design: idempotency keys added automatically on writes, connection pooling, automatic retry with backoff on 5xx and 429, and typed error classes you can catch by kind.

Language	Package	Minimum version
PHP	`composer require bearmerchant/bearmerchant-php`	PHP 8.1
Node.js	`npm install @bearmerchant/node`	Node 18
Python	`pip install bearmerchant`	Python 3.9
Java	`com.bearmerchant:bearmerchant-java`	Java 11
Ruby	`gem install bearmerchant`	Ruby 3.0
Go	`go get github.com/bearmerchant/bearmerchant-go`	Go 1.21
.NET	`dotnet add package BearMerchant`	.NET 6

Every SDK reads BM_SECRET_KEY from the environment if you construct the client without arguments — the easiest way to keep keys out of source control.

The same call, four ways

The shape is deliberately identical across languages, so a snippet from one translates without surprises.

charge.php php

<?php
use BearMerchant\Client;
use BearMerchant\Exception\CardException;

$bm = new Client();  // reads BM_SECRET_KEY

try {
    $charge = $bm->charges->create([
        'amount'         => 4280,
        'currency'       => 'usd',
        'payment_method' => 'pm_1KdY7x',
        'metadata'       => ['order_id' => '1042'],
    ]);
    fulfil($charge->id);
} catch (CardException $e) {
    // Declined — $e->declineCode says whether a retry is worth it
    showDecline($e->getMessage());
}

charge.js javascript

import BearMerchant from '@bearmerchant/node';

const bm = new BearMerchant();

try {
  const charge = await bm.charges.create({
    amount: 4280,
    currency: 'usd',
    payment_method: 'pm_1KdY7x',
    metadata: { order_id: '1042' },
  });
  await fulfil(charge.id);
} catch (err) {
  if (err.type === 'card_error') showDecline(err.message);
  else throw err;
}

charge.py python

import bearmerchant
from bearmerchant.error import CardError

bm = bearmerchant.Client()

try:
    charge = bm.charges.create(
        amount=4280,
        currency="usd",
        payment_method="pm_1KdY7x",
        metadata={"order_id": "1042"},
    )
    fulfil(charge.id)
except CardError as e:
    show_decline(e.message)

charge.go go

package main

import bm "github.com/bearmerchant/bearmerchant-go"

func charge() {
    client := bm.New()

    ch, err := client.Charges.Create(&bm.ChargeParams{
        Amount:        bm.Int64(4280),
        Currency:      bm.String("usd"),
        PaymentMethod: bm.String("pm_1KdY7x"),
    })
    if err != nil {
        if ce, ok := err.(*bm.CardError); ok {
            showDecline(ce.Message)
            return
        }
        panic(err)
    }
    fulfil(ch.ID)
}

Client-side SDKs

Card details are collected by our hosted fields and exchanged for a token in the browser. Raw card numbers never reach your servers, which keeps you in the lightest PCI scope available.

Platform	How to load
Web	`<script src="https://js.bearmerchant.com/v1/"></script>`
iOS	`pod 'BearMerchant'` or Swift Package Manager
Android	`implementation 'com.bearmerchant:bearmerchant-android'`
React Native	`npm install @bearmerchant/react-native`

checkout.js javascript

const bm = BearMerchant('pk_live_51H8xQ2p');   // publishable key
const fields = bm.fields();

fields.create('card').mount('#card-element');

form.addEventListener('submit', async (e) => {
  e.preventDefault();

  const { token, error } = await bm.createToken(fields);
  if (error) return showError(error.message);

  // Send only the token to your server; the card never touches it
  await fetch('/api/pay', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: token.id }),
  });
});

Only ever use a publishable key (pk_) in client code. A secret key shipped to a browser or compiled into a mobile app is a full account compromise.

Ecommerce plugins

If you run a standard cart, the plugin is usually a faster route than the API — install, paste your keys, and checkout works.

Platform	Notes
Shopify	App store listing; supports wallets and 3-D Secure out of the box
WooCommerce	WordPress plugin directory; subscriptions supported via WooCommerce Subscriptions
Magento 2	Composer package, Adobe Commerce compatible
BigCommerce	Single-click app install
Salesforce Commerce Cloud	LINK cartridge
SAP Commerce	Certified extension

OpenAPI and tooling

If your language is not listed, generate a client yourself. The specification is public, versioned and always matches production.

OpenAPI 3.1 specification at https://api.bearmerchant.com/openapi.json
Postman collection, importable in one click
Command-line tool for tailing events, triggering test data and replaying webhooks
TypeScript definitions ship inside the Node package — no separate @types install

generate.sh bash

# Generate a client for any supported language
curl -O https://api.bearmerchant.com/openapi.json

openapi-generator-cli generate \
  -i openapi.json \
  -g rust \
  -o ./bearmerchant-rust

Versioning and upgrades

Your account is pinned to the API version that was current when you signed up. Nothing changes underneath you — upgrading is something you choose to do.

SDKs follow semantic versioning. A major bump means a breaking change and never happens in a patch release.
Pin an exact SDK version in production and upgrade deliberately, with the changelog open.
Test a new API version by sending BM-Version on individual requests before switching the account default.
Deprecated fields keep working for at least 12 months after the deprecation notice, and we email every affected account.

test-version.sh bash

# Try a newer API version on one call without changing your account
curl https://api.bearmerchant.com/v1/charges \
  -u sk_live_…: \
  -H "BM-Version: 2026-04-01"