Payment Gateways

Craft Commerce payments gateways are provided by Craft CMS plugins.

To create a payment gateway you must install the appropriate plugin, navigate to Commerce → Settings → Gateways, and add configuration for that gateway. For more detailed instructions, see each plugin’s README.md file.

Payment gateways generally fit in one of two categories:

  • External or offsite gateways.
  • Merchant-hosted or onsite gateways.

Merchant-hosted gateways collect the customer’s credit card details directly on your site, but have much stricter requirements such as an SSL certificate for your server. You will also be subject to much more rigorous security requirements under the PCI DSS (Payment Card Industry Data Security Standard). These security requirements are your responsibility, but some gateways allow payment card tokenization.

# First-Party Gateway Plugins

Plugin Gateways Remarks 3D Secure Support
Stripe (opens new window) Stripe Uses Stripe SDK; only first-party gateway to support subscriptions Yes
PayPal Checkout (opens new window) PayPal Checkout Yes
Sage Pay (opens new window) SagePay Direct; SagePay Server Yes
MultiSafepay (opens new window) MultiSafePay REST Does not support authorize charges Yes
Worldpay (opens new window) Worldpay JSON No
eWay (opens new window) eWAY Rapid Supports storing payment information Yes
Mollie (opens new window) Mollie Does not support authorize charges Yes
PayPal (opens new window) deprecated PayPal Pro; PayPal REST; PayPal Express PayPal REST supports storing payment information Only PayPal Express

# Dummy Gateway

After installation, Craft Commerce will install some demo products and a basic config along with a Dummy payment gateway for testing.

This dummy gateway driver is only for testing with placeholder credit card numbers. A valid card number ending in an even digit will get a successful response. If the last digit is an odd number, the driver will return a generic failure response:

Example Card Number Dummy Gateway Response
4242424242424242 Success
4444333322221111 Failure

# Manual Gateway

The manual payment gateway is a special gateway that does not communicate with any third party.

You should use the manual payment gateway to accept checks or bank deposits: it simply authorizes all payments allowing the order to proceed. Once the payment is received, the payment can be manually marked as captured in the control panel.

# Other Gateway Specifics

Before using a plugin-provided gateway, consult the plugin’s readme for specifics pertaining to the gateway.

# Adding Gateways

Additional payment gateways can be added to Commerce with relatively little work. The first-party gateway plugins, with the exception of Stripe, use the Omnipay payment library (opens new window) and can be used as point of reference when creating your own.

See the Extending Commerce section’s Payment Gateway Types page to learn about building your own gateway plugin or module.

# Storing Config Outside of the Database

When you’re configuring gateways in the Craft control panel, we recommend using environment variables (opens new window) so environment-specific settings and sensitive API keys don’t end up in the database or project config.

Craft CMS 3.7.22 added UI giving boolean values the option to be set with environment variables. Previously, these could only be overridden in static config files.

# commerce-gateways.php

The now-deprecated config/commerce-gateways.php format allows storing any number of gateway setting overrides in a common static file, where each array of settings is indexed by a key that matches a payment gateway handle you’ve first configured in the control panel:

return [
    'myStripeGateway' => [
        'apiKey' => getenv('STRIPE_API_KEY'),
    ],
];

If you’re overriding gateway settings this way, you’ll get a deprecation warning:

Overriding gateway settings using the commerce-gateways.php file has been deprecated. Use the gateway’s config file instead.

Commerce 4 will not have support for this format, so it’s best to remove config/commerce-gateways.php and use environment variables like we recommend above. If you must override gateway settings, you can still do that using a standard config file for your gateway plugin (i.e. config/commerce-stripe.php)—but be aware that you’ll only be able to provide one set of settings for that gateway.

While it’s possible to leverage dependency injection (opens new window) to support multiple configurations per payment gateway, settings will eventually get captured in the project config and likely lead to more issues or confusion.

# Payment Sources

Craft Commerce supports storing payment sources for select gateways. Storing a payment source allows for a more streamlined shopping experience for your customers.

The following first-party provided gateways support payment sources:

  • Stripe
  • PayPal REST
  • eWAY Rapid

# 3D Secure Payments

3D Secure payments add another authentication step for payments. If a payment has been completed using 3D Secure authentication, the liability for fraudulent charges is shifted from the merchant to the card issuer. Support for this feature depends on the gateway used and its settings.

# Partial Refunds

All first-party provided gateways support partial refunds as of Commerce 2.0.

# Templating

# craft.commerce.gateways.getAllCustomerEnabledGateways

Returns all payment gateways available to the customer.

{% set gateways = craft.commerce.gateways.getAllCustomerEnabledGateways %}

{% if not gateways|length %}
<p>No payment methods available.</p>
{% endif %}

{% if gateways|length %}
<form method="post">
  {{ csrfInput() }}
  {{ hiddenInput('action', 'commerce/cart/update-cart') }}
  {{ hiddenInput('redirect', 'commerce/checkout/payment') }}

  <label for="gatewayId">Payment Method</label>
  <select name="gatewayId" id="gatewayId">
    {% for id,name in gateways %}
      <option value="{{ id }}"{% if id == cart.gatewayId %} selected{% endif %}>
        {{- name -}}
      </option>
    {% endfor %}
  </select>
</form>
{% endif %}