README

Laravel package to make online payments from your website via "Telr" payment gateway.

Installation

You can install the package via composer:

composer require melogail/telr-laravel

You can publish and run the migrations with:

php artisan vendor:publish --provider="Melogail\TelrLaravel\TelrLaravelServiceProvider" --tag="migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="Melogail\TelrLaravel\TelrLaravelServiceProvider" --tag="config"

This will add the config/telr-laravel.php config file inside your project config folder.

Inside the config/telr-laravel.php config file you will need to add the relative path to success, decline, and cancel page according to your project route.

return [

    // ...other configs

    'response_path' => [
        'return_auth' => '/:path/to_success_page',
        'return_decl' => '/:path/to_decline_page',
        'return_can' => '/:path/to_cancel_page',
    ],
];

Add the following code to your .env file and change the values to your payment values.

TELR_STORE_ID=      # Payment API key [its different from your "Service API" key].
TELR_AUTH_KEY=      # Payment API key.
TELR_TEST_MODE=     # 1=Test mode | 0=Live mode.
TELR_CURRENCY=      # Currency used for payment.

Add TelrLaravel facade inside your config/app.php file.

'aliases' => Facade::defaultAliases()->merge([
        // 'ExampleClass' => App\Example\ExampleClass::class,
        'TelrLaravel' => \Melogail\TelrLaravel\Facades\TelrLaravel::class,

    ])->toArray(),

Usage

To make payment you need to invoke the TelrLaravel class in your controller.

use Melogail\TelrLaravel\TelrLaravel;

$telr_laravel = new TelrLaravel();

Use makePayment() method to make payment.

$telr_laravel->makePayment('183-487-143', 9.50, 'Cart generated by John Doe on 2023-1-16');

After calling the makePayment() method, then you call for pay() method to perform the payment.

The makePayment(string $order_id, float $amount, string $description) method requires three parameters:

string $order_id : The order ID generated by your system.
float $amount : The amount to be paid in decimals ex: 9.50.
string $description : A short description for the payment, max length 63 characters.

While the pay(<array $params>) method accepts one optional parameter as an array that holds the essential billing information required by the payment gateway. If these parameters are ignored in your system, the payment gateway page will prompt the user to add these information.

The required information is as follows:

bill_fname : The user first name.
bill_sname : The user sure name.
bill_addr1 : The main billing address.
bill_phone : The user phone number.
bill_city : The city, ex: Dubai.
bill_country : The country, MUST be supplied as a two character ISO 3166 country code, ex: US, GB, EG.
bill_email : User main email.

$billing_parameters = [
    'bill_fname' => $first_name,
    'bill_sname' => $sure_name,
    'bill_addr1' => $address1,
    'bill_phone' => $phone,
    'bill_city' => $city,
    'bill_country' => $country,
    'bill_email' => $email
];

$telr_laravel->makePayment('183-487-143', 9.50, 'Cart generated by John Doe on 2023-1-16')
    ->pay($billing_parameters);

Full code example:

use Melogail\TelrLaravel\TelrLaravel;

$telr_laravel = new TelrLaravel();

$billing_parameters = [
    'bill_fname' => $first_name,
    'bill_sname' => $sure_name,
    'bill_addr1' => $address1,
    'bill_phone' => $phone,
    'bill_city' => $city,
    'bill_country' => $country,
    'bill_email' => $email
];

$telr_laravel->makePayment('183-487-143', 9.50, 'Cart generated by John Doe on 2023-1-16')->pay($billing_parameters);

For more information about the billing parameters, check the platform documentation here

Confirm Transaction and Update Transaction Status

After setting up payment status path pages inside your config/telr-laravel.php file, you need to create three different views, each for each status (Success, Decline, Cancel).

Inside each view you need to call the setTransactionStatus(Request $request) method on the Telr facade to update the transaction status based on its response return.

use Illuminate\Http\Request;
use \Melogail\TelrLaravel\Facades\TelrLaravel;

class PaymentController extends Controller {

    public function success(Request $request){
    
        // Calling setTransactionStatus facade.
        TelrLaravel::setTransactionStatus($request);
        
        return view( //... success view page);
    }
    
    
    public function decline(Request $request){
    
        // Calling setTransactionStatus facade.
        TelrLaravel::setTransactionStatus($request);
        
        return view( //... decline view page);
    }
    
    
    public function cancel(Request $request){
    
        // Calling setTransactionStatus facade.
        TelrLaravel::setTransactionStatus($request);
        
        return view( //... cancel view page);
    }

}

Testing Cards

You can use the following cards to test your payment gateway integration.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

Mohamed Elogail

License

The MIT License (MIT). Please see License File for more information.

melogail / telr-laravel

Maintainers

Details