Package: payments

Source: api/packages/payments · imported version 0.2.20. The sections after the README are extracted from the code on every docs build.

README

Purpose

This package lets you create Payments and process them using integrations with external payment providers (gateways).

Dependencies

• Stripe integration is based on league/omnipay and omnipay/stripe packages.
• Przelewy24 integration is based on mnastalski/przelewy24-php package.
• Optional integration with ulams/settings package enables changing payment gateway api keys & secrets using Settings API (and Admin Panel).

Installation

• composer require ulams/payments
• php artisan migrate
• php artisan db:seed --class="Ulams\Cart\Database\Seeders\CartPermissionSeeder"

Usage

Facades

Payments Facade

Use Ulams\Payments\Facades\Payments for starting payment processing. You can create PaymentProcessor` either from a model using Payable trait or from precreated Payment object.

use Ulams\Cart\Models\Cart;
use Ulams\Payments\Dtos\PaymentMethodDto;
use Ulams\Payments\Facades\Payments;

$payable = Cart::find($id); // Cart must implement Payable interface and use Payable trait
$paymentMethodDto = PaymentMethodDto::instantiateFromRequest($request);
$processor = Payments::processPayment($payable);
$processor->purchase($paymentMethodDto); // will emit PaymentPaid event on success
if($payment->status->is(PaymentStatus::PAID)){
    // ...
}

PaymentGateway Facade

With Ulams\Payments\Facades\PaymentGateway you can call payment provider gateways directly.

For existing payment you can for example do:

use Ulams\Payments\Dtos\PaymentMethodDto;
use Ulams\Payments\Facades\PaymentGateway;
use Ulams\Payments\Models\Payment;

$payment = Payment::find($id);
$paymentMethodDto = PaymentMethodDto::instantiateFromRequest($request);
$paymentDto = PaymentDto::instantiateFromPayment($payment); // or you can create it manually
PaymentGateway::purchase($paymentDto, $paymentMethodDto); // will use default payment driver

Important: This will not save Payment object.

To use specific driver, you can call

PaymentGateway::driver('stripe')->purchase($paymentDto, $paymentMethodDto);

Available payment drivers

• stripe (using Stripe Payment Intent)
• free
• przelewy24
• TODO: stripe-checkout

Payable Trait & Interface

Payable trait and interface are the core of this package, enabling simplified calling of PaymentsService and GatewayManager. When you include it in your model that represents a Payable (for example Cart or Order or Product) you can begin payment processing for that Payable by calling $payable->process() which calls Payments::processPayable($this) and automatically creates a Payment and returns a PaymentProcessor instance for that Payment.

Ulams\Cart package uses this trait and interface in Ulams\Cart\Models\Order.

Payment Processor

Ulams\Payments\Entities\PaymentProcessor is a special class which wraps around Payment and contains functionality related to processing that payment, for example generating links to payment gateways, automatically setting payment status after purchase, emiting events related to payment status, etc.

use Ulams\Payments\Dtos\PaymentMethodDto;
use Ulams\Payments\Entities\PaymentProcessor;
use Ulams\Payments\Models\Payment;

$payment = Payment::find($id);
$paymentMethodDto = PaymentMethodDto::instantiateFromRequest($request);
$processor = new PaymentProcessor($payment); // instead of using Payments facade
$processor->purchase($paymentMethodDto);

PaymentProcessor automatically selects free driver when payment amount equals 0.

Payment Model

This package defines a Ulams\Payments\Models\Payment which contains all data abount given payment required for payment gateways to work.

Endpoints

All the endpoints are defined in .

Tests

Run ./vendor/bin/phpunit to run tests. See tests/Mocks/Payable as an example how a Payable is defined.

Test details:

Events

• Ulams\Payments\Events\PaymentCancelled - - emited after payment processing is cancelled (by user action or possibly by timeout sent from payment gateway)
• Ulams\Payments\Events\PaymentFailed - emited after payment has failed (payment gateway returns error)
• Ulams\Payments\Events\PaymentRegistered - emited when new Payment is created
• Ulams\Payments\Events\PaymentSuccess - emited when payment gateway returns success

Listeners

No Listeners are defined in this package.

How to use this package on Frontend

Admin Panel

Left Menu

List of Payments

Permissions

Permissions are defined in Enum and seeded in Seeder.

Roadmap. Todo. Troubleshooting

• ???

More documentation in the package

• api/packages/payments/ADMIN.md
• api/packages/payments/docs/list.png
• api/packages/payments/docs/menu.png

API endpoints

Method	Path	Auth	Action
GET	/api/payments-gateways		GatewayController@index
ANY	/api/payments-gateways/callback/{payment}		GatewayController@callback
POST	/api/payments-gateways/webhook/stripe		GatewayController@stripeWebhook
ANY	/api/payments-gateways/callback/refund/{payment}		GatewayController@callbackRefund
GET	/api/admin/payments/export	yes	PaymentsAdminController@export
GET	/api/admin/payments/{payment}	yes	PaymentsAdminController@show
GET	/api/admin/payments	yes	PaymentsAdminController@search
GET	/api/payments/{payment}		PaymentsController@show
GET	/api/payments		PaymentsController@search

Permissions

Permission	Seeded for roles	Constant
payment_list	admin	PaymentsPermissionsEnum::PAYMENTS_LIST
payment_read	admin	PaymentsPermissionsEnum::PAYMENTS_READ
payment_export	admin	PaymentsPermissionsEnum::PAYMENTS_EXPORT

Settings

Registered with AdministrableConfig::registerConfig (editable in the admin panel under Configuration → Settings).

Key	Rules	Public	Read-only
ulams_payments.drivers.stripe.enabled	required, boolean	yes
ulams_payments.drivers.stripe.secret_key	required, string	no
ulams_payments.drivers.stripe.publishable_key	required, string	yes
ulams_payments.drivers.stripe.webhook_secret	nullable, string	no
ulams_payments.drivers.przelewy24.enabled	required, boolean	yes
ulams_payments.drivers.przelewy24.live	required, boolean	no
ulams_payments.drivers.przelewy24.merchant_id	required, string	no
ulams_payments.drivers.przelewy24.pos_id	required, string	no
ulams_payments.drivers.przelewy24.api_key	required, string	no
ulams_payments.drivers.przelewy24.crc	required, string	no
ulams_payments.drivers.revenuecat.enabled	required, boolean	yes
ulams_payments.default_gateway	required, string, in:Free,Stripe,Przelewy24	yes
ulams_payments.default_currency	required, string, in: . implode(,, Currency::getValues())	yes

Events

Event	Description	Notification templates
PaymentCancelled		Email
PaymentFailed		Email
PaymentRegistered		Email
PaymentSuccess		Email

Notification templates registered here

None.

Artisan commands

None.

Scheduled jobs

None.

Environment variables read

PAYMENTS_DEFAULT_CURRENCY, PAYMENTS_DEFAULT_GATEWAY, PAYMENTS_PRZELEWY24_API_KEY, PAYMENTS_PRZELEWY24_CRC, PAYMENTS_PRZELEWY24_LIVE, PAYMENTS_PRZELEWY24_MERCHANT_ID, PAYMENTS_PRZELEWY24_POS_ID, PAYMENTS_REVENUECAT_ENABLED, PAYMENTS_REVENUECAT_RECEIPT_VERIFIER, PAYMENTS_STRIPE_API_BASE, PAYMENTS_STRIPE_PUBLISHABLE_KEY, PAYMENTS_STRIPE_SECRET_KEY, PAYMENTS_STRIPE_WEBHOOK_SECRET, PAYMENTS_STRIPE_WEBHOOK_TOLERANCE