PHPackages                             bryceandy/laravel-selcom - 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. bryceandy/laravel-selcom

ActiveLibrary[API Development](/categories/api)

bryceandy/laravel-selcom
========================

Laravel package that integrates with Selcom APIs (Utility Payments, Wallet Cashin, Agent Cashout, C2B, Qwiksend, VCN, Checkout & International Money Transfer

v0.0.7(3y ago)169647MITPHPPHP ^7.4|^8.0

Since Sep 15Pushed 3y ago3 watchersCompare

[ Source](https://github.com/bryceandy/laravel-selcom)[ Packagist](https://packagist.org/packages/bryceandy/laravel-selcom)[ Patreon](https://www.patreon.com/bryceandy)[ RSS](/packages/bryceandy-laravel-selcom/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)Dependencies (2)Versions (8)Used By (0)

[![](https://camo.githubusercontent.com/debec7d3dadb848dc39ffb8d321cd4a221243e2c65583bc68e8147f188691482/68747470733a2f2f6272796365616e64792e636f6d2f73656c636f6d2e706e67)](https://camo.githubusercontent.com/debec7d3dadb848dc39ffb8d321cd4a221243e2c65583bc68e8147f188691482/68747470733a2f2f6272796365616e64792e636f6d2f73656c636f6d2e706e67)

Selcom package for Laravel apps
===============================

[](#selcom-package-for-laravel-apps)

[![Actions Status](https://github.com/bryceandy/laravel-selcom/workflows/Tests/badge.svg)](https://github.com/bryceandy/laravel-selcom/actions)[![Total Downloads](https://camo.githubusercontent.com/2d7e0af7e8c74e9d8e56c7c8d36bae08578bc0479ae8e8df4fa3ce5f750b661b/68747470733a2f2f706f7365722e707567782e6f72672f6272796365616e64792f6c61726176656c2d73656c636f6d2f642f746f74616c2e737667)](https://packagist.org/packages/bryceandy/laravel-selcom)[![Latest Stable Version](https://camo.githubusercontent.com/9309b1887b627dcc0dfa40ab7afea907505be4fd47278d5ee66b8009df51ad76/68747470733a2f2f706f7365722e707567782e6f72672f6272796365616e64792f6c61726176656c2d73656c636f6d2f762f737461626c652e737667)](https://packagist.org/packages/bryceandy/laravel-selcom)[![License](https://camo.githubusercontent.com/332a2c14a95acc47665586f3dc5a64f5460a4bfcd75f0f69c9465c46a413a5e8/68747470733a2f2f706f7365722e707567782e6f72672f6272796365616e64792f6c61726176656c2d73656c636f6d2f6c6963656e73652e737667)](https://packagist.org/packages/bryceandy/laravel-selcom)

This package enables Laravel developers to integrate their websites/APIs with all Selcom API services

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

[](#installation)

Pre-installation requirements

- Supports Laravel projects starting version 8.\*
- Minimum PHP version is 7.4
- Your server must have the cURL PHP extension (ext-curl) installed

Then proceed to install:

```
composer require bryceandy/laravel-selcom

```

Configuration
-------------

[](#configuration)

To access Selcom's APIs, you will need to provide the package with access to your Selcom vendorID, API Key and Secret Key.

After obtaining the three credentials from Selcom support, add their values in the `.env` variables:

```
SELCOM_VENDOR_ID=123456
SELCOM_API_KEY=yourApiKey
SELCOM_API_SECRET=yourSecretKey

SELCOM_IS_LIVE=false
```

Note that when starting you will be provided with test credentials.

When you change to live credentials don't forget to change `SELCOM_IS_LIVE` to `true`.

We are going to update more configuration settings as we move along, but feel free to publish the config to fully customize it.

```
php artisan vendor:publish --tag=selcom-config

```

Run the migration command to create a table that stores Selcom payments:

```
php artisan migrate

```

Checkout API
------------

[](#checkout-api)

Checkout is the simplest Selcom API we can start processing payments with.

### Checkout payments using USSD

[](#checkout-payments-using-ussd)

This API automatically pulls your user's USSD payment menu directly after being called.

**Note**: As of now, this is only applicable to AirtelMoney and TigoPesa customers.

```
use Bryceandy\Selcom\Facades\Selcom;

Selcom::checkout([
    'name' => "Buyer's full name",
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
    'no_redirection' => true,
    // Optional fields
    'currency' => 'Default is TZS',
    'items' => 'Number of items purchased, default is 1',
    'payment_phone' => 'The number that will make the USSD transactions, if not specified it will use the phone value',
]);
```

Other networks may use USSD checkout manually with tokens as shown with other checkout options below.

### Checkout to the payments page (without cards)

[](#checkout-to-the-payments-page-without-cards)

The payment page contains payment options such as QR code, Masterpass, USSD wallet pull, mobile money payment with tokens.

To redirect to this page, we will use the previous example, but **return** without the `no_redirection` option or assign it to `false`:

```
use Bryceandy\Selcom\Facades\Selcom;

return Selcom::checkout([
    'name' => "Buyer's full name",
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
]);
```

### Checkout to the payments page (with cards)

[](#checkout-to-the-payments-page-with-cards)

To use the cards on the payment page, return the following request:

```
use Bryceandy\Selcom\Facades\Selcom;

return Selcom::cardCheckout([
    'name' => "Buyer's full name",
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
    'address' => "Your buyer's address",
    'postcode' => "Your buyer's postcode",
    // Optional fields
    'user_id' => "Buyer's user ID in your system",
    'buyer_uuid' => $buyerUuid, // Important if the user has to see their saved cards.
    // See the last checkout section on how to fetch a buyer's UUID
    'country_code' => "Your buyer's ISO country code: Default is TZ",
    'state' => "Your buyer's state: Default is Dar Es Salaam",
    'city' => "Your buyer's city: Default is Dar Es Salaam",
    'billing_phone' => "Your buyer's billing phone number: forexample 255756334000",
    'currency' => 'Default is TZS',
    'items' => 'Number of items purchased, default is 1',
]);
```

Optionally, you may specify using the `.env` file the following:

- The page where your users will be redirected once they complete a payment:

```
SELCOM_REDIRECT_URL=https://mysite.com/selcom/redirect
```

- The page where your users will be taken when they cancel the payment process:

```
SELCOM_CANCEL_URL=https://mysite.com/selcom/cancel
```

If you feel lazy, this package already ships with these pages for you. And if you want to customize them, run:

```
php artisan vendor:publish --tag=selcom-views

```

[![](https://camo.githubusercontent.com/d0caee385e99a2f1b80fe7a43e8ad7482ea8fe1d6b5f3201b9bb44ffb3d9e953/68747470733a2f2f6272796365616e64792d646576626c6f672e73332d75732d656173742d322e616d617a6f6e6177732e636f6d2f313633313731313530352e706e67)](https://camo.githubusercontent.com/d0caee385e99a2f1b80fe7a43e8ad7482ea8fe1d6b5f3201b9bb44ffb3d9e953/68747470733a2f2f6272796365616e64792d646576626c6f672e73332d75732d656173742d322e616d617a6f6e6177732e636f6d2f313633313731313530352e706e67)[![](https://camo.githubusercontent.com/d1ab7e818f2400e34bed80dce8d6efba9e7ab42b3d39b41460f7f6fcce410b26/68747470733a2f2f6272796365616e64792d646576626c6f672e73332d75732d656173742d322e616d617a6f6e6177732e636f6d2f313633313731313637382e706e67)](https://camo.githubusercontent.com/d1ab7e818f2400e34bed80dce8d6efba9e7ab42b3d39b41460f7f6fcce410b26/68747470733a2f2f6272796365616e64792d646576626c6f672e73332d75732d656173742d322e616d617a6f6e6177732e636f6d2f313633313731313637382e706e67)

- Also, you can assign a prefix for the package. This will be applied to the routes and order IDs

```
SELCOM_PREFIX=SHOP
```

#### Customizing the payment page theme

[](#customizing-the-payment-page-theme)

The configuration contains a `colors` field which specifies the theme of your payment page.

To customize the colors, add the color values in the `.env` file:

```
SELCOM_HEADER_COLOR="#FG345O"
SELCOM_LINK_COLOR="#000000"
SELCOM_BUTTON_COLOR="#E244FF"
```

For JSON requests (API applications), this type of checkout to the payments page will return data with `payment_gateway_url` instead of redirecting to that page:

```
{
  "payment_gateway_url": "https://example.selcommobile-url.com"
}
```

### Checkout payments with cards (without navigating to the payment page)

[](#checkout-payments-with-cards-without-navigating-to-the-payment-page)

To use a card without navigating to the payment page, you need to have already created a card for the paying user by navigating to the payment page.

This is very useful for recurring or on-demand card payments. The data is the same as the previous card checkout, except we are adding `no_redirection`, `user_id` & `buyer_uuid`:

```
use Bryceandy\Selcom\Facades\Selcom;

Selcom::cardCheckout([
    'name' => "Buyer's full name",
    'email' => "Buyer's email",
    'phone' => "Buyer's msisdn, for example 255756334000",
    'amount' => "Amount to be paid",
    'transaction_id' => "Unique transaction id",
    'no_redirection' => true,
    'user_id' => "Buyer's user ID in your system",
    'buyer_uuid' => $buyerUuid, // See instructions below on how to obtain this value
    'address' => "Your buyer's address",
    'postcode' => "Your buyer's postcode",
    // Optional fields
    'country_code' => "Your buyer's ISO country code: Default is TZ",
    'state' => "Your buyer's state: Default is Dar Es Salaam",
    'city' => "Your buyer's city: Default is Dar Es Salaam",
    'billing_phone' => "Your buyer's billing phone number: forexample 255756334000",
    'currency' => 'Default is TZS',
    'items' => 'Number of items purchased, default is 1',
]);
```

This method will fetch 3 saved cards of the user and try all of them until a payment is successful or all fail.

#### Obtaining the buyer's UUID

[](#obtaining-the-buyers-uuid)

If this user has visited the payment page before to make a payment, then their uuid is already in the database.

```
use Illuminate\Support\Facades\DB;

$buyerUuid = DB::table('selcom_payments')
    ->where([
        ['user_id', '=' auth()->id()],
        ['gateway_buyer_uuid', '', null],
    ])
    ->value('gateway_buyer_uuid');
```

### Listing a user's stored cards

[](#listing-a-users-stored-cards)

To fetch the user's stored cards could be useful to know if a user has cards, or if there is a need to delete.

You will require a user's ID and `buyer_uuid`:

```
use Bryceandy\Selcom\Facades\Selcom;

Selcom::fetchCards($userId, $gatewayBuyerUuid);
```

### Deleting a user's stored card

[](#deleting-a-users-stored-card)

To delete a user's stored card you need a `buyer_uuid` and card ID obtained from `fetchCards` request above.

```
use Bryceandy\Selcom\Facades\Selcom;

Selcom::deleteCard($cardId, $gatewayBuyerUuid);
```

### Checkout webhook/callback

[](#checkout-webhookcallback)

The package comes with an implementation of the payment webhook.

When Selcom sends the payment status to your site, the data in the `selcom_payments` table will be updated and an event `Bryceandy\Selcom\Events\CheckoutWebhookReceived` will be dispatched.

You can create a listener for the event:

```
class EventServiceProvider extends ServiceProvider
{
    protected $listen = [
        \Bryceandy\Selcom\Events\CheckoutWebhookReceived::class => [
            \App\Listeners\ProcessWebhook::class,
        ],
    ];
}
```

Then in your listener `App\Listeners\ProcessWebhook`, you can do anything with the order ID:

```