PayMongo for Craft Commerce
This plugin provides a PayMongo integration for Craft Commerce.
Requirements
This plugin requires Craft 3.1.5 and Craft Commerce 2.2 or later.
Installation
You can install this plugin from the Plugin Store or with Composer.
With Composer
Open your terminal and run the following commands:
# go to the project directory
cd /path/to/my-project.test
# tell Composer to load the plugin
composer require craftcms/commerce-paymongo
# tell Craft to install the plugin
./craft install/plugin commerce-paymongo
Setup
To add the Stripe payment gateway, go to Commerce → Settings → Gateways, create a new gateway, and set the gateway type to “PayMongo Payment Intents”.
In order for the gateway to work properly, the following settings are required:
- Public API Key
- Secret API Key
Configuring Stripe
Set up a webhook endpoint in your Stripe dashboard API settings. The URL for this endpoint can be found in your Commerce Stripe gateway settings.
It is recommended to emit all possible events, but the required events are:
For 3D secure payments (if using Stripe Charge gateway)
source.cancelled
source.chargeable
source.failed
For subscriptions
The bare minimum of events required are:
invoice.payment_succeeded
customer.subscription.deleted
However, it is strongly recommended to enable the following events as well to ensure your Commerce subscriptions stay in sync with your Stripe dashboard:
plan.deleted
plan.updated
invoice.created
customer.subscription.updated
invoice.payment_failed
Configuring the gateway
When you've set up the endpoint, you can view the signing secret in its settings. Enter this value in your Stripe gateway settings in the Webhook Signing Secret field. To use webhooks, the Webhook Signing Secret setting is required.
Configuration settings
chargeInvoicesImmediately
setting
The For subscriptions with automatic payments, Stripe creates an invoice 1-2 hours before attempting to charge it. By setting this to true in your commerce-stripe.php
config file, you can force Stripe to charge this invoice immediately.
This setting affect all Stripe gateways on your Commerce installation.
Subscriptions
Creating a subscription plan
- To create a subscription plan, it must first be created on Stripe.
- Go to Commerce → Settings → Subscription plans and create a new subscription plan.
Options when subscribing
trialDays
parameter
The When subscribing, you can pass a trialDays
parameter. The first full billing cycle will start once the number of trial days lapse. Default value is 0
.
Options when cancelling a subscription.
cancelImmediately
parameter
The If this parameter is set to true
, the subscription is canceled immediately. Otherwise, it is marked to cancel at the end of the current billing cycle. Defaults to false
.
Options when switching between different subscription plans
prorate
parameter
The If this parameter is set to true, the subscription switch will be prorated. Defaults to false
.
billImmediately
parameter
The If this parameter is set to true, the subscription switch is billed immediately. Otherwise, the cost (or credit, if prorate
is set to true and switching to a cheaper plan) is applied to the next invoice.
Please note, that the subscription switch will be billed immediately regardless of this parameter if the billing periods differ.
Events
The plugin provides several events that allow you to modify the behaviour of your integration.
Payment request related events
buildGatewayRequest
event
The Plugins get a chance to provide additional metadata to any request that is made to Stripe in the context of paying for an order. This includes capturing and refunding transactions.
There are some restrictions:
- Changes to the
Transaction
model available as thetransaction
property will be ignored; - Changes to the
order_id
,order_number
,transaction_id
,client_ip
, andtransaction_reference
metadata keys will be ignored; - Changes to the
amount
,currency
anddescription
request keys will be ignored;
use craft\commerce\models\Transaction;
use craft\commerce\stripe\events\BuildGatewayRequestEvent;
use craft\commerce\stripe\base\Gateway as StripeGateway;
use yii\base\Event;
Event::on(StripeGateway::class, StripeGateway::EVENT_BUILD_GATEWAY_REQUEST, function(BuildGatewayRequestEvent $e) {
if ($e->transaction->type === 'refund') {
$e->request['someKey'] = 'some value';
}
});
receiveWebhook
event
The Plugins get a chance to do something whenever a webhook is received. This event will be fired regardless the Gateway has done something with the webhook or not.
use craft\commerce\stripe\events\ReceiveWebhookEvent;
use craft\commerce\stripe\base\Gateway as StripeGateway;
use yii\base\Event;
Event::on(StripeGateway::class, StripeGateway::EVENT_RECEIVE_WEBHOOK, function(ReceiveWebhookEvent $e) {
if ($e->webhookData['type'] == 'charge.dispute.created') {
if ($e->webhookData['data']['object']['amount'] > 1000000) {
// Be concerned that a USD 10,000 charge is being disputed.
}
}
});
Subscription events
createInvoice
event
The Plugins get a chance to do something when an invoice is created on the Stripe gateway.
use craft\commerce\stripe\events\CreateInvoiceEvent;
use craft\commerce\stripe\base\SubscriptionGateway as StripeGateway;
use yii\base\Event;
Event::on(StripeGateway::class, StripeGateway::EVENT_CREATE_INVOICE, function(CreateInvoiceEvent $e) {
if ($e->invoiceData['billing'] === 'send_invoice') {
// Forward this invoice to the accounting dpt.
}
});
beforeSubscribe
event
The Plugins get a chance to tweak subscription parameters when subscribing.
use craft\commerce\stripe\events\SubscriptionRequestEvent;
use craft\commerce\stripe\base\SubscriptionGateway as StripeGateway;
use yii\base\Event;
Event::on(StripeGateway::class, StripeGateway::EVENT_BEFORE_SUBSCRIBE, function(SubscriptionRequestEvent $e) {
$e->parameters['someKey'] = 'some value';
unset($e->parameters['unneededKey']);
});
Deprecated events
The following events are deprecated as they are associated with the deprecated Stripe Charge gateway.
receive3dsPayment
event
The Plugins get a chance to do something whenever a successful 3D Secure payment is received.
use craft\commerce\Plugin as Commerce;
use craft\commerce\stripe\events\Receive3dsPaymentEvent;
use craft\commerce\stripe\gateways\Gateway as StripeGateway;
use yii\base\Event;
Event::on(StripeGateway::class, StripeGateway::EVENT_RECEIVE_3DS_PAYMENT, function(Receive3dsPaymentEvent $e) {
$order = $e->transaction->getOrder();
$paidStatus = Commerce::getInstance()->getOrderStatuses()->getOrderStatusByHandle('paid');
if ($order && $paidStatus && $order->orderStatusId !== $paidStatus->id && $order->getIsPaid()) {
$order->orderStatusId = $paidStatus->id;
Craft::$app->getElements()->saveElement($order);
}
});