Download the PHP package remp/crm-payments-module without Composer

On this page you can find all versions of the php package remp/crm-payments-module. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package crm-payments-module

CRM Payments Module

Translation status @ Weblate

Installing module

We recommend using Composer for installation and update management.

Enabling module

Add installed extension to your app/config/config.neon file.

Add following commands to your scheduler (e.g. crontab) and change the path to match your deploy path:

Configuration

Data retention configuration

You can configure time before which application:cleanup deletes old repository data and column which it uses by using (in your project configuration file):

Fast charge check configuration

You can configure fast charge threshold check by adding this to your configuration:

Fast charge check is done by RecurrentPaymentsChargeCommand::validateRecurrentPayment and it prevents system from repeated charging if error occurs while charging.

Scheduled commands

For payment module to work correctly, please add execution of following commands to your scheduler. Example displays crontab usage for execution (alter paths to your deploy paths):

Service commands

Module might provide service commands to be run in the deployed environment. Mostly to handle internal changes and to prevent direct manipulation with the database. You can display required and optional arguments by using --help switch when running the command.

Payments module doesn't provide service commands.

Payment gateways

Module has a default set of supported payment gateways developed and used by us:

By default, only bank_transfer as a default payment gateway is enabled by PaymentsModule. You can enable gateways you wish to use by adding following snippet to your app/config/config.neon:

At this moment, there are several gateway implementations you can add to your CRM installation as a separate module:

Standard (one-time) payments

Standard and initial recurrent payment have common beginning of process. Once the system generates instance of new payment, user can be redirected to payment gateway for processing. Each gateway requires different set of parameters to be provided, therefore gateway is responsible for generating the redirect URL with all required parameters.

As remp/crm-payments-module is responsible only for actual payment processing, frontend flow can be managed by our remp/crm-salesfunnel-module which provides a way to create sales funnels (payment windows), aggregates statistics and displays user success page after the payment with possibility to extend it with widgets.

After the payment, user is directed back to the CRM. Each gateway provides its own URL where user is directed for payment completion processing.

If the payment is successful, payments module uses PaymentCompleteRedirectManager to determine what kind of success page the user should see. If crm-salesfunnel-module is used, user is directed to the success page registered by the module.

The flow of payment processing can be described with following diagram:

Recurrent payments

Initiating payment

If the payment uses gateway that supports recurrent payment, the initial flow is usually the same as with the regular payments. The difference comes in during processing of successful initial payment.

PaymentsModule creates new instance of recurrent payment - a profile defining when the system should charge user again, and what subscription type will the user get when charged.

Each recurrent payment instance represent a single payment that will be charged in the future. That means, that if the charge fails, system creates new recurrent payment with charge date calculated based on retry rules and stores failing information to the original recurrent payment. Similarly, if the charge was successful, new subscription is created and new recurrent payment is defined to be charged in the next period. Thanks to that the system is able to provide information about each charge attempt for whole history of user charging including the bank approval/failure code.

This is all done on backend without system requiring any kind of user interaction. This block merely explains the flow and describes the terms so when displayed in CRM admin, the reader understands the displayed data.

Automatic charges

To charge the user, add payments:charge command to your scheduler. Command doesn't handle concurrent runs - that means that it's responsibility of your scheduler to prevent multiple overlapping instances of command running at the same time. Otherwise a user could be charged twice during the same period.

We recommend using flock or some other locking tool which will prevent command to be execute while the previous instance is still running. Following is an example snippet for crontab to run the charging every 15 minutes:

Notifying expired cards

If gateway supports it, CRM fetches expiration date for each cid (effectively credit card) used to execute recurring charges. Optionally, you can add command to your scheduler that automatically stops expired recurrent payments:

When recurrent payment is stopped, Crm\PaymentsModule\Events\RecurrentPaymentCardExpiredEvent is emitted. By default, PaymentsModule checks if there's another active recurring payment for user. If there isn't, it sends NotificationEvent with card_expires_this_month template code.

If you're not satisfied with the default implementation, you can remove the default handler by unregistering it in your module definition:

Implementing new gateway

You can implement and integrate new gateways to the CRM if necessary. Based on whether you're implementing standard or recurrent gateway, you implementation should implement just Crm\PaymentsModule\Gateways\PaymentInterface or the former and Crm\PaymentsModule\Gateways\RecurrentPaymentInterface.

When implementing a gateway, we recommend extending Crm\PaymentsModule\Gateways\GatewayAbstract to avoid implementing parts which are always similar and would cause code duplication.

Once you have your implementation ready, you need to seed it into the database from within seeder in your own module (see PaymentGatewaysSeeder as an example) and register it into the application's configuration:

Then, add seeder that will insert the gateway to database. See Crm\PaymentsModule\Seeders\PaymentGatewaysSeeder as an example seeder implementation and register seeders section of CRM skeleton documentation too see how the seeders should be registered in your module.

Adding PaymentCompletedRedirectResolver

If you want to change the success page displayed to user after the payment based on any arbitrary rule - for example your gateway might want user to see some special offering or require him to enter some additional data - you can register redirect resolver to process this request. When the payment is confirmed, redirect resolver will decide (based on priority of registered resolvers) whether to redirect user to a special success page or whether a default success page (if remp/crm-salesfunnel-module is used) is sufficient.

The implementation of redirect resolver can look like this:

In the example the resolver first checked whether the redirection should happen for this particular payment - it should happen if the payment was done via foo_gateway. Then the redirectArgs method returns array of arguments, that will be 1:1 used in Nette's $this->redirect() call. User will be redirected to renderSuccess method of SalesFunnelPresenter that is implemented in our FooModule and presents user our own success page.

When the implementation is ready, resolver needs to be registered in the app/config/config.neon with the priority specifying order of execution of resolvers - higher the number, higher the priority.

Bank Transfer landing page

When bank_transfer is used, user isn't redirected to external payment gateway provider, but CRM displays payment information that user should use to complete the payment manually.

By default, this is handled by default resolver.

Create the resolver and register it with priority >10 in your config.neon.

Bank email processing

Sometimes user doesn't finish the whole payment process and quits after the payment was made but before returning to the CRM for internal payment confirmation. That scenario is always unpleasant as user doesn't have money nor subscription.

To support this scenario, we've added possibility to read bank confirmation emails and try to confirm unfinished payments based on incoming emails.

The implementation is not universal yet and you'd need to create your own command for checking the mailbox. Please take a look at two implementations that we included within this package: confirmation commands for Tatra banka and for CSOB.

Mail downloaders

By default, our mail processing commands (e.g.: ImapMailDownloader. You can replace this downloader if needed by:

  1. creating your own mail downloader which must implement MailDownloaderInterface
  2. replacing default implementation with your own in your app config neon file:

Upgrades

Payments module provides a very basic way how to handle the upgrades. The upgrades are not currently configurable and work with predefined set of rules. There are 4 type of upgrades available:

Upgrade options for subscription types are configurable within subscription type detail in CRM admin. Upgrades don't check the content of each subscription type - therefore they cannot automatically determine that monthly web subscription can be upgraded to monthly web + print subscription. Each upgrade has to be configured manually and all upgrade options are always determined based on actual subscription, price of actual subscription type and price of upgraded subscription type.

Change of VAT rates

If the VAT rate changes in your country, there are two commands that help you update the system. Schedule them to be executed on the date of VAT change.

VAT modes

Before each payment is created, CRM internally assigns it one of the VAT modes - one of B2C, B2B or B2B Reverse-charge mode. Each payment is then processed according to the selected mode.

B2C mode is selected by default by payments module. If you want to set different mode for a payment, the options are:

B2B

No VAT related changes are applied.

B2B Reverse-charge

When B2B reverse-charge mode is applied, VAT is not included in the payment. Practically, this is done by subtracting the VAT from the final sum (as if 0% VAT was set).

B2C

No VAT related changes are applied, unless One Stop Shop mode is enabled.

One Stop Shop

One Stop Shop (OSS) is an optional VAT feature, that can be turned on for payments made in B2C mode. For more details about its specifics, see https://vat-one-stop-shop.ec.europa.eu/index_en.

⚠ One Stop Shop works for EU countries only.

Prerequisites and setup

For turning on the OSS feature, you need:

The feature can be turned on in CRM settings in /admin/config-admin/ in Payments section.

How it works

If enabled, each payment is assigned a payment country when the payment is created. Payment country is resolved according to multiple rules, sorted by priority:

After resolving, payment country is stored along with other payment data. Next, if payment is made outside the default country, OSS adjust VAT rates of the payment items.

VAT rate is adjusted accordingly:

European Union VAT

Loading VAT rates using Vatstack service

To load current VAT rates of EU member countries, we decided to use free VAT rate service https://vatstack.com/ which handles all issues with official EU VAT rates list for us.

After registration you'll find your API keys on page Developers->Api Keys. Add your public API key into your config.neon:

Or you can provide API key with option --vatstack_api_key={VAT-STACK-PUBLIC-API-KEY} when running command.

Usage

VAT rates are stored into vat_rates table for each EU member country _(linked to countries table with foreign key country_id)_.

VAT rates do not change often, but we strongly recommend to add this command into your scheduler (eg. cron). Expired VAT rates are kept with column valid_to set to date when system (this command) expired them.

Get current VAT rates for one country

To get current VAT rates for one country, call method VatRatesRepository->getByCountryAndDate().

API documentation

All examples use http://crm.press as a base domain. Please change the host to the one you use before executing the examples.

All examples use XXX as a default value for authorization token, please replace it with the real tokens:

API responses can contain following HTTP codes:

Value Description
200 OK Successful response, default value
400 Bad Request Invalid request (missing required parameters)
403 Forbidden The authorization failed (provided token was not valid)
404 Not found Referenced resource wasn't found

If possible, the response includes application/json encoded payload with message explaining the error further.


POST /api/v1/payments/paypal-ipn

Handles the IPN notifications from PayPal. Follow this guide to enable IPN notifications for your PayPal account. Use http://crm.press/api/v1/payments/paypal-ipn as "Notification URL" (replace http://crm.press with your domain).

Note: when switching to "live" mode, don't forget to also change the paypal_ipn_baseurl config to the live IPN endpoint (see here)

GET /api/v1/payments/variable-symbol

API call returns unique variable symbol (transaction ID) to be used for new payment instance.

Headers:
Name Value Required Description
Authorization Bearer String yes User token. Token must belong to user with admin flag.
Example:

Response:


GET /api/v1/users/recurrent-payments

API call returns list of all user's recurrent payments.

Headers:
Name Value Required Description
Authorization Bearer String yes User token.
Params:
Name Value Required Description
states String Array no Filter to return only payments with desired states. Available values: active, user_stop, admin_stop, pending, charged, charge_failed, system_stop.
chargeable_from String no ISO 8601 based date to filter only payments with charge_at parameter after the specified date.
Example:

Response:


POST /api/v1/recurrent-payment/reactivate

API call to reactivate user's recurrent payment.

Conditions to successfully reactivate recurrent payment:

Changes:

Headers:
Name Value Required Description
Authorization Bearer String yes User token.
Payload params:
Name Value Required Description
id Integer yes RecurrentPayment ID.
Example:

Response:

On success HTTP status 200 OK is returned with recurrent payment's details.

In addition to API responses described at the beginning of API documentation section:

Value Description
409 Conflict Recurrent payment cannot be stopped by user (reason is in error message)

POST /api/v1/recurrent-payment/stop

API call to stop user's recurrent payment.

Conditions to successfully stop recurrent payment:

Changes:

Headers:
Name Value Required Description
Authorization Bearer String yes User token.
Payload params:
Name Value Required Description
id Integer yes RecurrentPayment ID.
Example:

Response:

On success HTTP status 200 OK is returned with recurrent payment's details.

In addition to API responses described at the beginning of API documentation section:

Value Description
409 Conflict Recurrent payment cannot be stopped by user (reason is in error message)

Components

ActualFreeSubscribersStatWidget

Simple admin dashboard widget showing free subscribers count.

Source code

How to use

ActualPaidSubscribersStatWidget

Simple admin dashboard widget showing paid subscribers count.

Source code

How to use

ChangePaymentStatus

Admin listing/detail change payment status modal component.

Source code

How to use

DeviceUserListingWidget

Admin user listing device component.

Source code

How to use

DonationPaymentItemListWidget

Source code

How to use

DupliciteRecurrentPayments

Admin listing of duplicit recurrent payments.

Source code

How to use

LastPayments

Admin listing of last payments in payment gateway detail.

Source code

How to use

MonthAmountStatWidget

Admin dashboard simple stat widget showing payments amount for last month.

Source code

How to use

MonthToDateAmountStatWidget

Admin dashboard simple stat widget showing payments amount for last month.

Source code

How to use

MyNextRecurrentPayment

Source code

How to use

ParsedMails

Payments admin widget showing payments with wrong amount.

Source code

How to use

PaymentItemsListWidget

Admin listing of payment items in payment detail.

Source code

How to use

SubscribersWithPaymentWidget

Admin dashboard single stat widget.

Source code

How to use

SubscriptionsWithActiveUnchargedRecurrentEndingWithinPeriodWidget

Admin listing widget.

Source code

How to use

SubscriptionsWithoutExtensionEndingWithinPeriodWidget

Admin dashboard stats widget.

Source code

How to use

SubscriptionTypeReports

Admin subscription type detail stats widget.

Source code

How to use

TodayAmountStatWidget

Admin dashboard simple single stat widget.

Source code

How to use

TotalAmountStatWidget

Admin dashboard simple single stat widget.

Source code

How to use

TotalUserPayments

Admin user detail stat widget.

Source code

How to use

UserPayments

Admin user detail listing widget.

Source code

How to use

Confirmation e-mails

Examples of confirmation mails received from banks. Every type of mail has it's own IMAP access configurable in application configuration.

TatraBanka Simple

From: b-mail (at) tatrabanka (dot) sk

Subject: e-commerce

Example e-mail file

TatraBanka

From: b-mail (at) tatrabanka (dot) sk

Subject: Kredit na ucte

Example e-mail file

TatraBanka Statement

From: vypis_obchodnik (at) tatrabanka (dot) sk

Example e-mail file

CSOB

From: notification (at) csob (dot) cz

Subject: CEB Info: Zaúčtování platby

Example e-mail file

Slovak CSOB

From: AdminTBS (at) csob (dot) sk

Subject: ČSOB Info 24 - Avízo

Example e-mail file


All versions of crm-payments-module with dependencies

PHP Build Version
Package Version
Requires php Version ^8.1
ext-soap Version *
php-http/curl-client Version ^2.2.1
tomaj/bank-mails-parser Version ^2.7
tomaj/imap-mail-downloader Version ^1.2.0
rootpd/omnipay-csob Version ^4.4.0
rootpd/omnipay-paypal-reference Version ^4.0.0
singpolyma/openpgp-php Version ^0.6
tomaj/omnipay-tatra Version 4.3.0
geoip2/geoip2 Version ^v2.13.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package remp/crm-payments-module contains the following files

Loading the files please wait ....