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

The chargeInvoicesImmediately setting

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

1. To create a subscription plan, it must first be created on Stripe.
2. Go to Commerce → Settings → Subscription plans and create a new subscription plan.

Options when subscribing

The trialDays parameter

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.

The cancelImmediately parameter

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

The prorate parameter

If this parameter is set to true, the subscription switch will be prorated. Defaults to false.

The billImmediately parameter

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

The buildGatewayRequest event

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 the transaction property will be ignored;
• Changes to the order_id, order_number, transaction_id, client_ip, and transaction_reference metadata keys will be ignored;
• Changes to the amount, currency and description 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';
  }
});

The receiveWebhook event

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

The createInvoice event

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.
    }
});

The beforeSubscribe event

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.

The receive3dsPayment event

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);
    }
});