Download the PHP package kofi/ngpayments without Composer

NgPayments

Simple integration with Nigerian payment gateways - Paystack and Rave (Flutterwave). This package simplifies the process of building requests to these APIs and retrieving their responses for processing.

Requirements, Installation & Configuration

This package requires at least php7.1

Install using Composer:

composer require kofi/ngpayments

This package uses 4 configuration values. You are required to provide 2 of these configuration values while the package has defaults for the other two. You can set your configurations using either .env, PHP Constants or configuration caching

Using .env (recommended)

If you are using Rave (Flutterwave) instead of Paystack, replace the PAYSTACK prefix with RAVE and set your payment provider like so:

Using constants in a config.php file (not recommended)

Caching configurations (relevant for Laravel users)

If you are using the Laravel artisan config:cache command to cache your configurations in production, the package will not have access to the variables from your .env file so you'd need to configure the package in one of your service providers.

Firstly load the configurations from .env into Laravel's config by going to config/services.php and doing this

Then in your AppServiceProvider's boot() method ( you could place this in any other service provider) do this:

Configuring Http Exceptions and Payment Exceptions

By default http exceptions are disabled for requests made by the package. But if you would like to deal with BadResponseException exceptions thrown by the Guzzle Http Client for 4xx and 5xx level http responses, you can enable http exceptions this way:

Setting Request Parameters

The package provides you with some flexibility in how you set your request parameters before they are sent to the configured Payment Provider.

For example, to bill a customer using Paystack, after configuring Paystack using the instructions above you could do this:

Using the Bill constructor allows you to set the parameters that are required for that request but you might have additional parameters you'd like to send along with your request. For instance, you might want to set your own payment reference rather than use the reference that Paystack generates for you. In that instance you could do any of these:

Using Magic set methods

Parameters set this way will automatically be rendered and sent to the configured payment provider with snake_case.

You can use kebab-case like so:

If you don't want any type of case applied use

Using Magic properties

Using an associative array of parameters

Check the documentation for the provider you are integrating with to learn more about the request options needed for various endpoints.

Billing

To charge a customer an amount of naira for a product, say N7000, follow these steps:

1) Initialize the payment and redirect the customer to the payment page

2) Verify that that the customer paid what they were expected to pay

You would typically do this step in response to a request from either Paystack or Rave to the callback_url you set in your API dashboard or with your request using $bill->setCallbackUrl($url) (see their docs for more information).

If the Payment is not valid, by default a FailedPaymentException is thrown which you can use to log details about the request and the response received from the PaymentProvider like so:

If you don't want to handle this type of exceptions, you can disable this using

Recurring Billing

Both Rave and Paystack support recurring billing through the use of tokens. To charge a customer with recurring billing, you have to ensure that customer has made at least one payment to you so that your PaymentProvider can generate the token to send you for use in future billings.

To charge a customer using Recurring Billing follow these steps:

1) Initialize a Bill payment

2) Validate the payment and store the authorization code or token from your payment provider

3) Create an AuthBill and charge the customer anytime you need to

Note that the authorization_code you get from your provider is only valid for the specified customer's email.

Split Billing

To share a customer's payment with a merchant you need to first create a sub account for the merchant, and then use the subaccount id when billing the customer. Check your payment provider's documentation to learn more about subaccounts.

1) Creating and storing the subaccount

To get a list of banks and their corresponding codes to use when creating subaccounts, you can call the Subaccount::fetchBanks() method.

Paystack requires you to pass in the bank name when creating the subaccounts while Rave requires you to pass in the bank code

Like with bills, you could also use magic setters and magic properties to set your request variables for subaccounts.

2) Split a bill with the created subaccount

You could also split AuthBill payments with subaccounts

3) Validate the payment

Plans and Subscriptions

You could also create payment plans with your payment provider and subscribe customers to those payment plans.

Note that, if you do this, the customer will be able to cancel their subscriptions directly with either Paystack or Rave, so you'd need to regularly check to ensure that a customer has not cancelled their subscription before you give value.

1) Create the Payment Plan

2) Subscribe a customer to the payment plan

Integrating with Paystack

When you create a Plan or a Subaccount with Paystack, Paystack returns two forms of identifying these objects: An alphanumeric code and an id.

When you make a call to either $plan->save() or $subaccount->save() methods, you are going to be getting the alphanumeric code. The reason for this is that while you can identify plans and subaccounts with the numeric id, you can't use that numeric id to initialize payments. You need the code for that.

So when you save a subaccount or plan, you'll be getting the alphanumeric code which you can then store in your database for use in future transactions.

Integrating with Rave

Creating Subaccounts with Rave

The Subaccount class that ships with this package has 4 default arguments in its constructor

In the documentation for Rave's Create Subaccount endpoint you will find that Rave requires you to set more parameters than this. The package helps you set the split_type to percentage and the country to NG. The $percentage_charge in the constructor is used to set the split_value required by Rave. This is fine if you want to work with percentage splits.

To create a Subaccount with Rave you would still need to set the business_mobile and the business_email yourself, in order to successfully create a subaccount when you call the $subaccount->save() method. So to create a subaccount with Rave you would do this:

Also note that when you save a subaccount, you are going to be getting the subaccount's alphanumeric id which you can use to initialize payments later with either Bill or AuthBill.