Download the PHP package gladcodes/ravephp without Composer

RavePHP

This package provides a very simple interface for integrating the Rave Payment Gateway to your PHP application. It is an extension of the Flutterwave-Rave-PHP-SDK package originally developed by Femi Olanipekun.

1. Getting Started
   • Installation
   • Configuration
   • Setting Up for Payment
2. Advanced Usage
   • Custom Payment Fields
   • Payment Metadata
   • Event Handlers
3. License

Getting Started

Installation

This package can be installed as a dependency in your project using Composer.

This adds the RavePHP package to the vendor folder of your project root directory. You can then require the autoloader our PHP scripts to use the package as follows:

Configuration

After the installation, you can set config variables for your PHP app. This package requires that a .env file exists in the root directory of your project that contains all the config variables. The following config variables are required for Rave integration.

Create a new .env file in your project root directory (or edit the file if it already exists) with the following content. Ensure to replace them with your own config values.

Version Control and .env file
It is adviced that you remove the .env file from version control since it usually contains some sensitive information like API keys which should not be visible to the outside world. If you are using Git for version control, remember to add the .env entry to the .gitignore file of your project.

Setting Up for Payment

Payment Form

To make payment, you will need to setup a payment form and a PHP payment script. The payment form is expected to send a form-encoded POST request to the payment script when submitted. In other words, the action of the payment form should be the payment script. Check the payment form example for a sample payment form snippet. The payment form by default should contain the following fields.

Payment Script

The payment script is where you initialize and run Rave to process the payment request sent from the payment form. Rave fetches the payload of the payment request from the PHP $_POST superglobal. Below is the snippet for a basic payment script. The snippet assumes that the payment script is located at the root directory of your project.

Advanced Usage

Custom Payment Fields

You can setup Rave to look for custom payment field names other than the default names in your payment form. For example, say your payment form uses a payment_amount field for the transaction payment amount and a payment_currency field for the currency. You can map the custom fields to the default fields using the fields() method of the Rave instance.

Note: The custom field names must only contain alphanumeric characters (0-9A-Za-z) and underscores (_). Also, the field name must not start with a digit. Hence, '2nd_address' and 'address-2' are invalid, but 'address_2' is valid.

Your payment form should reflect the custom fields:

Payment Metadata

Sometimes you may want to send some metadata alongside the payment request to further describe the payment. You can setup Rave to look for metadata field names in your payment form. For example, say you want to send the customer_ip_address and customer_user_agent alongside the payment data. You can specify metadata fields using the meta() method of the Rave instance.

Note: The metadata field names must only contain alphanumeric characters (0-9A-Za-z) and underscores (_). Also, the field name must not start with a digit. Hence, '2nd_address' and 'address-2' are invalid, but 'address_2' is valid.

Your payment form should include the metadata fields:

Event Handlers

An instance of the Rave\Event\BaseEventHandler is used as the default event handler for the Rave instance. This event handler simply echoes text to the output for each event. You may define your own custom event handler to use instead of the default one. Here are a few guidelines for implementing your own event handler.

1. Must implement Rave\Event\EventHandlerInterface
   Your event handler must implement the following methods of the Rave\Event\EventHandlerInterface:

   Method	Description
   onInit($initializationData)	This is called when a transaction is initialized.
   onSuccessful($transactionData)	This is called only when a transaction is successful.
   onFailure($transactionData)	This is called only when a transaction failed.
   onRequery($transactionReference)	This is called when a transaction is requeried from the payment gateway.
   onRequeryError($requeryResponse)	This is called when a transaction requery returns with an error.
   onCancel($transactionReference)	This is called when a transaction is cancelled by the user.
   onTimeout($transactionReference, $data)	This is called when a transaction doesn't return with a success or a failure response. This can be a timedout transaction on the Rave server or an abandoned transaction by the customer.

   
   

2. Attach an instance of the event handler to the Rave instance using the listener() method
   Create a new instance of your custom event handler and attach it to the Rave instance using the listener() method of the Rave instance.

License

This package is covered by the MIT license. Below is a copy of the license (please read carefully).