TomatoPHP
Join CommunityGitHubDiscord
  • 🚀Overview
  • 🏅Support
  • 🤝Contributing
  • 🛣️Screenshots
  • Get Started
    • 🔥Environment Setup
      • 💿Configuring the server
      • 📡Install Valet
      • 🎟️Install PHPMyAdmin
    • 🚀Install
    • ✨Start Your First CRUD
  • Tomato Admin
    • 🚀Get Started
    • 🧠Install
    • 🛗Generate CRUD
    • 👓Slots
    • 🌉Widgets
    • 📖Menus
    • 🔁Requests
      • 🔁Index Request
      • 🔁JSON Request
      • 🔁Get Request
      • 🔁Store Request
      • 🔁Update Request
      • 🔁Destroy Request
    • 🎹Inputs
      • 🔆Rich Text Editor
      • 📞Phone Editor
      • 🖌️Color Switcher
      • 🔁Inputs Repeater
      • 💧Draggable
      • 👨‍💻Code Editor
      • ⚡Select Input
      • 🔚Submit
      • 🧾Items
      • 🔍Search
      • 🚁Icon
    • 🗜️Components
      • 🔗Relation Manager
      • 🧊Container
      • 👁️View Row
      • 🌉Widget
      • 🔘Button
      • 📖Menu
      • 👾Tooltip
      • ©️©️ Clipboard
      • 🛣️Slider
      • ℹ️Action Buttons
      • 🍅Application Logo
      • 🔽Dropdown
      • ⏸️Paginator
    • 📑Table
      • ✅Bulk Actions
      • 🗄️Filters
      • 🦘Slots
    • 🔓Jetstream & Fortify
    • 🆕Upgrade
  • Tomato PHP
    • 🚀Get Started
    • 🎹Use
  • Plugins
    • 🔌Get Started
    • 🏗️Create New Plugin
    • 🔓Tomato Roles
      • 📐Use
      • 🔏Developer Gate
      • 🏗️Register Permission
      • 💽Config
    • 🌎Tomato Locations
      • 🔁APIs
    • ⚙️Tomato Settings
      • 📐Use
      • 💽Config
    • 🔔Tomato Notifications
      • 📐Use
      • 🏗️Notification Service
      • 💽Config
      • 🔁APIs
    • 🔷Tomato Category
      • 📐Use
      • 💽Config
      • 🔁APIs
    • ✨Tomato Forms
      • 📐Use
      • 💽Config
      • 🔁APIs
    • 📖Tomato Menus
      • 📐Use
      • 💽Config
    • 👨‍💼Tomato CRM
      • 📐Use
      • 🏗️Auth Builder
      • 🔥Events
      • 💽Config
      • 🔁APIs
    • 💳Tomato Wallet
      • 📐Use
      • 🗂️Payment Methods
      • 💽Config
      • 🔁APIs
    • 📃Tomato CMS
      • 📐Use
      • 💽Config
    • 🎧Tomato Support
      • 📐Use
      • 💽Config
      • 🔁APIs
    • 👜Tomato Products
      • 💿Config
      • 🌆Screenshots
    • 💯Tomato Coupons
      • 💿Config
      • 🌆Screenshots
    • 🚀Tomato Orders
      • 💿Config
      • 🌆Screenshots
    • 🛍️Tomato Ecommerce
      • 🎭Install E-commerce Theme
      • 💿Config
      • 🌆Screenshots
    • 🚛Tomato Inventory
      • 💿Config
    • 🧾Tomato POS
      • 💿Config
    • 📄Tomato Invoices
      • 💿Config
    • 🏬Tomato Subscription
      • 📐Use
      • 💽Config
    • 🧪Tomato Dusk
      • 📐Use
      • 💿Config
      • 🌆Screenshots
    • ⚔️Tomato Chat
      • 🏗️Setup
      • 📐Use
      • 💽Config
    • 📱Tomato Flutter
      • 📐Use
      • 🧲Generate CRUD
      • 🚀Change Endpoint
      • ⏩Tomato Froms
      • 🛣️Screenshots
    • 🏗️Tomato Builder
      • 🧠Install
      • 🖍️Use
      • 🌆Screenshots
      • 💿Config
    • 🏗️Tomato Sections
      • 💿Config
    • 🎭Tomato Themes
      • 🏂Create New Theme
      • 🏗️Theme Builder
      • 🛍️Install E-commerce Theme
      • 💿Config
    • 📠Tomato Eddy
      • 💿Config
    • 👨‍💻Tomato User Activities
      • 💿Config
    • 👨‍💼Tomato PMS
    • ✅Tomato Tasks
    • ⌛Tomato Timer
    • ✈️Tomato API
    • 🚦Tomato Figma
    • 🌟Tomato SaaS
    • 🔤Tomato Translations
    • 👨‍💻Tomato Artisan
    • 🎒Tomato Backup
    • 📂Tomato Browser
    • 📕Tomato Logs
  • Helpers
    • 🍕Laravel Console Helpers
    • 📽️Laravel Agora
    • 💿Laravel Package Generator
  • Filament
    • 🌎Try Plugins
    • 👨‍🏭Filament Users
      • 🛣️Screenshots
      • 🏗️Installation
      • 🛡️Integration
      • 💼Use Facade Class
      • 📢Publish Assets
    • 🌎Filament Translations
      • 🛣️Screenshots
      • 🏗️Installation
      • 🇪🇬Language Switcher
      • 👨‍💻Command Line
      • 🔧Queue
      • 🔘Buttons
      • 🤖AI Integration
      • 🌠Import & Export
      • 📢Publish Assets
    • ⚙️Filament Settings Hub
      • 🛣️Screenshots
      • 🏗️Installation
      • ▶️Usage
      • 📢Publish Assets
    • 🍔Filament Menus
      • 🏗️Installation
      • 🛣️Screenshots
      • ⏩Use as Filament Navigation
      • ⏯️Use as a Livewire Component
      • 📢Publish Assets
    • 🆎Filament Types
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Register New Type
      • 🎹Use Type Helper
      • 🔄Use Type Column
      • 📢Publish Assets
    • 🔌Filament Plugins
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • ®️®️ List your package on the plugins list
      • 📶Use Selected Module in your panel
      • 🏂Get Only Current Panel Plugins
      • 🛑Stop Auto Discover Module Resources
      • 🎸Stop Using Plugins UI
      • 📢Publish Assets
    • 🦄Filament Icons
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • 🪄Add Custom Icons
      • 📢Publish Assets
    • 🗺️Filament Locations
      • 🛣️Screenshots
      • 🏗️Installation
      • 📢Publish Assets
    • 📢Filament Alerts
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • 🔥Firebase Integration
      • 🔗Slack Integration
      • 🔗Discord Integration
      • ⚙️API
      • 📢Publish Assets
    • 🦸‍♂️Filament Accounts
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • 🎇Use Accounts as SaaS Panel
      • 🍫Use Account Column
      • 🔔Use Notifications
      • 🗺️Use Account Locations
      • 🅰️Use Filament Types
      • 🔏Use Filament Impersonate
      • 🏢How to use a builder
      • ✌️Custom validation
      • 🆕Attach New Field
      • 🎌Attach Relation
      • 🔘Attach Table Button
      • 🛁Auth Events
      • ⚙️APIs
    • 💰Filament Wallet
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • 🏁Filament Accounts Integration
      • 📢Publish Assets
    • ✨Filament Splade
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • 📢Publish Assets
    • 🔐Filament Developer Gate
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • 📢Publish Assets
    • 🏛️Filament Helpers
      • 🏗️Installation
      • ⏯️Using
    • 👨‍💻Filament Artisan
      • 🛣️Screenshots
      • 🏗️Installation
      • 🏃‍♂️Running command
      • ⚙️Configuration
      • 📢Publish Assets
    • 📂Filament Browser
      • 🛣️Screenshots
      • 🏗️Installation
      • 📢Publish Assets
    • 🔥Filament FCM
      • 🏗️Installation
      • ⏯️Usage
      • 📢Publish Assets
    • 🖊️Filament CMS
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Custom Type
      • ⏯️Custom Author Type
      • 📺Youtube Integration
      • 🏩Behance Integration
      • 🎭Theme Manager
      • 🏨Page Builder
      • 🔡Form Builder
      • 📢Publish Assets
    • 🔗Filament API
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Usage
      • 📢Publish Assets
    • 👜Filament Ecommerce
      • 🛣️Screenshots
      • 🏗️Installation
      • 🎁Use Coupon Service
      • 📢Publish Assets
    • 🔚Filament Twilio
      • 🏗️Installation
      • ⏯️Using
      • 📢Publish Assets
    • ⚔️Filament Discord
      • 🛣️Screenshot
      • 🏗️Installation
      • ⏯️Using
      • 🦸‍♂️Send to Selected User
      • ⚡Allow Discord Error Logger
      • 📢Publish Assets
    • 🆎Filament Translation Component
      • 🛣️Screenshot
      • 🏗️Installation
      • ⏯️Using
      • 📢Publish Assets
    • 📒Filament Notes
      • 🛣️Screenshot
      • 🏗️Installation
      • ⏯️Using
      • 📢Publish Assets
    • 📼Filament Media Manager
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Use Component
      • 🅰️Add Custom Type
      • 📂Allow Sub Folders
      • 🦸‍♂️Allow User Access
      • 🎇Folders API
      • 📢Publish Assets
    • 💳Filament Withdrawals
      • 🛣️Screenshots
      • 🏗️Installation
      • ⏯️Custom Author Type
      • 🔡Form Builder
      • 📢Publish Assets
    • 🧾Filament POS
      • 🌄Screenshots
      • 🏗️Installation
      • 📢Publish Assets
  • Learn
    • 🛍️Build E-Commerce
    • 🙏Task To Get Start
    • 🔴Use Github
    • 🔥Deploy Laravel App Using GitHub Actions
      • 🏯Install Cloudpanel
      • 🔓Link Cloudflare
      • 🔃Clone Repo
      • 🎇Workflow
      • 🦕Deploy Script
    • 🦄Awesome TailwindCSS
    • 💻Terminal
Powered by GitBook
On this page

Was this helpful?

Edit on GitHub
  1. Plugins
  2. Tomato Wallet

Use

PreviousTomato WalletNextPayment Methods

Last updated 1 year ago

Was this helpful?

you can start using your wallet very easily by checking these .

Start using Payments

you can create your own custom drivers if it does not exist in the list, read the Create custom drivers section.

In the config file, you can set the default driver to use for all your payments. But you can also change the driver at runtime.

Choose what gateway you would like to use in your application. Then make that as the default driver so that you don't have to specify that everywhere. But, you can also use multiple gateways in a project.

// Eg. if you want to use zarinpal.
'default' => 'zarinpal',

Then fill the credentials for that gateway in the drivers array.

'drivers' => [
    'zarinpal' => [
        // Fill in the credentials here.
        'apiPurchaseUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentRequest.json',
        'apiPaymentUrl' => 'https://www.zarinpal.com/pg/StartPay/',
        'apiVerificationUrl' => 'https://www.zarinpal.com/pg/rest/WebGate/PaymentVerification.json',
        'merchantId' => '',
        'callbackUrl' => 'http://yoursite.com/path/to',
        'description' => 'payment in '.config('app.name'),
    ],
    ...
]

your Invoice holds your payment details, so initially we'll talk about Invoice class.

Working with invoices

before doing any thing you need to use Invoice class to create an invoice.

In your code, use it like the below:

// At the top of the file.
use TomatoPHP\TomatoWallet\Invoice;
...

// Create new invoice.
$invoice = new Invoice;

// Set invoice amount.
$invoice->amount(1000);

// Add invoice details: There are 4 syntax available for this.
// 1
$invoice->detail(['detailName' => 'your detail goes here']);
// 2 
$invoice->detail('detailName','your detail goes here');
// 3
$invoice->detail(['name1' => 'detail1','name2' => 'detail2']);
// 4
$invoice->detail('detailName1','your detail1 goes here')
        ->detail('detailName2','your detail2 goes here');

available methods:

  • uuid: set the invoice's unique ID

  • getUuid: retrieve the invoice's current unique ID

  • detail: attach some custom details to the invoice

  • getDetails: retrieve all custom details

  • amount: set the invoice amount

  • getAmount: retrieve invoice amount

  • transactionId: set invoice payment transaction ID

  • getTransactionId: retrieve payment transaction id

  • via: set up a driver we use to pay the invoice

  • getDriver: retrieve the driver

Purchase invoice

In order to pay the invoice, we need the payment transaction. We purchased the invoice to retrieve the transaction id:

// At the top of the file.
use TomatoPHP\TomatoWallet\Invoice;
use TomatoPHP\TomatoWallet\Facade\Payment;
...

// Create new invoice.
$invoice = (new Invoice)->amount(1000);

// Purchase the given invoice.
Payment::purchase($invoice,function($driver, $transactionId) {
	// We can store $transactionId in database.
});

// Purchase method accepts a callback function.
Payment::purchase($invoice, function($driver, $transactionId) {
    // We can store $transactionId in database.
});

// You can specify callbackUrl
Payment::callbackUrl('http://yoursite.com/verify')->purchase(
    $invoice, 
    function($driver, $transactionId) {
    	// We can store $transactionId in database.
	}
);

Pay Invoice

After purchasing the invoice, we can redirect the user to the bank payment page:

// At the top of the file.
use TomatoPHP\TomatoWallet\Invoice;
use TomatoPHP\TomatoWallet\Facade\Payment;
...

// Create new invoice.
$invoice = (new Invoice)->amount(1000);
// Purchase and pay the given invoice.
// You should use return statement to redirect user to the bank page.
return Payment::purchase($invoice, function($driver, $transactionId) {
    // Store transactionId in database as we need it to verify payment in the future.
})->pay()->render();

// Do all things together in a single line.
return Payment::purchase(
    (new Invoice)->amount(1000), 
    function($driver, $transactionId) {
    	// Store transactionId in database.
        // We need the transactionId to verify payment in the future.
	}
)->pay()->render();

// Retrieve json format of Redirection (in this case you can handle redirection to bank gateway)
return Payment::purchase(
    (new Invoice)->amount(1000), 
    function($driver, $transactionId) {
    	// Store transactionId in database.
        // We need the transactionId to verify payment in the future.
	}
)->pay()->toJson();

Verify payment

When the user has completed the payment, the bank redirects them to your website, then you need to verify your payment in order to ensure the invoice has been paid.

// At the top of the file.
use TomatoPHP\TomatoWallet\Facade\Payment;
use TomatoPHP\TomatoWallet\Exceptions\InvalidPaymentException;
...

// You need to verify the payment to ensure the invoice has been paid successfully.
// We use transaction id to verify payments
// It is a good practice to add invoice amount as well.
try {
	$receipt = Payment::amount(1000)->transactionId($transaction_id)->verify();

    // You can show payment referenceId to the user.
    echo $receipt->getReferenceId();

    ...
} catch (InvalidPaymentException $exception) {
    /**
    	when payment is not verified, it will throw an exception.
    	We can catch the exception to handle invalid payments.
    	getMessage method, returns a suitable message that can be used in user interface.
    **/
    echo $exception->getMessage();
}

Useful methods

  • callbackUrl: can be used to change callbackUrl on the runtime.

    // At the top of the file.
    use TomatoPHP\TomatoWallet\Invoice;
    use TomatoPHP\TomatoWallet\Facade\Payment;
    ...
    
    // Create new invoice.
    $invoice = (new Invoice)->amount(1000);
    
    // Purchase the given invoice.
    Payment::callbackUrl($url)->purchase(
        $invoice, 
        function($driver, $transactionId) {
        // We can store $transactionId in database.
    	}
    );
  • amount: you can set the invoice amount directly

    // At the top of the file.
    use TomatoPHP\TomatoWallet\Invoice;
    use TomatoPHP\TomatoWallet\Facade\Payment;
    ...
    
    // Purchase (we set invoice to null).
    Payment::callbackUrl($url)->amount(1000)->purchase(
        null, 
        function($driver, $transactionId) {
        // We can store $transactionId in database.
    	}
    );
  • via: change driver on the fly

    // At the top of the file.
    use TomatoPHP\TomatoWallet\Invoice;
    use TomatoPHP\TomatoWallet\Facade\Payment;
    ...
    
    // Create new invoice.
    $invoice = (new Invoice)->amount(1000);
    
    // Purchase the given invoice.
    Payment::via('driverName')->purchase(
        $invoice, 
        function($driver, $transactionId) {
        // We can store $transactionId in database.
    	}
    );
  • config: set driver configs on the fly

    // At the top of the file.
    use TomatoPHP\TomatoWallet\Invoice;
    use TomatoPHP\TomatoWallet\Facade\Payment;
    ...
    
    // Create new invoice.
    $invoice = (new Invoice)->amount(1000);
    
    // Purchase the given invoice with custom driver configs.
    Payment::config('mechandId', 'your mechand id')->purchase(
        $invoice,
        function($driver, $transactionId) {
        // We can store $transactionId in database.
    	}
    );
    
    // Also we can change multiple configs at the same time.
    Payment::config(['key1' => 'value1', 'key2' => 'value2'])->purchase(
        $invoice,
        function($driver, $transactionId) {
        // We can store $transactionId in database.
    	}
    );

Create custom drivers:

First you have to add the name of your driver, in the drivers array and also you can specify any config parameters you want.

'drivers' => [
    'zarinpal' => [...],
    'my_driver' => [
        ... // Your Config Params here.
    ]
]

Now you have to create a Driver Map Class that will be used to pay invoices. In your driver, You just have to extend TomatoPHP\TomatoWallet\Abstracts\Driver.

Eg. You created a class: App\Packages\PaymentDriver\MyDriver.

namespace App\Packages\PaymentDriver;

use TomatoPHP\TomatoWallet\Abstracts\Driver;
use TomatoPHP\TomatoWallet\Exceptions\InvalidPaymentException;
use TomatoPHP\TomatoWallet\{Contracts\ReceiptInterface, Invoice, Receipt};

class MyDriver extends Driver
{
    protected $invoice; // Invoice.

    protected $settings; // Driver settings.

    public function __construct(Invoice $invoice, $settings)
    {
        $this->invoice($invoice); // Set the invoice.
        $this->settings = (object) $settings; // Set settings.
    }

    // Purchase the invoice, save its transactionId and finaly return it.
    public function purchase() {
        // Request for a payment transaction id.
        ...
            
        $this->invoice->transactionId($transId);
        
        return $transId;
    }
    
    // Redirect into bank using transactionId, to complete the payment.
    public function pay() {
        // It is better to set bankApiUrl in config/payment.php and retrieve it here:
        $bankUrl = $this->settings->bankApiUrl; // bankApiUrl is the config name.

        // Prepare payment url.
        $payUrl = $bankUrl.$this->invoice->getTransactionId();

        // Redirect to the bank.
        return redirect()->to($payUrl);
    }
    
    // Verify the payment (we must verify to ensure that user has paid the invoice).
    public function verify(): ReceiptInterface {
        $verifyPayment = $this->settings->verifyApiUrl;
        
        $verifyUrl = $verifyPayment.$this->invoice->getTransactionId();
        
        ...
        
        /**
			Then we send a request to $verifyUrl and if payment is not valid we throw an InvalidPaymentException with a suitable message.
        **/
        throw new InvalidPaymentException('a suitable message');
        
        /**
        	We create a receipt for this payment if everything goes normally.
        **/
        return new Receipt('driverName', 'payment_receipt_number');
    }
}

Once you create that class you have to specify it in the payment.php config file map section.

'map' => [
    ...
    'my_driver' => App\Packages\PaymentDriver\MyDriver::class,
]

Note:- You have to make sure that the key of the map array is identical to the key of the drivers array.

Events

You can listen for 2 events

  • InvoicePurchasedEvent: Occurs when an invoice is purchased (after purchasing invoice is done successfully).

  • InvoiceVerifiedEvent: This occurs when an invoice is verified successfully.

💳
📐
docs