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.

Card number	Type	CVV	MPI
4000 0000 0000 0002	Visa	123	No
4111 1111 1111 1111	Visa	123	Yes
4444 3333 2222 1111	Visa	123	Yes
4444 4244 4444 4440	Visa	123	Yes
4444 4444 4444 4448	Visa	123	Yes
4012 8888 8888 1881	Visa	123	Yes
5105 1051 0510 5100	Mastercard	123	No
5454 5454 5454 5454	Mastercard	123	Yes
5555 5555 5555 4444	Mastercard	123	Yes
5555 5555 5555 5557	Mastercard	123	Yes
5581 5822 2222 2229	Mastercard	123	Yes
5641 8209 0009 7002	Maestro UK	123	Yes
6767 0957 4000 0005	Solo	123	No
3434 343434 34343	American Express	1234	No
3566 0020 2014 0006	JCB	123	No
3111 1111 1111 1111	MADA	123	No

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