Download the PHP package bryceandy/laravel-beem without Composer

Beem package for Laravel apps

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

Table of Contents

• Installation
• Configuration
• Usage
  1. SMS
     • SMS Delivery Reports
     • Collecting the delivery data
     • SMS Templates
     • Two-Way SMS
       • Collecting the outbound SMS data
  2. Contacts
  3. USSD
     • Collecting callback data
     • Checking the balance
  4. Airtime
     • Airtime callback success
     • Collecting callback data
     • Querying airtime transaction status
     • Checking the balance
  5. Payment Collection
     • Collecting callback data
     • Checking the balance
  6. Payment Checkout
     • Payment checkout callback
     • Collecting callback data
  7. Disbursements
  8. OTP
• Debugging Tips
• License
• Contributing

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

Configuration

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

For this we need to publish the package's configuration file using:

After you have created a Beem vendor account and obtained the keys on the dashboard, add their values in the .env variables

Usage

1. SMS

To send an SMS message, use the Beem facade and pass the message and recipients as arguments

Optionally, you can include your custom sender name only if the request has been accepted on your vendor dashboard.

The default sender name is 'INFO'.

For scheduled SMS, you can use a datetime value or Carbon\Carbon instance, but make sure the timezone is GMT+0

You can also check the remaining SMS balance using

SMS Delivery Reports

If you have specified a callback URL in the account profile, you can use that route in any way.

Optionally, this package comes with:

• A customizable callback route /beem/sms-delivery-report. The prefix can be changed using a .env value for BEEM_PATH. Once it is changed, the route becomes /{env-value}/sms-delivery-report (remember to update this callback on the vendor dashboard).

• An event Bryceandy\Beem\Events\SmsDeliveryReportReceived to collect Beem's data once they are sent to the callback.

Collecting the delivery data

To use the event above, assign a listener in the App\Providers\EventServiceProvider

After you create the listener class, you can use Beem's delivery report

Fetching SMS sender names on your vendor account

New sender names can be requested through the API as well. Follow Beem guidelines on sender name formats

SMS templates

The following can be used to view all SMS templates for the vendor

New SMS templates can also be added:

SMS templates can be edited or deleted if you have their template_id

Two-Way SMS

After requesting a number on the SMS dashboard, you will have to edit it to assign a callback URL.

You can use the given route in any way, but this package comes with:

• A customizable callback route /beem/outbound-sms. The prefix can be changed using a .env value for BEEM_PATH. Once it is changed, the route becomes /{env-value}/outbound-sms.

• An event Bryceandy\Beem\Events\TwoWaySmsCallbackReceived to collect Beem's data once they are sent to the callback.

Collecting the outbound sms data

Assign an event listener for the event above in the EventServiceProvider

Then after creating the listener, you can collect the sms data and send a reply

2. Contacts

List all address books

Use the following to add a new address book

Address books can be edited or deleted if you have their addressbook_id

List contacts of a specific address book. Optionally filter by first name, last name or mobile number

Adding a new contact to an address book requires a mobile number and, an array of address book IDs. Other fields are optional;

Contacts can be edited by the contact_id. Other required fields are address book IDs and the mobile number.

Lastly, a contact can be deleted by specifying the contact_id and their addressbook_id

3. USSD

In a USSD app, Beem will send data to the callback URL you have specified in the USSD dashboard.

This package comes with an optional implementation that provides:

• A customizable route /beem/ussd-callback that defines the callback url. If you add a value for BEEM_PATH in the .env file, the path will now be /{env-value}/ussd-callback.

• An event Bryceandy\Beem\Events\UssdCallbackReceived which can be used to process the data from beem

Collecting USSD callback data

Assign an event listener for the event above in the EventServiceProvider

Then in the listener class ProcessUssdCallback, you can collect the data for processing

Checking the USSD balance

4. Airtime

Start by sending airtime when you have sufficient funds on the airtime dashboard

Airtime callback success

If you have defined a callback URL in the airtime dashboard profile, Beem will send data once the transaction is completed.

Optionally, you can use a callback implementation of this package which provides:

• A callback route /beem/airtime-callback, that can be customized by adding a BEEM_PATH value in the env file. Once you set this variable, your callback route becomes /{env-value}/airtime-callback (remember to change this on the profile).

• An event Bryceandy\Beem\Events\AirtimeCallbackReceived that can be used to listen to all callbacks.

Collecting airtime callback data

Use the event above and assign a new listener in the App\Providers\EventServiceProvider

Then after creating the App\Listeners\ProcessAirtimeCallback class, fetch the callback data

Querying airtime transaction status

Check the status of a recharge request. Use the transaction_id obtained from the ->json() response of the request.

Checking the airtime balance

5. Payment Collection

This package comes with another callback implementation for the payment collection. Available to you is:

• The payment collection event Bryceandy\Beem\Events\PaymentCollectionReceived, which allows you to handle Bpay payments instantly.

• A customizable callback route /beem/payment-collection. If you decide to use this callback implementation, remember to update the callback URL on dashboard the product.

Collecting payment collection callback data

Using the event above, create a listener to handle the callback and assign them in the App\Providers\EventServiceProvider

Then after creating the listener class App\Listeners\ProcessPaymentCollection, fetch the data you need

Checking the payment collection balance

6. Payment Checkout

The package provides an eloquent functionality to handle Beem's payment checkout by redirection.

Collect the required data and use the redirect facade anywhere in your controller or classes;

Payment checkout callback

This package comes with another callback implementation for the payment checkout. Available to you is:

• The payment checkout event Bryceandy\Beem\Events\PaymentCheckoutCallbackReceived, which fires when payment checkout callbacks hit your callback URL.

• A customizable callback route /beem/payment-checkout. If you decide to use this callback implementation, remember to update the callback URL on dashboard the product.

Collecting payment checkout callback data

Using the event above, create a listener and assign it in the App\Providers\EventServiceProvider

Then after creating the listener class App\Listeners\ProcessPaymentCheckout, fetch the data you need

7. Disbursements

To send payments by disbursements, use the facade with appropriate arguments

8. OTP

To request a pin, you require the user's number and, the app ID that you created on the OTP dashboard.

To verify that the user sent the correct PIN, you will send a pinID from the response of the request and, the PIN the user sent.

Debugging Tips

To debug the Bryceandy\Beem\Facades\Beem facade

• Use the ->json() method to fetch data of the response.

• Use the boolean ->successful() method to see if the request was successful

License

MIT license

Contributing

If you spot any bugs or want to add a feature, feel free to send a detailed PR with working tests to improve the project