Building an Integration (Stripe) - Part 2 - Web API Controllers

The Series

• Appraising the available tools and choosing which are right for an integration

  • Integration Best Practices: Choosing the Right Tools

• Getting hands-on

  • Building an Integration (Stripe) - Part 1 - Admin Objects and Live Site Functionality
  • Building an Integration (Stripe) - Part 2 - Web API Controllers
  • Building an Integration (Stripe) - Part 3 - Helpers and Event Handlers

---

Setting up the library

First, in your WebApp solution, create a new .NET Framework class library called Custom.Xperience.Stripe.Admin. In this project, install the Kentico.Xperience.Libraries, Newtonsoft.Json, Microsoft.AspNet.WebApi, and Stripe.net NuGet packages (the Kentico libraries version should match the hotfix version of your project). Then, add a reference from the WebApp project to the Custom.Xperience.Stripe.Admin class library.

Adding constants

There are some strings that need to be re-used throughout the admin side of the integration, so let’s make some re-usable constants.

Add a folder to the Custom.Xperience.Stripe.Admin library called Constants. Add a static class called XperienceStripeConstants in the Custom.Xperience.Stripe namespace with the following strings.

Creating a controller

To update orders in Xperience based on what happens in Stripe, we need a controller that will process webhook messages.

Add a Controllers folder to the class library, and create a new class called StripeController. Define it in the namespace Custom.Xperience.Stripe.Endpoint, and give it the following using directives:

Make your class inherit from APIController

This code will need several services to function, so let’s add each of the following.

• An IEventLogService to log errors and information to the Event log.
• An IAppSettingsService to pull the values of settings keys from the web.config file.
• An ILocalizationService to resolve the value of resource strings.
• An IOrderInfoProvider to work with Xperience orders.
• An IOrderStatusInfoProvider to work with Xperience order statuses.
• An IPaymentOptionInfoProvider  to work with Xperience payment options.

Resolving these services in the constructor will let you use a single instance throughout the whole class, rather than having to materialize the service each time you need to access the information that it provides.

Next, we’ll create some utility methods to keep our code organized.

Validating and retrieving the order status

Since this code relies so heavily upon the Stripe payment method’s settings for the order statuses associated with various states, let’s create a method to make sure a provided order status exists and return it if so.

Our method will follow a similar principle to the TryParse methods used by numeric types, returning true and passing a value as an out parameter if the status exists and returning false if not.

Create a new bool method called TryGetValidStatus, which takes an int parameter to hold the order status ID and an OrderStatusInfo out parameter for the order status itself.

The IOrderStatusInfoProvider that we resolved in the constructor has an overload of its Get method that takes a numerical ID as a parameter and returns the corresponding OrderStatusInfo if it exists. Execute this query, setting its result to status, and return true if there was a result.

The result should look like the following.

 

Setting the order status

Now we can create some methods to update the status of an order, which can be called based on the type of message we get from Stripe. These operations are fundamental to the purpose of our endpoint.

First, create a method to update the order to paid status. It should be void and take an order as a parameter.

Since this will be used when Stripe tells us the order was successfully paid for, we know that the order should be marked as paid when we receive this message. Set OrderIsPaid to true after confirming that the order is not null.

If our goal was to be as robust as possible, it might be worth logging an error if the order is null, but for the purposes of this integration, that will be handled higher up in the call stack, before this method is reached. If you plan to use these methods in a different context, though, it may be advisable to add extra logging.

It is possible to configure an order status to set this property automatically when the order reaches it. However, there is no guarantee that whoever uses this integration will take the time to configure that, so let’s set it explicitly to be sure.

Next, pull the Stripe payment option based on the order provided as a parameter.

After that, check if the query found a result. If it did, we can use the TryGetValidStatus method from earlier to validate the ID saved to its PaymentOptionSucceededOrderStatusID setting. Based on the result of this method, either set the order’s OrderStatusID or log an error to the Event log.

The completed method should look like this.

Next, create a method called UpdateOrderToFailed that follows similar logic, setting order.OrderIsPaid to false, and order.OrderStatusID to the failed status specified by the payment option. It should look like the following.

The last method in this group should set the order to the authorized status, which will involve an additional step, and an extra parameter.

Since it will be used when a status is meant to be paid later, we need to give it information that Xperience can use to find the proper payment in Stripe in the future. Define the method with an additional parameter to accept the ID of a Payment Intent from Stripe.

Start by validating the parameters, and log an error if there is no paymentIntentId found.

After ensuring that order.OrderIsPaid is false, because payment has not been captured yet, save the value of the paymentIntentId parameter to the order’s OrderCustomData field.

The rest of the method should be like the previous two, resulting in the following.

Retrieving the order

The integration should receive messages about two types of objects from Stripe— Checkout Sessions and Payment Intents. Let’s make a method to retrieve the related Xperience order based on each.

The method to retrieve an order when we’re processing a Payment Intent should take the ID of the Payment Intent as a parameter and return an OrderInfo object.

We can search the custom data of our orders to see if the payment intent ID was saved to the custom data of any orders.

Finally, we can return the result of this query. Unless the person using the integration uses the stripe API to change the ClientReferenceId saved in Stripe, multiple orders should never be associated with the same payment intent. If there are multiple orders, or no orders, then log an error and return FirstOrDefault.

The resulting method should look like the following.

Next up, we’ll look into retrieving the order from a Checkout Session. Checkout event messages from Stripe will have the ClientReferenceID field available, so take it as the parameter for the method.

Since this parameter references an Xperience OrderID directly, we can find it with a query for equality, unlike the previous case that used WhereLike. The parameter comes from the Stripe event as a string, which we can use with the WhereEquals extension method.

If the query returns a result, return it via SingleOrDefault. The primary key status of OrderID should prevent there from ever being more than one result. If the query returns empty, then log an error that references the clientReferenceId and return null.

The full method should look like the following.

Updating the order

Now we should have the tools to retrieve and update an order based on the events that Stripe sends.

First, create a method to update an Xperience Order (OrderInfo) based on a checkout Session and the Stripe Event that session came from.

Within this new method, validate the parameters and save the Stripe Checkout Session's ID to the order's custom data.

Next, check on the event’s Type, and the PaymentStatus of the checkout session. If the checkout session is completed, it can have two potential payment statuses— paid or unpaid.

If the checkout session is completed and paid, update the order to the Paid status with the method you built earlier.

If the checkout session is completed but the order is unpaid, the payment will be captured later. In this case, we should consider this payment authorized. In this case, call the UpdateOrderToAuthorized method from earlier.

Similarly, if the checkout session expired, we can use our earlier method to set the order to the Failed status.

Lastly, we can log an error if the event turns out not to fit any of the supported types and update the order.

The result should be the following.

 

Starting with the parameters provided by the event, there’s still a bit of setup we need to do before we can use this method.

Create a new method taking an Event as the parameter.

We need to parse a Session (checkout session) from the provided Event’s Data.Object property, so let’s validate that each of these pieces are not null, logging an error if necessary. Then we can use the as operator to get a Session object, and similarly validate it.

The ClientReferenceId in Stripe is not a required field, so check whether it is filled in, before using it to get the order. Log an error if it is absent.

Then, if the order is not null, call the UpdateOrderFromCheckoutSession method, passing along the Session, OrderInfo, and Event. Log an error if it is null.

When you’re done, the result should look like this.

The analogous process for Payment Intents requires less setup and can fit into a single method.

Start by taking the Event as a parameter once more, and mirror the previous steps of validating and casting it to a PaymentIntent.

Get the order using the GetOrderFromPaymentIntent method from earlier.

 

If the order can be found, set its status based on whether the payment intent indicates success or failure, and log an error if it indicates an unsupported event.

Lastly, update the order with any changes that may have occurred.

This should leave you with a method that looks like the following.

We also need a method to get a Stripe event based on the request posted to our endpoint, in order to supply the Event parameter of the methods we’ve just created.

Stripe has a utility method to construct an event that takes a specific header value, along with the JSON body of the request and the webhook secret key as parameters. Let’s have our method accept the same parameters with one caveat— take the header value as an enumerable set of strings so that it can accept the out-parameter value of the HttpRequestMessage method TryGetValues.

First, extract the Stripe header from the enumerable parameter, and create a null Event object.

Verify that the signature header was retrieved before passing it along.

Now, try to populate this Event using Stripe’s utility method and log an error if it fails.

Finally, return the Event, outside of the conditional.

The resulting method should look like the following.

Now we should have everything the endpoint will need, so let’s add it.

Define an asynchronous method that returns a Task for an HttpResponseMessage, and decorate it with the HttpPost attribute.

Collect the JSON from the request body using the StreamReader’s ReadToEndAsync method and pull the CustomStripeWebhookSecret setting from the web.config of the admin app.

If the setting was successfully retrieved, get the Stripe-Signature header from the request, logging errors if either of these pieces can’t be found.

Using the Stripe-Signature value, along with the JSON object and the settings key, get an Event object from Stripe via the GetStripeEvent method from earlier.

After validating the Data.Object property of the event, evaluate whether the event is for a Payment Intent or a Checkout Session and call the appropriate Update… method, logging an error if it fits neither category.

Finally, return a 200 OK status code, to let Stripe know that the request was received.

In the end, it should look like this.

Registering a Web API module

Now that the controller is in place, we need to register it.

In the Custom.Xperience.Stripe.Admin project, open AssemblyInfo.cs, located under Properties in the solution explorer. Add a using directive for CMS, and add the AssemblyDiscoverable attribute.

Now, add a new folder called ModuleRegistration to the project, containing a class XperienceStripeEndpointModule.

Add the following using directives.

Add the RegisterModule assembly attribute, passing the type of your class as the parameter. Use the namespace Custom.Xperience.Stripe.Endpiont for the class, and have it extend Module.

Have the constructor call the base constructor, passing a name for your module, XperienceStripeEndpoint, as the parameter.

Override the OnInit method, and call base. Then map a route to the StripeController’s Update action.

What’s next

The next article will cover the implementation of a helper class, which can capture approved payments and a global event handler which automatically captures payments when an order enters a specific status.