victorybiz/laravel-crypto-payment-gateway

GoUrl.io Crypto Payment Gateway for Laravel

v1.3.0 2024-04-01 19:16 UTC

Requires

• php: ^7.4|^8.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0
• tecnickcom/tc-lib-barcode: ^1.15

Requires (Dev)

• orchestra/testbench: ^6.0|^8.0|^9.0
• phpunit/phpunit: ^9.0|^10.5

MIT

• Victory Osayi Airuoyuwa

• payment
• crypto
• laravel
• cryptocurrency
• payment-gateway
• victorybiz
• laravel-crypto-payment-gateway
• laravel-bitcoin-payment-gateway
• cryptoapi
• cryptocurrency-payment
• crypto-payment-gateway
• bitcoin-payment-gateway
• gourl-payment-gateway
• gourl.io
• gourl

README

GoUrl.io Crypto Payment Gateway for Laravel.

Table of Contents

• Laravel Crypto Payment Gateway
  • Table of Contents
  • Installation
  • Requirements
    • Dependencies
  • Configuration - Define payment routes - Define the public key and private keys in environment file
    • Config Options
  • Usage
    • Payment Data Submission
      • Usage with Form Submit
      • Usage with AJAX Request
      • Usage with Session Redirect (through controller, Livewire component or anywhere in your application)
    • The Callback
      • Callback Controller
      • Callback Route
      • IPN (Instant Payment Notification)
    • Eloquent Model for crypto_payments table
  • Advanced Usage
    • Instance of GoUrl.io PHP Class API (cryptobox.class.php)
  • Resources
  • Testing
  • Changelog
  • Contributing
    • Security
  • Credits
  • License
  • Laravel Package Boilerplate

Installation

You can install the package via composer:

composer require victorybiz/laravel-crypto-payment-gateway

Next, you should publish the configuration, migration and asset files using the vendor:publish Artisan command. The configuration, migration and asset files will be placed in your application's config, database/migrations and public/vendor directory respectively:

php artisan vendor:publish --provider="Victorybiz\LaravelCryptoPaymentGateway\LaravelCryptoPaymentGatewayServiceProvider"

Requirements

This package is create a laravel wrapper on the GoUrl.io's CryptoAPI Payment Gatway.

• Register for Free or Login on the GoUrl.io website.
• Create new payment box.
• Ensure to specify your External wallet address and Callback Url
• Obtain the Public Key and Private of each coin's payment box you want to support.

Dependencies

The compact and standard box template uses Alpinejs and TailwindCSS. While the gourl-cryptobox-iframe and gourl-cryptobox-boostrap uses assets provided by GoUrl.io. You do not need to install any of the dependencies, the package uses the CDN version of dependencies.

Configuration

You need create the following files;

• A PaymentController with a callback method. Learn more below.
• A static class method anywhere in your application to hook IPN (Instant Payment Notification). Preferably you can just define the static method public static function ipn($cryptoPaymentModel, $payment_details, $box_status){..} in the same PaymentController for easy code management. Learn more below
• Define the payment routes.
• Define the public key and private keys in environment file

Define payment routes

// routes/web.php

// You can protect the 'payments.crypto.pay' route with `auth` middleware to allow access by only authenticated user
Route::match(['get', 'post'], '/payments/crypto/pay', Victorybiz\LaravelCryptoPaymentGateway\Http\Controllers\CryptoPaymentController::class)
                ->name('payments.crypto.pay');

// You you need to create your own callback controller and define the route below
// The callback route should be a publicly accessible route with no auth
// However, you may also exclude the route from CSRF Protection by adding their URIs to the $except property of the VerifyCsrfToken middleware.
Route::post('/payments/crypto/callback', [App\Http\Controllers\Payment\PaymentController::class, 'callback'])
                ->withoutMiddleware(['web', 'auth']);

Learn more about The Callback Route below.

Define the public key and private keys in environment file

Defined the created payment box's public key and private key for the various coins in your .env file.

GOURL_PAYMENTBOX_BITCOIN_PUBLIC_KEY
GOURL_PAYMENTBOX_BITCOIN_PRIVATE_KEY

GOURL_PAYMENTBOX_BITCOINCASH_PUBLIC_KEY
GOURL_PAYMENTBOX_BITCOINCASH_PRIVATE_KEY

Config Options

See the published config/laravel-crypto-payment-gateway.php for available options to customize the payment box like changing logo, box_template, box_template_options and other configuration options.

Usage

Payment Data Submission

The payment data can be submitted in the following ways;

• Form Submit
• AJAX Request
• Session Redirect (through controller, Livewire component or anywhere in your application)

Which ever method data field amount in BTC or amountUSD need to be sent, both cannot be used. And optional data fields userID, orderID (if you want to reference the data to any model in app e.g Product model) and redirect (a url you want to redirect to once payment is received).

Usage with Form Submit

<form id="payment-form" method="post" action="{{ route('payments.crypto.pay) }}">
  @csrf
  <input type="text" name="amountUSD" placeholder="Amount">
    <input type="hidden" name="userID" value="{{ Auth::user()->id }}">
  <input type="hidden" name="orderID" value="1">
  <input type="hidden" name="redirect" value="{{ url()->full() }}">
  <button type="submit">Pay</button>
</form>       

Usage with AJAX Request

axios({
  method: "post",
  url: "/payments/crypto/pay",
  data: {
    amountUSD: 20.50,
    userID: 1,
    orderID: 101,
    redirect: 'https://domain.com/redirect-url',
  },
  headers: {
    'Accept': 'application/json'
    // Ensure you include your TOKEN as well
  },
})
  .then(function (response) {
    // The url is available in `data` key of the json response:
    // {
    //   status: true,
    //   message: 'Request successful.',
    //   data: 'https://your-domain.com/payments/crypto/pay?cryptopsid=some-unique-token-string'
    // }
    if (response.data.status === true) {
      const paymentUrl = response.data.data
      window.location = paymentUrl
    }
  })
  .catch(function (response) {
    //handle error
    console.log(response);
  });

Usage with Session Redirect (through controller, Livewire component or anywhere in your application)

You need to ensure you validate your data before sending to the payment gateway

// This could be in a controller method or livewire component method
use Victorybiz\LaravelCryptoPaymentGateway\LaravelCryptoPaymentGateway;

$payment_url = LaravelCryptoPaymentGateway::startPaymentSession([
    'amountUSD' => $validatedData['amount'], // OR 'amount' when sending BTC value
    'orderID' => $product->id,
    'userID' => Auth::user()->id,
    'redirect' => url()->full(),
]);
// redirect to the payment page
redirect()->to($payment_url);

The Callback

When a user has made a payment, the GoUrl.io's server will send payment data using HTTP POST method on your callback url specified in field Callback URL of your crypto payment box.

Callback Controller

Create a PaymentController and call instance of Laravel Crypto Payment Gateway's callback method.

<?php

namespace App\Http\Controllers\Payment;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Victorybiz\LaravelCryptoPaymentGateway\LaravelCryptoPaymentGateway;

class PaymentController extends Controller
{
    /**
     * Cryptobox callback.
     */
    public function callback(Request $request)
    {   
      return LaravelCryptoPaymentGateway::callback();
    }
}

Callback Route

Define the callback route to the created controller, the callback route should be a publicly accessible route with no auth. However, you may also exclude the route from CSRF Protection by adding their URIs to the $except property of the VerifyCsrfToken middleware. If you use Cloudflare & Mod_Security & other CDN services, Click Here to view the GoUrl.io's server IPs you need to add in Whitelist.

// routes/web.php
 
Route::post('/payments/crypto/callback', [App\Http\Controllers\Payment\PaymentController::class, 'callback'])
                ->withoutMiddleware(['web', 'auth']);

IPN (Instant Payment Notification)

Once the GoUrl.io's Cryptobox Class finished processing the received callback behind the scene, then it make a call to a cryptobox_new_payment(...) function which allows you to define your processing after payment. To hook on to this function to handle IPN (Instant payment notification) with your custom processing like sending email notifications and giving value to the user once payment is confirmed, create a static class method. This can be a static class method defined anywhere in your application. Preferably you can just define the static method in the same PaymentController for easy code management.

<?php

namespace App\Http\Controllers\Payment;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Victorybiz\LaravelCryptoPaymentGateway\LaravelCryptoPaymentGateway;

class PaymentController extends Controller
{
    //...
    
    /**
     * Cryptobox IPN Example
     * 
     * @param \Victorybiz\LaravelCryptoPaymentGateway\Models\CryptoPaymentModel $cryptoPaymentModel
     * @param array $payment_details
     * @param string $box_status
     * @return bool
     */
    public static function ipn($cryptoPaymentModel, $payment_details, $box_status)
    {            
        if ($cryptoPaymentModel) {  
            /*
            // ADD YOUR CODE HERE
            // ------------------
            // For example, you have a model `UserOrder`, you can create new Bitcoin payment record to this model
            $userOrder = UserOrder::where('payment_id', $cryptoPaymentModel->paymentID)->first();
            if (!$userOrder) 
            {
                UserOrder::create([
                    'payment_id' => $cryptoPaymentModel->paymentID,
                    'user_id'    => $payment_details["user"],
                    'order_id'   => $payment_details["order"],
                    'amount'     => floatval($payment_details["amount"]),
                    'amountusd'  => floatval($payment_details["amountusd"]),
                    'coinlabel'  => $payment_details["coinlabel"],
                    'txconfirmed'  => $payment_details["confirmed"],
                    'status'     => $payment_details["status"],
                ]);
            }
            // ------------------

            // Received second IPN notification (optional) - Bitcoin payment confirmed (6+ transaction confirmations)
            if ($userOrder && $box_status == "cryptobox_updated")
            {
                $userOrder->txconfirmed = $payment_details["confirmed"];
                $userOrder->save();
            }
            // ------------------
            */

            // Onetime action when payment confirmed (6+ transaction confirmations)
            if (!$cryptoPaymentModel->processed && $payment_details["confirmed"])
            {
                // Add your custom logic here to give value to the user.
        
                // ------------------
                // set the status of the payment to processed
                // $cryptoPaymentModel->setStatusAsProcessed();

                // ------------------
                // Add logic to send notification of confirmed/processed payment to the user if any
            }
            
        }
        return true;
    }
}

Then update the published config/laravel-crypto-payment-gateway.php and set value for hook_ipn key to hook IPN (Instant Payment Notification) function to the static class method defined above. config file

// config/laravel-crypto-payment-gateway.php

/**
 * Hook IPN (Instant payment notification) to the following static class method.
 * In this static class method, you can  add your custom logic and give value to the user once your confirmed payment box status.
 * You can also add payment notification logic. 
 * This can be a static class method defined anywhere in your application.
 * This can also be static method/action defined in controller class but route must not be defined for the action.
 * 
 * The Static Method Definition in your class:
 * @param \Victorybiz\LaravelCryptoPaymentGateway\Models\CryptoPaymentModel $cryptoPaymentModel
 * @param array $payment_details
 * @param string $box_status
 * @return bool
 * public static function ipn($cryptoPaymentModel, $payment_details, $box_status)
 * {
 *  // Add your custom logic here.
 *  return true;
 * }
 * 
 * Example: [\Victorybiz\LaravelCryptoPaymentGateway\Http\Controllers\CryptoPaymentController::class, 'ipn']
 */
'hook_ipn' => [\App\Http\Controllers\Payment\PaymentController, 'ipn'],

Eloquent Model for crypto_payments table

This package provide eloquent model for the crypto_payments.

use Victorybiz\LaravelCryptoPaymentGateway\Models\CryptoPaymentModel;

$cryptoPayment = CryptoPaymentModel::find($paymentID);

$cryptoPayment = CryptoPaymentModel::where('paymentID', $paymentID);

$processedCryptoPayment = CryptoPaymentModel::where('processed', true);

Advanced Usage

Instance of GoUrl.io PHP Class API (cryptobox.class.php)

This package provide access to instance of the core GoUrl.io's cryptobox.class.php which this package uses under the hood.

use Victorybiz\LaravelCryptoPaymentGateway\LaravelCryptoPaymentGateway;

$laravelCryptoPaymentGateway = new LaravelCryptoPaymentGateway;

$cryptobox = $laravelCryptoPaymentGateway->getCryptobox($options = []);

$payment_history = $cryptobox->payment_history($boxID = "", $orderID = "", $userID = "", $countryID = "", $boxType = "", $period = "7 DAY");

Click Here to learn more about GoUrl.io PHP Class API and the available methods.

Resources

The following packages was put together to makeup this seamless package.

• GoUrl.io Website
• GoUrl.io's CryptoAPI Payment Gateway Repository
• PHP Class API Doc
• TailwindCSS
• AlpineJS
• Alpine Clipboard
• Alpine Tooltip
• tc-lib-barcode

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Victory Osayi Airuoyuwa
• All Contributors

License

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

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.