PHPackages                             bitsika/merchant-sdk-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. bitsika/merchant-sdk-php

ActiveLibrary[API Development](/categories/api)

bitsika/merchant-sdk-php
========================

This package fluent way to use the bitsika merchant api.

1.2.1(3y ago)01342MITPHP

Since Jan 22Pushed 3y ago3 watchersCompare

[ Source](https://github.com/bitsika/merchant-sdk-php)[ Packagist](https://packagist.org/packages/bitsika/merchant-sdk-php)[ Docs](https://github.com/bitsika/merchant-sdk-php)[ RSS](/packages/bitsika-merchant-sdk-php/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (1)Versions (17)Used By (0)

Bitsika Console for Merchants - PHP SDK
=======================================

[](#bitsika-console-for-merchants---php-sdk)

The Bitsika PHP library gives convenient access to the Console Merchant API for applications written in the PHP language. Devs and merchants alike can use our API and corresponding dashboard to create invoices that any Bitsika user can instantly pay. Learn more here: . Our raw API documentation: . Small video [demo.](https://www.youtube.com/watch?v=qOBr1cXlV1s)

General Requirements
--------------------

[](#general-requirements)

1. PHP version 7.0 or greater.
2. Composer for installing packages.
3. The binding relies on [Guzzle](https://guzzle3.readthedocs.io/index.html) to work fine. This package comes pre-installed with Guzzle.

Installation
------------

[](#installation)

Install the Bitsika PHP Library. Version to install is `dev-main`.

```
composer require bitsika/merchant-sdk-php
```

You can also install these packages using the `composer install` command from your `composer.json` file.

```
{
    "require": {
        "bitsika/merchant-sdk-php": "1.0.9"
    }
}
```

To use the bindings, use Composer's autoload.

```
require_once __DIR__ . '/vendor/autoload.php';
```

Getting Started
---------------

[](#getting-started)

To get started, create an instance of the Merchant class. You will need a copy of your Bitsika API `Secret Key`. This can be found on the [Keys and Security page](https://merchant.bitsika.africa/dashboard/merchant/keys-and-security) of our [Console](https://merchant.bitsika.africa/).

```
require_once __DIR__ . '/vendor/autoload.php';

use Bitsika\Merchant;

$merchant = new Merchant('PUT_YOUR_SECRET_KEY_HERE');
```

The variable `$merchant` is now an instance of the Merchant class and can be used to perform any of the multiple tasks available to merchants.

Merchant Methods
================

[](#merchant-methods)

### Get merchant detail.

[](#get-merchant-detail)

This method returns basic data related to the merchant company whose `Secret Key` you’re currently using. Data returned includes company name, Bitsika username, profile picture URL, KYC status, balances across multiple currencies and much more.

```
$response = $merchant->detail();

var_dump($response);
```

### Get merchant statistics.

[](#get-merchant-statistics)

This method returns transaction statistics pertaining to the respective merchant company. It returns data like number of unique users, sum of successful transactions, sum of all transactions, etc.

```
$response = $merchant->statistics();

var_dump($response);
```

Invoice Methods
===============

[](#invoice-methods)

### Create invoice.

[](#create-invoice)

This method returns basic data for a newly created invoice including (most importantly) the invoice / payment web link URL. This invoice can we paid by any Bitsika user who opens the payment link. They can pay the invoice with any currency balance in their Bitsika app. You, the merchant, will get settled instantly in the currency you specify when creating the invoice below.

```
$response = $merchant->invoices()->create([
    "title" => "Vanilla Ice-Cream",
    "description" => "2 scoops of vanilla ice-cream, chocolate biscuits and coconut shavings.",
    "amount" => 2000000,
    "currency" => "NGN",
    "recipient_email" => "test@example.com",
    "photo_url" => "https://image.com/test.jpg"
]);

var_dump($response);
```

ParamRequiredAboutValidationtitleYesTitle of the invoice. Here, provide a heading of the service you rendered to your customer. For example "Vanilla ice-cream with coconut shavings".String. Minimum number of characters = 4. Maximum number of characters = 50.descriptionYesProvide more info on the service your customer is about to pay for. Example: "2 scoops of vanilla ice-cream, chocolate biscuits and coconut shavings. Large cup size".String. Minimum number of characters = 4. Maximum number of characters = 280.amountYesAmount number that the service costs.Integer. Minimum amount: 1. Maximum amount: 10000000. 2 decimal places, if used. It is important to note that because of KYC, fraud control and best practices, we suggest that the amount of your invoice doesn't exceed the equivalent of $1,000 in its respective currency.currencyYesDenote the currency you / your company would like the payment of this invoice to be settled in.String. Provide one of the following currencies: `NGN`, `USD`, `XOF`, `XAF`, `GHS`recipient\_emailNoWho should a copy of this invoice be sent to upon creation?String / Email format. Minimum number of characters = 4. Maximum number of characters = 50.photo\_urlNoProvide the URL of your product's / service's item photo.String / URL format. Minimum number of characters = 4. Maximum number of characters = 280.### Get invoice by id.

[](#get-invoice-by-id)

This method is used to query an invoice’s data any time in the future. You can use this method to manually check on the state (if it’s been paid or not) or expiry status of an invoice.

```
$invoiceId = 'INVOICE_ID_HERE';
$response = $merchant->invoices()->get($invoiceId);

var_dump($response);
```

### Send cash.

[](#send-cash)

Your merchant company needs to be verified (KYC verification) before you can successfully call this method.

Use this method to send money from your company’s merchant balances to any Bitsika user or merchant with a $username or $cashtag. All such transfers are instant and free.

```
$response = $merchant->transaction()->sendCash([
   "platform" => "bitsika",
   "amount" => 100,
   "currency" => "USD",
   "username" => "davido",
   "debit_from" => "USD",
   "purpose" => ""
]);

var_dump($response);
```

ParamRequiredAboutValidationplatformYesWhat network are you transferring the money on?String. `bitsika`amountYesNumerical value of amount to be transferred.Integer. Minimum amount: 1. Maximum amount: 10000000. 2 decimal places, if used. It is important to note that because of KYC, fraud control and best practices, we suggest that the amount of your invoice doesn't exceed the equivalent of $1,000 in its respective currency.currencyYesDenote the currency you / your company would like the end user to receive the transfer in.String. Provide one of the following currencies: `NGN`, `USD`, `XOF`, `XAF`, `GHS`usernameYesProvide the `username` or `cashtag` of the Bitsika user or merchant you're making the transfer to.String. Example: `davido`, `taylorswift13`. Do not include the `$` infront of the username when writing it.debit\_fromYesDenote the currency balance you / your company would like the transfer to be deducted from. You can make a transfer in one currency, debited from another. For example: you can send a user 100 USD, but choose to deduct the debit from your NGN balance.String. Provide one of the following currencies: `NGN`, `USD`, `XOF`, `XAF`, `GHS`purposeNoA comment or note to accompany the transfer.String. Minimum number of characters = 4. Maximum number of characters = 255.### Verify transaction.

[](#verify-transaction)

Use this method to verify the status of transfers you make with the `Send Cash` method above.

```
$transactionId = "YOUR_TRANSACTION_ID_HERE";

$response = $merchant->transaction()->get($transactionId);

var_dump($response);
```

### Search for a user.

[](#search-for-a-user)

Use this method to search for a bitsika user, and verify is they exist.

```
$username = "USERNAME_HERE";

$response = $merchant->customer()->search($username);

var_dump($response);
```

Virtual card
============

[](#virtual-card)

Merchants can generate virtual cards for their account. Here's a list of operations that can be performed pertaining to a virtual card.

### Create Card

[](#create-card)

This method is used to create a virtual card

ParamRequiredAboutValidationnameYesThe virtual card nameStringcurrencyYesThe currency the generated card will haveString. `NGN`, `USD`, `GHS`amountYesThe amount to fund the card with upon creationInteger. numericdebit\_fromYesThe wallet currency to be debited from upon creationString.`NGN`, `USD`, `GHS````
$response = $merchant->virtualCard()->create([
   "name" => "Tommie Nii Darku",
   "currency" => "USD",
   "amount" => 11,
   "debit_from" => "GHS"
]);

var_dump($response);
```

### Get all virtual cards

[](#get-all-virtual-cards)

You can fetch all the available virtual cards with the method below

```
$response = $merchant->virtualCard()->all();

var_dump($response);
```

### Get virtual card by id

[](#get-virtual-card-by-id)

You can get a virtual card by it's `id` with the method below

```
$cardId = 113;
$response = $merchant->virtualCard()->get($cardId);

var_dump($response);
```

### Top-up virtual card by id

[](#top-up-virtual-card-by-id)

You can top up a virtual card by it's `id` with the method below

ParamRequiredAboutValidationamountYesThe amount to fund the card withInteger. numericcurrencyYesThe currency to fund the card withString. `NGN`, `USD`, `GHS`debit\_fromYesThe wallet currency to be debited fromString.`NGN`, `USD`, `GHS````
$cardId = 113;
$response = $merchant->virtualCard()->topUp($cardId, [
   "amount" => "10",
   "currency" => "USD",
   "debit_from" => "GHS"
]);

var_dump($response);
```

### Withdraw from card by id

[](#withdraw-from-card-by-id)

You can withdraw from a virtual card by it's `id` with the method below

```
$cardId = 113;
$response = $merchant->virtualCard()->withdraw($cardId, [
   "amount" => "5"
]);

var_dump($response);
```

### Get card Transactions

[](#get-card-transactions)

You can fetch a virtual card's transaction by it's `id` with the method below

```
$cardId = 113;
$response = $merchant->virtualCard()->transactions($cardId);

var_dump($response);
```

### Freeze Card

[](#freeze-card)

You can freeze a virtual card by it's `id` with the method below

```
$cardId = 113;
$response = $merchant->virtualCard()->freeze($cardId);

var_dump($response);
```

### Unfreeze Card

[](#unfreeze-card)

You can unfreeze a virtual card by it's `id` with the method below

```
$cardId = 113;
$response = $merchant->virtualCard()->unfreeze($cardId);

var_dump($response);
```

Invoice Webhooks
----------------

[](#invoice-webhooks)

Whenever invoices are paid, notifications are sent to the webhook URL you provided on the `Keys and Security` page of your [Bitsika Console](https://console.bitsika.africa) account. Your webhook URL is expected to be an unauthenticated `POST` request URL.

Once payments are recieved, weather `Initiated`, `Failed` or `Successful`, we make a Post request containing the event object to your webhook URL.

The request object contains the `event`, `invoice_id` and `transaction` details.

The `event` key will be `invoice.payment_failed` for failed payments, or `invoice.payment_success` for successful payments.

The `invoice_id` is the `id` of the invoice being paid for, while the `transaction` key contains a JSON object of the payment.

### Verifying webhooks

[](#verifying-webhooks)

(Optional) Everytime a request is made to your webhook url, for security reasons, we also send a `x-bitsika-signature` in the header. This contains a `HMAC SHA512` hash of the payload signed using your secret key.

```
if($_SERVER['HTTP_X_BITSIKA_SIGNATURE'] !== hash_hmac('sha512', $input, YOUR_SECRET_KEY_HERE))
    exit();
```

**Sample Response -**An example of the JSON response to expect:

```
{
   "id": 935,
   "reference": "87-1601554148-1530",
   "currency": "USD",
   "status": "Successful",
   "amount": 50,
   "type": "Out",
   "created_at": "2020-10-01 12:09:08",
   "updated_at": "2020-10-01 12:09:08",
   "from_account": {
      "id": 87,
      "name": "Tom Tom Darku",
      "username": "tdlover"
   }
}

```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~27 days

Recently: every ~61 days

Total

13

Last Release

1297d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/00ffaaace8a05e5cf8a3db80ff57db4d65798f9f0d0468a18c893610ea9e87bf?d=identicon)[ajimoti](/maintainers/ajimoti)

---

Top Contributors

[![ajimoti](https://avatars.githubusercontent.com/u/26599467?v=4)](https://github.com/ajimoti "ajimoti (6 commits)")[![tommie24](https://avatars.githubusercontent.com/u/6250856?v=4)](https://github.com/tommie24 "tommie24 (6 commits)")

---

Tags

bitsikabitsika merchant

### Embed Badge

![Health badge](/badges/bitsika-merchant-sdk-php/health.svg)

```
[![Health](https://phpackages.com/badges/bitsika-merchant-sdk-php/health.svg)](https://phpackages.com/packages/bitsika-merchant-sdk-php)
```

###  Alternatives

[statamic/cms

The Statamic CMS Core Package

4.8k3.6M966](/packages/statamic-cms)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M46](/packages/tencentcloud-tencentcloud-sdk-php)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k38](/packages/neuron-core-neuron-ai)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

528.5M7](/packages/avalara-avataxclient)[files.com/files-php-sdk

Files.com PHP SDK

2481.1k](/packages/filescom-files-php-sdk)[aimeos/prisma

A powerful PHP package for integrating media related Large Language Models (LLMs) into your applications

1943.1k5](/packages/aimeos-prisma)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)