cashier-provider/core

Cashier provides an expressive, fluent interface to manage billing services.

v3.5.1 2022-10-25 15:37 UTC

Requires

• php: ^7.3 || ^8.0
• ext-json: *
• doctrine/dbal: ^2.6 || ^3.0
• dragon-code/contracts: ^2.18
• dragon-code/laravel-cache: ^2.12
• dragon-code/laravel-support: ^3.3.2
• dragon-code/simple-dto: ^2.2
• dragon-code/support: ^5.2
• fig/http-message-util: ^1.1
• guzzlehttp/guzzle: ^6.5 || ^7.0
• illuminate/broadcasting: ^6.0 || ^7.0 || ^8.0 || ^9.0
• illuminate/console: ^6.0 || ^7.0 || ^8.0 || ^9.0
• illuminate/contracts: ^6.0 || ^7.0 || ^8.0 || ^9.0
• illuminate/database: ^6.0 || ^7.0 || ^8.0 || ^9.0
• illuminate/queue: ^6.0 || ^7.0 || ^8.0 || ^9.0
• illuminate/support: ^6.0 || ^7.0 || ^8.0 || ^9.0
• lmc/http-constants: ^1.2
• psr/http-message: ^1.0
• ramsey/uuid: ^3.7 || ^4.0
• symfony/http-kernel: ^4.0 || ^5.0 || ^6.0

Requires (Dev)

• orchestra/testbench: ^4.0 || ^5.0 || ^6.0 || ^7.0
• phpunit/phpunit: ^9.0
• symfony/var-dumper: ^4.0 || ^5.0 || ^6.0

MIT

• Andrey Helldar

• payments
• Bank
• billing
• cashier

README

Cashier provides an expressive, fluent interface to manage billing services.

Installation

Note

Drivers will usually automatically install the correct Cashier Provider Core version, but you can do this manually.

To get the latest version of Cashier Provider Core, simply require the project using Composer:

$ composer require cashier-provider/core

Or manually update require block of composer.json and run composer update.

{
    "require": {
        "cashier-provider/core": "^3.0"
    }
}

You should publish the config file and migrations with:

php artisan vendor:publish --provider="CashierProvider\Core\ServiceProvider"

Further, if necessary, edit the migration file copied to your application and run the command to apply migrations:

php artisan migrate

Upgrade from andrey-helldar/cashier

For application

1. Replace andrey-helldar/cashier with cashier-provider/core in the composer.json file;
2. In the config/cashier.php file replace the Helldar\Cashier namespace with CashierProvider\Core.
3. Call the composer update command.

For driver developers

1. Replace andrey-helldar/cashier with cashier-provider/core in the composer.json file;
2. Replace the Helldar\CashierDriver namespace with CashierProvider in all files.
3. Replace the Helldar\Cashier namespace with CashierProvider\Core in all files.
4. Call the composer update command.

Using

Cashier allows you to connect any payment driver compatible with your application.

Depending on the type of payment, Cashier will automatically call the required driver to work with the bank's API.

Configuration

Before starting, edit the config/cashier.php file:

use App\Models\Payment as Model;
use CashierProvider\Core\Constants\Attributes;
use CashierProvider\Core\Constants\Status;

return [
    'payment' => [

        // Please provide a link to the payment model.
        'model' => App\Models\Payment::class,

        // Specify the field names for the payment types based on which
        // the required driver will be loaded, the status identifier and
        // the entry creation date fields.
        'attributes' => [
            Attributes::TYPE => 'type_id',

            Attributes::STATUS => 'status_id',

            Attributes::CREATED_AT => 'created_at',
        ],

        // Indicate the correspondence of statuses in your system.
        // Values can be either integer or string.
        'statuses' => [
            Status::NEW => Model::STATUS_NEW,

            Status::SUCCESS => Model::STATUS_SUCCESS,

            Status::FAILED => Model::STATUS_FAILED,

            Status::REFUND => Model::STATUS_REFUND,

            Status::WAIT_REFUND => Model::STATUS_WAIT_REFUND,
        ],

        // Here you need to specify the name of the drivers called
        // for the payment types.
        'map' => [
            Model::PAYMENT_TYPE_QR_SBER => 'driver_name',
        ],
    ],

    // This parameter determines in which queue workers will be sent for
    // requests to banks.
    'queue' => [

        // This value indicates which queue service the jobs will fall into.
        // Here you may define a default connection.
        'connection' => env('QUEUE_CONNECTION'),

        // This value specifies the names of the queue into which the task will
        // be placed.
        'names' => [
            'start' => env('CASHIER_QUEUE'),
            'check' => env('CASHIER_QUEUE'),
            'refund' => env('CASHIER_QUEUE'),
        ],
    ],

    // This parameter defines the parameters for automatic refunds.
    'auto_refund' => [

        // This setting determines whether you want to issue an automatic refund
        // of payments.
        'enabled' => env('CASHIER_AUTO_REFUND_ENABLED', false),
    ],

    // This setting defines the list of drivers for the implementation of
    // payments.
    'drivers' => [
        'driver_name' => [

            // Here you need to fill in the data of the connected payment driver
            // Connection information is usually found in the driver documentation.

        ]
    ]
];

Using Trait

Add the necessary trait to your Payment model:

namespace App\Models;

use CashierProvider\Core\Concerns\Casheable;
use Illuminate\Database\Eloquent\Model;

class Payment extends Model
{
    use Casheable;
}

Cron Commands

You need to register a call to the console command to periodically start checking payment statuses.

Add a call to app/Console/Kernel.php file:

use Illuminate\Console\Scheduling\Schedule;

protected function schedule(Schedule $schedule)
{
    $schedule->command('cashier:check')->withoutOverlapping()->everyThirtyMinutes();
    $schedule->command('cashier:refund')->withoutOverlapping()->daily();
}

• cashier:check - Launching a re-verification of payments with a long processing cycle. Payments created for the previous day and earlier will be checked 1 time per hour.
• cashier:refund - Launching the command to check payments for refunds.

You can specify any start time for the cashier:check command, but we recommend using the call every thirty minutes.

Note: we do not recommend calling the command every 15 minutes or more often - this can fill up the task queue and delay the processing of new items.

Queue Handler

If your application uses a queue handler (we hope you are using it), then you will need to add configuration to it.

This must be done if you give it your connection and names.

For example:

[program:queue-payments-start]
process_name = %(process_num)02d
command = php /var/www/artisan queue:work database --queue=payments_start --tries=100
autostart = true
autorestart = true
numprocs = 4
user = www-data
redirect_stderr = true
stdout_logfile = /var/www/storage/logs/queue-payments-start.log

[program:queue-payments-check]
process_name = %(process_num)02d
command = php /var/www/artisan queue:work database --queue=payments_check --tries=100
autostart = true
autorestart = true
numprocs = 4
user = www-data
redirect_stderr = true
stdout_logfile = /var/www/storage/logs/queue-payments-check.log

[program:queue-payments-refund]
process_name = %(process_num)02d
command = php /var/www/artisan queue:work database --queue=payments_refund --tries=100
autostart = true
autorestart = true
numprocs = 1
user = www-data
redirect_stderr = true
stdout_logfile = /var/www/storage/logs/queue-payments-refund.log

Manual

use App\Models\Payment;
use CashierProvider\Core\Services\Jobs;

$model = Payment::findOrfail(1234);

$jobs = Jobs::make($model);

$jobs->start();
$jobs->check();
$jobs->refund();
$jobs->retry();

Drivers

Available

Driver	Description
cashier-provider/cash	Driver for managing cash payments in the Cashier Provider ecosystem
cashier-provider/sber-qr	Driver for payment with QR codes via Sber
cashier-provider/tinkoff-qr	Driver for payment with QR codes via Tinkoff
cashier-provider/tinkoff-online	Driver for online payments via Tinkoff

Authorization drivers

Driver	Description
cashier-provider/sber-auth	Sber Cashier Authorization Driver
cashier-provider/tinkoff-auth	Tinkoff Cashier Authorization Driver

Development

Note

You can join our team, create a driver repository and maintain it.

Create main classes with the following inheritance:

Class	Extends	Description
Driver	CashierProvider\Core\Services\Driver	Main driver file. Contains information on exchanging information with the bank via the API.
Exceptions\Manager	CashierProvider\Core\Exceptions\Manager	Error handling manager. Contains information about error codes returned from the bank.
Helpers\Statuses	CashierProvider\Core\Services\Statuses	Types of statuses. Groups the statuses returned by the bank by type.
Resources\Details	CashierProvider\Core\Resources\Details	Details cast. Contains information for working with the bank. For example, in the cashier-provider/sber-qr driver, it contains a link to generate a QR code. In your driver, you are free to specify the methods you need.
Requests\Create	CashierProvider\Core\Http\Request	Request to the bank to initiate a payment session.
Requests\Status	CashierProvider\Core\Http\Request	Request to the bank to check the status of the payment.
Requests\Cancel	CashierProvider\Core\Http\Request	Request to the bank to cancel the payment and return the funds to the client if he has already paid for the services.
Responses\Created, Responses\Refund, Responses\Status	CashierProvider\Core\Http\Response	Classes for processing responses from the bank.

namespace CashierProvider\BankName\BankTechnology;

use CashierProvider\BankName\BankTechnology\Exceptions\Manager;
use CashierProvider\BankName\BankTechnology\Helpers\Statuses;
use CashierProvider\BankName\BankTechnology\Requests\Cancel;
use CashierProvider\BankName\BankTechnology\Requests\Create;
use CashierProvider\BankName\BankTechnology\Requests\Status;
use CashierProvider\BankName\BankTechnology\Resources\Details;
use CashierProvider\BankName\BankTechnology\Responses\Created;
use CashierProvider\BankName\BankTechnology\Responses\Refund;
use CashierProvider\BankName\BankTechnology\Responses\Status as StatusResponse;
use CashierProvider\Core\Services\Driver as BaseDriver;
use Helldar\Contracts\Cashier\Http\Response;

class Driver extends BaseDriver
{
    protected $exceptions = Manager::class;

    protected $statuses = Statuses::class;

    protected $details = Details::class;

    public function start(): Response
    {
        $request = Create::make($this->model);

        return $this->request($request, Created::class);
    }

    public function check(): Response
    {
        $request = Status::make($this->model);

        return $this->request($request, StatusResponse::class);
    }

    public function refund(): Response
    {
        $request = Cancel::make($this->model);

        return $this->request($request, Refund::class);
    }
}

These are the main files for driver development.

For convenience, we have created a Cashier Provider Driver Template, on the basis of which you can create your own driver. And also the Cashier Provider Authorization Driver Template.