Configure Payment Gateways

Why payment gateway configuration matters

Payment processing is the most security-sensitive part of your storefront. A misconfigured gateway leads to failed transactions, abandoned checkouts, and potential data breaches. Commerce abstracts payment processing behind a gateway interface, letting you swap providers without rewriting checkout logic. You still need to configure the gateway correctly, handle errors gracefully, and follow PCI compliance practices.

This guide covers integrating a payment provider, implementing tokenization, and handling common payment scenarios.

What you will do

1. Implement a payment gateway class
2. Register the gateway in Commerce
3. Configure client-side tokenization
4. Handle authorization, capture, and refund flows

Implement a payment gateway

Commerce uses the AbstractPaymentGateway base class. Your implementation handles communication with the payment provider’s API.

Payment gateway implementation

C# (.NET)

csharp Copy

using EPiServer.Commerce.Order;
using Mediachase.Commerce.Orders;
using Mediachase.Commerce.Plugins.Payment;

public class StripePaymentGateway
    : AbstractPaymentGateway
{
    private readonly string _apiKey;

    public StripePaymentGateway()
    {
        _apiKey = ConfigurationManager
            .AppSettings["Stripe:SecretKey"];
    }

    public override bool ProcessPayment(
        IPayment payment, ref string message)
    {
        var orderGroup = payment.Parent as IOrderGroup;
        var transactionType = payment
            .TransactionType;

        try
        {
            switch (transactionType)
            {
                case TransactionType.Authorization:
                    return Authorize(payment,
                        ref message);
                case TransactionType.Capture:
                    return Capture(payment,
                        ref message);
                case TransactionType.Credit:
                    return Refund(payment,
                        ref message);
                default:
                    message = $"Unsupported transaction"
                        + $" type: {transactionType}";
                    return false;
            }
        }
        catch (Exception ex)
        {
            message = "Payment processing failed.";
            payment.Status =
                PaymentStatus.Failed.ToString();
            return false;
        }
    }

    private bool Authorize(IPayment payment,
        ref string message)
    {
        var token = payment
            .Properties["PaymentToken"] as string;
        // Call provider API to authorize
        // Set payment.TransactionID on success
        payment.Status =
            PaymentStatus.Processed.ToString();
        message = "Payment authorized.";
        return true;
    }

    private bool Capture(IPayment payment,
        ref string message)
    {
        var transactionId = payment.TransactionID;
        // Call provider API to capture
        message = "Payment captured.";
        return true;
    }

    private bool Refund(IPayment payment,
        ref string message)
    {
        var transactionId = payment.TransactionID;
        // Call provider API to refund
        message = "Refund processed.";
        return true;
    }
}

Register the gateway

Register your gateway in the Commerce administration so it appears as a payment option during checkout.

In the Commerce UI:

1. Navigate to Commerce > Administration > Payment Methods
2. Click Add Payment Method
3. Select your market and language
4. Set the system keyword (must match your gateway class name)
5. Enable the method and set the sort order

Configure client-side tokenization

Never send raw card numbers through your server. Use your provider’s client-side SDK to convert card details into a token before submitting the checkout form.

Tokenization flow:

1. Customer enters card details into the provider’s hosted fields or iframe
2. Provider’s JavaScript SDK creates a token client-side
3. Your checkout form submits only the token (not card data)
4. Your gateway class uses the token to authorize the payment

This approach keeps your server out of PCI scope for card data handling.

PCI compliance considerations

Requirement	Implementation
Never store card numbers	Use tokenization; the provider stores card data
Use HTTPS everywhere	Enforce TLS on all checkout pages
Limit access	Restrict Commerce admin payment settings to authorized users
Authorize then capture	Authorize at checkout, capture only when you ship
Log transactions, not card data	Store transaction IDs and amounts, never PANs or CVVs

Common issues

Issue	Cause	Fix
”Payment method not found” at checkout	Gateway class name does not match system keyword	Verify the system keyword in Commerce admin matches your class name
Authorization succeeds but capture fails	Transaction expired before capture	Capture within the provider’s authorization window (typically 7 days)
Refund returns error	Original transaction already refunded or voided	Check transaction status in the provider dashboard before retrying
Token is null in gateway	Client-side SDK not loading or form not submitting token	Verify the provider’s JavaScript is loading and the token field is included in form submission

Related content

Continue your journey with these related pages.

📖Understand the concepts

• Optimizely Commerce

🔧Follow a guide

• Configure Checkout
• Process Returns