bitsika / merchant-sdk-php
This package fluent way to use the bitsika merchant api.
Requires
- ext-json: *
- guzzlehttp/guzzle: ^7.2
This package is not auto-updated.
Last update: 2024-10-29 15:23:00 UTC
README
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: https://console.bitsika.africa. Our raw API documentation: https://documenter.getpostman.com/view/12690520/UUy39RrV. Small video demo.
General Requirements
- PHP version 7.0 or greater.
- Composer for installing packages.
- The binding relies on Guzzle to work fine. This package comes pre-installed with Guzzle.
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
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 of our Console.
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
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.
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
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);
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.
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);
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.
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
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
This method is used to create a virtual card
$response = $merchant->virtualCard()->create([ "name" => "Tommie Nii Darku", "currency" => "USD", "amount" => 11, "debit_from" => "GHS" ]); var_dump($response);
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
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
You can top up a virtual card by it's id
with the method below
$cardId = 113; $response = $merchant->virtualCard()->topUp($cardId, [ "amount" => "10", "currency" => "USD", "debit_from" => "GHS" ]); var_dump($response);
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
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
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
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
Whenever invoices are paid, notifications are sent to the webhook URL you provided on the Keys and Security
page of your Bitsika Console 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
(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
The MIT License (MIT). Please see License File for more information.