Stripe Payment Provider for EPiServer Commerce

Introduction/Motivation

Stripe is a full-stack payment solution provider that is both user and developer-friendly. In this blog post, I will show how to implement a Stripe payment provider for EPiServer Commerce. You can use Stripe to charge customer credit cards, set up recurring payments, store customer information, and much more with simple API calls (and great documentation to go with it) instead of implementing complicated payment gateway logic (take a look at EPiServer’s PayPal payment provider for comparison). It is also designed to reduce PCI-compliance exposure for your site with Stripe (more about that later if you are not already familiar with and in Stripe documentation).

Stripe provides pre-built libraries in several languages, but unfortunately, as of this blog’s writing, an official .NET library does not exist. Having said that, there are a few C# libraries written by various people. For this example here, I used this .NET library for Stripe, a well-written, free library that you can add to your solution as a NuGet package. It is, however, a few versions behind the API at the time of writing this blog. The good news is that there is ongoing work to keep up with the official API, so chances are that your download will be fully up-to-date and compatible with the latest and greatest from Stripe.

The Stripe payment provider in this blog is to demonstrate how to implement a payment gateway for your EPiServer Commerce site to charge customer credit cards. As you will see, this is not a standard EPiServer Commerce payment provider. Unlike other payment providers that must implement that payment gateway logic directly, this Stripe payment gateway boils down to a service call to Stripe, with error-checking as needed. Your front-end implementation will pass the sensitive information to Stripe directly to request a token. You will then pass the token to your server for further processing, having ensured that your server does not ever get to see the aforementioned sensitive data.

Refer to the following links to read more about how to build a custom form to collect credit card information from the user and then to receive a token from Stripe that is valid only for one request by using Stripe.js. This is the approach recommended by Stripe when not using their embedded form called Checkout.

Installation Instructions for Stripe and the Sample Implementation

Requirements

HTTPS, TLS (no SSL due to the POODLE vulnerability)

According to this page, Stripe is served only over TLS. You can test your page without encryption, but you will eventually need to set up TLS when you want to go live.

Add the Stripe.net library via NuGet to your project.

Stripe Set-up

Set up a free account with Stripe here. Your account will remain in test mode until you are ready to activate your account.

Setting Up the Sample Implementation

You can find a bare-bones, sample site with the Stripe payment provider here. Here are the steps to set up the solution so that you can test the payment provider.

• Open the solution and build the solution to restore NuGet packages.
• In a command prompt, run msbuild.exe solution.targets /t:Setup. This sets up the databases for your front-end and Commerce Manager sites.
• Create two IIS sites to point to the SampleSite and CommerceManager projects in the solution.
• Import the test catalog. In Commerce Manager:
• Browse Catalog Management.
• Click on Catalogs.
• Click on Import/Export and select Import Catalog.
• Select the row with the test catalog.
• Click on Start Import.
• Follow the next sections to set up a payment method for Stripe.

Frontend site

Add references to provider project and Stripe.Net NuGet package to your frontend site project.

Commerce Manager

Follow steps 1 through 5 under the “Creating a custom payment gateway” section here to add the gateway to your Commerce Manager so that you can configure it. Alternatively, if you have a project for your Commerce Manager, you can directly add references to example payment provider project and Stripe.Net NuGet package to your project.

Get API keys for your Stripe account.

Create a new payment method for the Stripe payment gateway in Commerce Manager by following steps 6 through 11 from the above link. Use “Stripe” as the System Keyword if you are following along the sample implementation. Step 10 is where you will save your API keys.

Make a meta class for the payment method (import the attached MetaData export) by following these steps:

• Navigate to the Order System/Meta Class node in the Administration section of Commerce Manager.
• Click on Create New at the top of the page and select New Meta Class.
• Enter the following in corresponding fields:
• Name: StripePayment
• Friendly Name: Stripe Payment
• Object Type: Select Order Form Payment
• Click OK.
• Click Meta Fields in the Left Menu under Administration / Order System.
• Click New Meta Field.
• Enter the following in corresponding fields:
• Name: StripeToken
• Friendly Name: Stripe Token
• Type: Select Short String
• Check Allow Null Values.
• Click OK.
• Repeat step 7 for “StripeChargeId”.
• Navigate back to Meta Classes in the Left Menu under Administration / Order System.
• Assign the newly created meta fields to the Stripe Payment meta class:
• For Element: select Order Form Payment
• For Type: select Stripe Payment
• Scroll down to the bottom of the screen and check the box for Stripe Token.
• The form will scroll to the top. Scroll back down to the bottom of the screen and click OK.
• Repeat steps a through d for Stripe Charge ID.

Testing the Sample Implementation

Now that you are set up, pay for a new order with Stripe by following the steps below:

• Browse to your front-end site. If a screen about migration comes up, click the link to start the migration process.
• Click Shopping in the top bar area.
• Click test-node, then test-sku.
• Click Buy. You will be redirected to the cart page.
• Click Checkout in the top bar.
• Click Single Shipment Checkout.
• Click Add Shipment.
• Click Add Payment (Stripe payment provider).
• Click Submit Payment to Stripe.
• Fill out the required fields (more information here).
• Card Number: 4242424242424242.
• Cvc: 123 (or any 3-digit number).
• Expiry Month and Year: Any future date.
• Other fields are optional for this demo.
• Click Submit Stripe payment.
• Click Complete Order.
• Note the purchase order tracking number.
• In Commerce Manager, browse to Order Management / Purchase Orders / Today to confirm that the purchase order with the tracking number from the previous step has been successfully created.
• In your Stripe account dashboard, you can also check that the charge with the correct amount has been made.

Implementation Recommendations

My particular implementation necessitated that I save the Stripe token in the database before making a charge. However, depending on your site implementation, you may not need to do this. The only requirement for using the gateway is to make sure StripePayment.Token is populated when you are ready to complete an order.

Examine the ProcessPayments activity to make sure that the code will eventually hit the gateway. You can download the workflow activities code from here. The main thing here is that payment status is “Pending”.

Earlier in the post, I briefly mentioned that using Stripe helps reduce PCI-compliance exposure. You can have a look here for a clear, concise, and generic example on how to make a Stripe charge using Stripe.js in a .NET project. The important thing here is that you do not submit sensitive information (credit card numbers, expiration dates, etc.) to your server. The example here achieves this by the following steps:

• Leave inputs for sensitive information out of the submitted form altogether.
• Use Stripe.js to make a call to Stripe API and retrieve a one-time token.
• Submit the form with the card amount. All other fields are optional.

By doing this, you keep the sensitive information from reaching your server. One thing to remember is that using Stripe reduces your PCI-compliance exposure – it does NOT absolve you of PCI-compliance completely.

After you post the form to the server, you can attach the token to a StripePayment object, add it to the cart, and run the checkout workflow to process the payment (i.e. make a charge) through the Stripe payment gateway.

Further considerations

If you have payment plans, you might want to consider implementing subscriptions for Stripe in addition to making it work with what is already in Commerce Manager. This way, you will be able to track your transactions on Stripe’s interface as well.

Disclaimer/Limitations

This is only an example implementation and is offered as is. This is not a supported payment provider by EPiServer and merely a demonstration project

This project only supports making one-time charges of transaction type Mediachase.Commerce.Orders.TransactionType.Sale.

If you need to solve this problem, I hope this helps. Please feel free to contact me with any questions/suggestions/bugs in EPiServer Expert Services at Jooeun dot Lee at episerver.com.

Useful Links

https://bitbucket.org/episerver-es/stripe-payment-provider - Source of sample implementation on Expert Services Bitbucket account.

https://stripe.com/docs - Stripe documentation. It is a great place to start learning about Stripe.

http://world.episerver.com/documentation/Items/Developers-Guide/EPiServer-Commerce/8/Payments/Payment-gateways/ - EPiServer’s guide to implementing your own payment gateways.

https://github.com/jaymedavis/stripe.net – GitHub repository of the Stripe.Net library used in this project. This library is very helpful in extracting away most of the complexities with working with Stripe in a .NET project.

https://cmatskas.com/processing-payments-and-being-pci-compliant-with-stripe-js/