In this series, we’ve explored some key highlights for a modest implementation of a Stripe integration that brings together the capabilities of Stripe Connect and Stripe Billing for a fictitious business, Oasis Hubs. The business provides customers access to unique private and commercial workspaces that can be conveniently booked for a given number of hours. Customers will be able to choose between different subscription tiers that will give them access to various workspace listings (hubs) which have been provided by the service vendors (hosts). Hosts will sign up to the platform to provide details of their available workspaces, and get paid monthly based on the number of hours booked for their workspace.

In this last (maybe?) article, we will cover validating subscription logic with test clocks.

We should test this

In the software industry, and also many others, it is important that we thoroughly test our products before releasing them to the public. Unit tests, integration tests, A/B tests, performance tests, and many more aim to verify and set the quality bar so we can ship with confidence. However, with the way we test software today, there is usually an expectation that when a suite of tests is run we should receive results that we can inspect within a relatively short amount of time. Depending on the type, tests may take a few minutes or even as long as a few hours.

When building support for recurring payments such as a subscription or a payment plan that might have a billing cycle spanning weeks or months, how can we verify our integration is working correctly? Waiting in real-time for one iteration of a billing cycle is far from being a viable option. While running unit tests against the various components of our software in isolation is possible, we still need the ability to run through more realistic scenarios; especially when integrating with an external payments service like Stripe.

Time traveling with Test Clocks

Since no one on the planet, that we know of, has successfully invented a time machine we are going to need to look for another alternative for simulating recurring billing cycles. Within the Oasis Hubs Stripe account, in test mode, we can make use of a feature called test clocks. Test clocks will allow us to simulate the forward movement of time in Stripe objects; like subscriptions, quotes, and customers. Once the time is adjusted, any time sensitive webhook events will get triggered and we will be able to handle those events in the action methods of the WebhookController.

We’ve discussed handling webhooks and the WebhookController on various occasions in previous articles of this series. //ADD LINK

Test clocks can be used to validate the logic for time based scenarios in your Stripe integration such as trial periods, prorations, subscription payments, upgrades or renewals. Creating and using a test clock follows a similar pattern to the other objects we’ve created in Stripe. In this article we’ll be using the Stripe .NET library, but there are other options available such as the Stripe CLI, the Stripe Dashboard, or one of the other language SDKs. This means that instead of waiting for weeks or months to test our recurring payment integration, we can run a simulation that would only take a few minutes.

Before we can start a simulation, we need to create a new test clock and set its initial time using the “FrozenTime” property. We have to specify the time as a Unix Epoch timestamp which can be either in the past or in the future. Once the TestClock object is created it can only be moved forward in time.

var tcCreateOptions = new TestClockCreateOptions{
   Name = $"Subscription Clock ({name})",
   FrozenTime = DateTimeOffset.UtcNow.DateTime
};

var testClockService = new TestClockService();
var newTestClock = await testClockService.CreateAsync(tcCreateOptions);

Test clocks can be attached to different objects in Stripe such as Customers, Subscriptions or even quotes. The snippet above, from the Oasis Hubs fake data generator, creates a new Customer object and associates it with a test clock. Existing objects in a Stripe account cannot be later updated to use a test clock. This has to be specified at the time of creation.

var ccOptions = new CustomerCreateOptions{
    Name = name,
    Email = email,
    Description = "Faker User Account",
    PaymentMethod = "pm_card_visa",
    TestClock = newTestClock.Id,
    InvoiceSettings = new CustomerInvoiceSettingsOptions
    {
       DefaultPaymentMethod = "pm_card_visa"
    }
};
var newCustomer = await customerService.CreateAsync(ccOptions);

Once this is done, other relevant Stripe objects linked with this Customer will also be associated with the test clock. That means when a Subscription or Invoice object is created for this Customer, we don’t have to pass the test clock Id along to them. This behavior applies to objects created via one of Stripe's hosted payment forms or if the objects created directly via the Stripe API.

var options = new SubscriptionCreateOptions {
    Customer = newCustomer.Id,
    Items = new List<SubscriptionItemOptions> {
        new SubscriptionItemOptions {Price = "my_price_id"}
    }
};

var subscriptionService = new SubscriptionService();
await subscriptionService.CreateAsync(options);

Inside of the Stripe Dashboard, any Customer objects created in test mode that are associated with a test clock will have a clock item next to their record.

If we dig deeper into the Customer details, you will notice that we now have the option to to “Advance time” using that test clock.

Test clocks can be advanced using the UI in Stripe Dashboard and also from your application code using one of the SDKs.

However, test clocks have limitations. Test clocks can only be advanced by two intervals at a time based on the shortest subscription interval of associated items. For example, if the test clock is associated with a monthly subscription, it can only advance up to two months at a time. If there are multiple associated subscription cycles, then the clock can be advanced up to two internals of the shortest cycle.

Limitations of Time Traveling

Before we start setting up and processing complex scenarios using test clocks. For each test clock created, there can be only three attached Customers, three attached Subscriptions, and ten Quotes. It is possible to create multiple test clocks that have their own unique name, initial time, and collection of associated Stripe objects. To learn more about the limitations of test clocks, take a look at documentation links referenced below.

Regardless of the limitations, this feature enables the possibility of some interesting test cases that you can integrate into your test automation and CI/DI pipelines.

References

• Oasis Hubs GitHub Repository
• Stripe Test Clocks
• Stripe Connect
• Stripe CLI

Stay connected with Stripe

You can also stay up-to-date with Stripe developer updates on the following platforms:

📣 Follow @StripeDev on Twitter. 📺 Subscribe to our YouTube channel. 💬 Join the official Discord server. 📧 Sign up for the Developer Digest.

In this series, we’ll explore some key highlights for a modest implementation of a Stripe integration that brings together the capabilities of Stripe Connect and Stripe Billing for a fictitious business, Oasis Hubs. The business provides customers with access to unique private and commercial workspaces that can be conveniently booked for a given number of hours. Customers will be able to choose between different subscription tiers that will give them access to various workspace listings (hubs) which have been provided by the service vendors (hosts). Hosts will sign up to the platform to provide details of their available workspaces, and get paid monthly based on the number of hours booked for their workspace.

Throughout this series, we will cover topics such as setting up Stripe Connect Onboarding, managing Stripe events, implementing metered billing, and validating subscription logic with test clocks.

Getting Paid

Oasis Hubs’ business model is based on charging for subscriptions that Customers choose from; either Basic, Standard, or Premium. Each level has its own benefits and pricing. Pricing starts at $35 monthly for Oasis Basic, $60 monthly for Oasis Standard, and $120 monthly for Oasis Premium. Each tier comes with 10 hours of hub rental per month, but the hours do not roll over to the following months. If a customer goes over their monthly allotment, they will be charged overage fees for each additional hour.

What about compensating the hosts? Once customers have successfully paid their monthly invoices, the hosts get paid a percent of the total invoice relative to the number of hours a customer used in their listing. For example, if a customer used 10 hours during a given month and 5 of those hours were booked at host A’s listings then host A will get paid 50% of the available funds to be paid out.

Once a customer’s invoice has been paid at the end of a billing cycle, Oasis Hubs will hold on to a portion of the revenue and distribute the remaining available funds between the respective hosts.

Modeling Products and Prices in Stripe

Before we can display pricing tiers to the customers on the website, we must first model them within Stripe as Product and Price objects. Based on the description above, each tier will need to have two prices. One price will represent the fixed monthly subscription price, while the other will be the hourly rate for any accrued overages. What we’ll do is make the overage rate 10% of the monthly fixed rate. The price breakdown will look something like this.

We have options when it comes to creating Products and Prices objects in Stripe. This article will focus on creating all the objects we need using the Stripe .NET library. That will give us access to the ProductService and PriceService classes that we can use to create and attach prices to products for Oasis Hubs.

ProductService productsService = new ProductService();
var prodCreateOptions = new ProductCreateOptions {
   Name = title,
   Description = description,
   Images = new List<string> { fileLink.Url },
   Features =
       features.Select(f => new ProductFeatureOptions { Name = f }).ToList(),
   UnitLabel = "hour",
   Metadata = new Dictionary<string, string> { ["tier.image"] = imageFileName }
};

var newHubProduct = await productsService.CreateAsync(prodCreateOptions);

To create products using the ProductService, we need to populate an instance of the ProductCreateOptions object and pass it to the CreateAsync method as shown above. The only required property is “Name” but providing more detail can be helpful later on in other parts of the application. In the example above, in addition to the name, we’re adding a description, an image URL, a list of features, and the unit label. As mentioned earlier, these properties can be updated later via the Dashboard if needed. Next, we’ll create the prices.

PriceService priceService = new PriceService();

// Create flat price in product
var priceCreateOptions = new PriceCreateOptions {
   Product = newHubProduct.Id,
   Nickname = newHubProduct.Name,
   Currency = "usd",
   UnitAmount = hourlyUnitPrice,
   LookupKey = $"{priceLookupPrefix}_usd",
   Recurring =
       new PriceRecurringOptions { Interval = "month", UsageType = "licensed" }
};

var newProductPrice = await priceService.CreateAsync(priceCreateOptions);

// Update default price
await productsService.UpdateAsync(newHubProduct.Id, new ProductUpdateOptions {
   DefaultPrice = newProductPrice.Id
});

Similar to the ProductService, with the PriceService we have to populate a PriceCreateOptions object and pass it to the CreateAsync method. This class, however, requires a currency code, a unit amount in cents which represents the prices, and also the Id of the Product object the price is associated with.

In the Stripe object model, Products objects can have many attached Prices, but Price objects are attached to one Product.

Since Oasis Hubs needs to have a fixed monthly price for each tier, the “Recurring” property is set on the PriceCreateOptions objects with an “Interval” of “month” and the “UsageType” set to “licensed.” In Stripe, recurring purchases can have a usage type of either “licensed” or “metered.” We can think of “licensed” as a fixed price per quantity. For example, if we were selling a service at $15 per month per user and a company signed up with 10 employees then they would have one monthly subscription at $150 per month. We don’t need to model prices that way with Oasis Hubs, so we will always assume that this quantity for this price is one per customer. Now let’s look at creating the price for the overages.

// Create tiered pricing in product
priceCreateOptions = new PriceCreateOptions {
   Product = newHubProduct.Id,
   Nickname = newHubProduct.Name,
   LookupKey = $"{priceLookupPrefix}_usd_tiered",
   Currency = "usd",
   Tiers =
       new List<PriceTierOptions> { new() { UnitAmount = 0, UpTo = 10 },
                                    new() { UnitAmount = hourlyUnitPrice / 10,
                                            UpTo = PriceTierUpTo.Inf } },
   Recurring =
       new PriceRecurringOptions { Interval = "month", UsageType = "metered" },
   TiersMode = "graduated",
   BillingScheme = "tiered"
};

newProductPrice = await priceService.CreateAsync(priceCreateOptions);

There are some significant differences between the fixed monthly Price object we created previously and the one we’re creating now. First, notice that the “UsageType” is set to “metered.” This is because the price that we’re modeling here is based on the number of additional hours consumed by a customer that month. That also means we’ll need to track usage for each customer as well, but we’ll get to that later on in the article. The next major difference to nice is that the “Tiers” property is being set with a list of pricing tiers. The first one specifies that the first 10 reported hours will not be charged. This makes sense since customers would have already paid for this allotment upfront through the fixed monthly pricing. The second tier for the Price object specifies that each additional hour reported over the 10 initial hours will be charged at 10% of the monthly fixed rate.

Processing Subscriptions

Now that subscription products and prices have been set up in Stripe, the next thing we should probably do is create a page where customers can see them. One of the convenient options at our disposal is the embedded pricing table from Stripe. This low code option allows us to design a pricing table with up to four products that we can embed in any website by just copying the generated code. Through the designer in the Stripe Dashboard, we can set options for tax collection, address collection, enable promotion codes, configure the look and feel, plus many other useful options.

One of the limitations the embedded pricing table has is that it doesn't give us an option to require that the customer is authenticated with an active account before proceeding to a checkout page. For this reason, Oasis Hubs created its own pricing table that’s aware of the user identity we created in the first article of this series.

To create this page, we’ll make use of the ProductService we used earlier. This time, instead of creating new products we’ll use it to query for the ones already in the Oasis Hubs Stripe account.

public IEnumerable<Product> HubTierListings { get; set; } =
    Enumerable.Empty<Product>();

public Pricing(UserManager<OasisHubsUser> userManager,
               IStripeClient stripeClient, LinkGenerator linkGenerator,
               ILogger<Pricing> logger) {
   this._userManager = userManager;
   this._stripeClient = stripeClient;
   this._linkGenerator = linkGenerator;
   this._logger = logger;
}

public async Task<IActionResult> OnGetAsync() {
   var productsService = new ProductService(this._stripeClient);

   var options =
       new ProductListOptions { Expand = new() { "data.default_price" },
                                Active = true };

   var products = await productsService.ListAsync(options);
   if (products.Any()) {
      HubTierListings =
          products.Where(p => p.Metadata.ContainsKey(_tierMetaKey));
   }

   return Page();
}

This code sample above shows a snippet of what the PageModel of the pricing page looks like. We populate an instance of the ProductListOptions object and provide it to the ListAsync method of the ProductService class. The set properties let Stripe know that we only want active products and to include the default price in the result set.

<main class="max-w-7xl m-auto px-6">
   <div class="w-full mx-auto bg-white px-5 py-10 text-gray-600">
      <div class="text-center w-3/4 mx-auto">
         <h1 class="text-5xl md:text-6xl mb-5">Subscription Plans</h1>
         <h3 class="font-medium text-xl text-gray-500 mb-10">Get started with one of tiered plans to get access to a curated list of our unique workspace options provided by our Oasis Hub Hosts. </h3>
      </div>
      <div class="max-w-full mx-auto md:flex">
         @foreach (var tier in Model.HubTierListings)
         {
            <vc:tier-pricing-item tier-product="@tier"></vc:tier-pricing-item>
         }
      </div>
   </div>
</main>

Then we’ll iterate through the results within Razor and pass each product to a custom pricing item component we created with a ViewComponent.

<div class="w-full">
      @if (User.Identity?.IsAuthenticated ?? false)
      {
         <form asp-page="/Pricing" method="POST">
            <button type="submit">Subscribe Now</button>
            <input type="hidden" name="lookupKey"
 value="@Model.TierProduct.DefaultPrice.LookupKey"/>
         </form>
      }
      else
      {
         <a asp-page="/signin" asp-route-returnUrl="/pricing">Sign in to Subscribe</a>
      }
</div>

The ViewComponent is mostly static but the button is where most of the interesting bits are. If the user is signed in, we render an HTML form that kicks off the checkout process otherwise we render a button that prompts the user to “Sign in to Subscribe.” Notice that we’re using the LookupKey for the default price for the product as a hidden form field.

Let’s break down the handler method that processes the subscribe request.

var lookupKey = Request.Form["lookupKey"].ToString();

var plOptions = new PriceListOptions {
     LookupKeys = new List<string> { lookupKey, $"{lookupKey}_tiered" }
};

var priceService = new PriceService(this._stripeClient);
var prices = await priceService.ListAsync(plOptions);
var lineItems = prices.Select(p => new SessionLineItemOptions {
   Price = p.Id, Quantity = !p.LookupKey.EndsWith("_tiered") ? 1 : null
}).ToList();

First we retrieve the Price objects associated with the specified lookup keys. The line items here should always have two prices. One of the fixed monthly and another for the tiered usage.

 var basePageUri = _linkGenerator.GetUriByPage(this.HttpContext, "/Index");
var scOptions = new SessionCreateOptions {
   Customer = user.StripeCustomerId,
   CustomerUpdate = new SessionCustomerUpdateOptions { Address = "auto" },
   LineItems = lineItems,
   Mode = "subscription",
   AutomaticTax = new SessionAutomaticTaxOptions { Enabled = true },
   SuccessUrl = $"{basePageUri}/PaymentComplete?session_id={{CHECKOUT_SESSION_ID}}",
   CancelUrl = $"{basePageUri}",
   ConsentCollection = new() { Promotions = "auto" },
   AllowPromotionCodes = true
};

var sessionService = new SessionService(this._stripeClient);
var session = await sessionService.CreateAsync(scOptions);
return Redirect(session.Url);

Then we create a new checkout session for the logged in user. Following a similar pattern as other Stripe services, we create an instance of the SessionCreateOptions object and pass it on to the CreateAsync method of the SessionService class. The session we’re creating will let Stripe know that we want to provision a hosted payment form for our logged in user with the given products; in this case it’s an Oasis Subscription. Some essential properties to pay attention to here are “Customer,” “Mode,” and “LineItems.” Also notice the SuccessUrl and CancelUrl properties which are used to redirect customers back to the main Oasis Hubs website to different URLs depending on if they successfully completed the checkout form or not.

After creating the checkout session, we can redirect the customer to the hosted checkout page using the URL property.

After the customer completes checkout, they’ll get redirected to the URL set on the SuccessUrl property of the session. As the payment is being processed, Stripe will generate a series of events which can be observed and processed using our webhook handler we created using the WebhooksController in the previous article of this series.

switch (stripeEvent.Type) {
case Events.InvoicePaid:
{
  var invoice = (stripeEvent.Data.Object as Invoice) ! ;
      await this._commandProcessor.PostAsync(new InitiateFundsTransferCommand(invoice));
  break;
  }
case Events.CustomerSubscriptionCreated:
{
  var newSubscription = (stripeEvent.Data.Object as Subscription) ! ;
    await this._commandProcessor.PostAsync(
      new ActivateCustomerSubscriptionCommand(newSubscription));
    break;
  }
case Events.CustomerSubscriptionUpdated:
{
  var updatedSubscription = (stripeEvent.Data.Object as Subscription) ! ;
   await this._commandProcessor.PostAsync(
      new ActivateCustomerSubscriptionCommand(updatedSubscription));
  break;
  }
default:
  _logger.LogInformation("Unhandled event type: {StripeEvent}", stripeEvent.Type);
  break;
}

Some of the events we should pay attention to include customer.subscription.created, customer.subscription.deleted, customer.subscription.paused and customer.subscription.updated. Here is where we can start any associated workflows, adjust user permissions, or update any data tables related to the customer’s account. One of the workflows for Oasis Hubs sets the ActiveSubscriptionId and HasSubscriptionActive properties on the OasisHubUser record for the customer. We introduced this type in the first article of this series.

Subscription Management

It is fair to assume that, after subscribing, customers might want to make adjustments to their subscriptions. They will expect to be able to update their billing information, view their invoice history, upgrade their subscriptions, or even cancel their subscriptions entirely. As responsible engineers, we should build these types of capabilities into our applications. But what if we don’t have too?

If we prefer not to spend the engineering cycles on this type of work, Stripe’s Customer Portal can provide us with a low-code option for adding these features to our applications.

To enable the Customer Portal, go to the Stripe Dashboard, use the search bar to search for the setting, then click on the “Enable” button on the configuration page. We will be able to toggle features on or off to suit our needs. To incorporate the portal into an application, we’ll have to create a new session for the customer and redirect them to using the generated URL. This is very similar to the checkout session we created earlier.

   [Authorize]
   [HttpPost("create-portal-session")]
   public async Task<IActionResult> CreatePortalSession() {
      var user = await _userManager.GetUserAsync(User);
      if (user == null) {
         return RedirectToPage("/SignIn");
      }

      var basePageUri = _linkGenerator.GetUriByPage(this.HttpContext, "/Index");
      var options = new Stripe.BillingPortal.SessionCreateOptions
      {
         Customer = user.StripeCustomerId,
         ReturnUrl = basePageUri
      };
      var service = new Stripe.BillingPortal.SessionService(_stripeClient);
      var portalSession = await service.CreateAsync(options);
      return Redirect(portalSession.Url);
   }

It’s important that these sessions are only shared with authenticated users since it exposes the ability to view and update sensitive information like the customer’s billing address and payment information.

To create a portal session, we’ll need the Id for the Stripe Customer object and a return URL the customer should be redirected when they’re ready to leave the portal.

Once a customer is redirected to the portal, they’ll be able to manage their subscription details through a Stripe hosted page.

Reporting Usage

At this stage, the Oasis Hubs website is set up to process subscriptions so the missing piece in our metered billing story is tracking the hours used when customers book workspaces.

For the purpose of keeping the demo relatively simple, collect usage at the time of booking. In a more realistic scenario we’ll want to implement a more robust check in/out system. On the details page for a workspace listing, provide a simple form where customers can enter a check in date, number of guests, and how many hours they want to use. The handler method on our Razor Page handles the request processing.

var checkInDate = DateTimeOffset.Parse(Request.Form["checkInDate"].ToString());

var hours = int.Parse(Request.Form["hours"].ToString());
var booking = new Booking {
  RenterId = renterId,
  RentalId = Request.Form["rentalId"].ToString(),
  Hours = hours,
  ReservedDateUtc = checkInDate.ToUniversalTime()
};

await using
var context = await this._dbContextFactory.CreateDbContextAsync();
context.Bookings.Add(booking);
await context.SaveChangesAsync();

Once the request has been validated, create a new record in the bookings table of our database using Entity Framework Core.

// retrieve subscription
var subscriptionService = new SubscriptionService(this._stripeClient);
var subscription = await subscriptionService.GetAsync(OasisUser.ActiveSubscriptionId);

  var subItem = subscription.Items.Data.Single(s =>s.Price.LookupKey.EndsWith("_tiered"));

  // report on usage
  var ucOptions = new UsageRecordCreateOptions {
    Quantity = hours,
    //Timestamp = DateTime.UtcNow,
    Action = "increment"
  };
  var idempotencyKey = Guid.NewGuid().ToString("N");
  var requestOptions = new RequestOptions {
    IdempotencyKey = idempotencyKey
  };

  var usageRecordService = new UsageRecordService(this._stripeClient);
  await usageRecordService.CreateAsync(subItem.Id, ucOptions, requestOptions);

To report the customer’s usage for the subscription, make use of two additional service classes from Stripe .NET; SubscriptionService and UsageRecordService.

Using the ActiveSubscriptionId property of our logged in user, we retrieve the Subscription object from Stripe with the SubscriptionService. If you recall, each subscription has two prices, but here we’re only interested in the tiered price. Then we create a usage report by populating an instance of the UsageReportCreateOptions object with the number of hours being booked and setting the action to “increment”. We supply the UsageRecordService with the UsageReportCreateOptions instance and the Id of the subscription item that represents the tiered price.

At the end of the billing cycle, Stripe will automatically finalize the invoice and charge the saved payment method for the customer. As you can imagine, this will generate a variety of events that can be subscribed to and handled via webhooks. As shown in an image earlier in this article, one of the events Oasis Hubs is particularly interested in is the “invoice.paid” event. Here we can refresh the customer status if necessary and distribute funds to our hosts.

Paying the connected accounts

We have previously discussed the registration flow hosts onboarding with Oasis Hubs. They are associated with regular Customer objects in Stripe as well as Stripe Connect Express accounts. When hosts create listings for workspaces, a database record is created that contains a field for the Id of the Connect account it’s associated with.

public class HubRental {
   public string Id { get; set; } = Guid.NewGuid().ToString("N");
   public required string Title { get; set; } = string.Empty;
   public string Description { get; set; } = string.Empty;
   public string Location { get; set; } = string.Empty;
   public int Capacity { get; set; }
   public RentalType HubType { get; set; } = RentalType.Other;
   public RentalTier HubTier { get; set; } = RentalTier.Basic;
   public string ImageUrl { get; set; } = string.Empty;
   public string StripeAccountId { get; set; } = string.Empty;
   public required string ReferenceCode { get; set; } = string.Empty;
   public bool IsActive { get; set; } = true;
}

public enum RentalTier { Basic, Standard, Premium }

public enum RentalType { EntireSpace,Room, Desk, Other }

When the “invoice.paid” event is received, we publish a message to the message broker (RabbitMQ) that instructs our system to start the payment distribution process for the Connect accounts. Within the process, we retrieve the customer, workspace listing, and booking records from the database. Then we do some math to determine how much money each account is owed. After that, we initiate a transfer using Stripe .NET.

var transOptions = new TransferCreateOptions {
  Amount = transferAmount,
  Currency = "usd",
  Destination = accountId,
  SourceTransaction = command.Invoice.ChargeId,
  Metadata = new Dictionary < string,
  string > { ["invoice.id"] = command.Invoice.InvoiceId,
    ["invoice.hours.total"] = totalReportedHours.ToString(CultureInfo.InvariantCulture),
    ["invoice.hours.account_reported"] = reportedAccountHours.ToString(CultureInfo.InvariantCulture),
    ["invoice.hours.percentage"] = accountHoursPercentage.ToString(CultureInfo.InvariantCulture)
  }
};

await transferService.CreateAsync(transOptions, cancellationToken: cancellationToken);

I left out the math part. That’s pretty boring anyway and you didn’t come here for that. However, the snippet above shows the code required to tell Stripe to begin the transfer process. We create a TransferCreatedOptions instance and provide it with the amount, currency, and the account Id of the Connect account that the funds should be sent to. For record keeping purposes, we also assign the “SourceTransaction” property so we can know what invoice payment these transferred funds are associated with.

At this point, the Oasis Hubs integration with Stripe has most of the functionality needed to run the business. Customers and hosts are able to sign up and go through onboarding. The subscriptions have been set up using Products and Prices objects. Customers can choose a subscription and report the hours they’ve used. Then we just saw how to pay hosts using the TransferService in Stripe .NET. In the next article of this series, we learn how to test out our subscription logic using test clocks.

References

• Oasis Hubs GitHub Repository
• Stripe Connect
• Stripe Connect guide
• Stripe Connect Account Types
• Stripe CLI

Stay connected with Stripe

You can also stay up-to-date with Stripe developer updates on the following platforms:

📣 Follow @StripeDev on Twitter. 📺 Subscribe to our YouTube channel. 💬 Join the official Discord server. 📧 Sign up for the Developer Digest.

In this series of blog posts, we’ll explore some key highlights for a modest implementation of a Stripe integration that brings together the capabilities of Stripe Connect and Stripe Billing for a fictitious business, Oasis Hubs.

The business provides customers with access to unique private and commercial workspaces that can be conveniently booked by the hour. Customers will be able to choose between different subscription tiers that will give them access to various workspace listings (hubs) which have been provided by service vendors (hosts). Hosts will sign up to the platform to provide details of their available workspaces, and get paid monthly based on the number of hours booked for their workspace.

Beyond APIs

In the previous article in this series, we examined how to integrate customer registration and onboarding for Stripe Connect accounts into an ASP.NET Core Razor Page application. To do this, we leveraged the Stripe .NET NuGet package which provides a convenient wrapper around the Stripe HTTP APIs. While Stripe does provide an abundance of functionality through API endpoints, there will be situations that require more than a typical request-response interaction.

If we consider some of the typical workflows that happen in the world of business, we understand that there are some processes that can resolve themselves immediately while others might take more time to complete. The financial workflows supported by Stripe also operate in a very similar fashion. Invoking commands to create new customers or products within a Stripe account have the expectation of executing and returning a result almost immediately. On the other hand, carrying out tasks like identity verification or processing delayed payment methods might take minutes, hours or even days. Take a moment and consider the onboarding process of Oasis Hubs in the real world. Verifying those business and banking details for Connect accounts can take some time to complete. So how can we handle these types of interactions? How do we get notified and react to updates that happen to the processes within our Stripe account? This is where we have to go beyond APIs and start thinking about events.

Understanding Stripe Events

As updates happen to the state of the activities running within your Stripe account, various events get generated to inform you that something has changed. This can be extremely beneficial for Stripe integrations as they can subscribe to the events they’re interested in and run the associated workflows. For example, imagine subscribing to an event that lets you know another order was placed for the custom t-shirts your company makes. At this point, you might want to start your fulfillment process of packing and shipping the new order to the customer. The pricing model of Oasis Hubs is based on monthly subscription. It will be important to listen for created and canceled subscription events to know access to listings should be updated for a given user.

When events are triggered in a Stripe account, a new Event object will be created that contains contextual information about what caused the event. The API reference documentation contains an exhaustive list of event types that it supports. While events vary, there are a few key properties on each one that should be paid attention to.

{
  "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy",
  "object": "event",
  "api_version": "2019-02-19",
  "created": 1686089970,
  "data": {   },
  "livemode": false,
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "customer.subscription.created"
}

The image above shows a condensed version of what an event object might look like. Probably the most important property of them all is “type”. You will need to inspect this value to determine which event has been triggered; which also has implications for the type of data it’s carrying. Another important property to observe, as you might have guessed, is “data”. This contains the Stripe object that is most relevant to the event that just fired. If you’ve subscribed to and received a customer.updated event, it would be fair to expect that the data property of the event could contain a customer object. The “api_version” property of the event object indicates the version of the Stripe API that the payload is associated with. This can be important when debugging your integration as different versions return payloads with different properties which could cause issues if your installed SDK or parser is expecting a particular shape.

To learn more about setting an API version in your SDK and on your Stripe account, take a look at the following link https://stripe.com/docs/libraries/set-version

Implementing Webhooks

The way an application can subscribe to event activity firing on a Stripe account is through registering a webhook. This is a common pattern used by service platforms to notify customers via an exposed HTTP endpoint. For the security minded folks, this really should be a HTTPS endpoint and that is a requirement for live mode environments in Stripe. I like to think of webhooks as an implementation of the Hollywood Principle, "Don't Call Us, We'll Call You".

Registering a webhook endpoint with Stripe can be done through the dashboard, but what we will be doing instead is seeing how to run webhook handlers locally using the Stripe CLI. In either case, you have the option to choose the events your integration should subscribe to. There are many different events that can be triggered and receiving them all can easily overwhelm your system.

To create a webhook handler in ASP.NET Core, we will need to add a method to the Oasis Hubs project that can respond to HTTP POST requests and deserialize the Stripe event object contained in the request body. The code sample below shows an action method for a Controller but feel free to use minimal APIs or whatever your preference might be for handling HTTP requests.

[HttpPost("stripe/platform")]
public async Task<IActionResult> PlatformHandler() {
  var payload = await new StreamReader(Request.Body).ReadToEndAsync();
  try {
    var stripeEvent = EventUtility.ConstructEvent(
        payload, Request.Headers["Stripe-Signature"],
        this._stripeConfiguration.GetValue<string>("WebhookSecret"));

    switch (stripeEvent.Type) {
      case Events.InvoicePaid: {
        var invoice = (stripeEvent.Data.Object as Invoice)!;

        this._logger.LogDebug(
            "Initiating funds transfer for paid invoice ({InvoiceId})",
            invoice.Id);

        break;
      }
      default:
        _logger.LogInformation("Unhandled event type: {StripeEvent}",
                               stripeEvent.Type);
        break;
    }

    return Ok();
  } catch (StripeException ex) {
    _logger.LogError(ex, "There was an issue processing this webhook request");
    return BadRequest();
  }
}

Regardless of the language or framework used, most webhook handlers will follow in a similar sequence. First, attach a method to the route at which you’ll want to receive event notifications. Retrieve the event object from the request body and parse the JSON. Since these routes are usually publicly accessible, you will want to validate the request to make sure that it’s actually coming from Stripe. The Stripe.net library comes with a helpful utility that does just that. The EventUtility.ConstructEvent method will validate and deserialize the Event object of the webhook request if you pass it the JSON payload, the value of the Stripe-Signature request header, and the webhook secret associated with your Stripe account.

In addition to request validation, production implementations might also want to consider adding rate limiting or an allow/block list.

Now that you have a strongly typed Event object, you can inspect the Type property, look for any of the event types your integration is concerned with and run any applicable workflows. Notice how the Data.Object property can be cast to the Stripe object associated with the event type.

When creating your webhook handler, there are some behavioral constraints that you should be aware of. For instance, handlers should quickly return a successful (HTTP 200) response once an event is received. Executing long running tasks within the body of your handler is not recommended as that may cause timeouts and Stripe will attempt to resend the event. This retry behavior involves an exponential backoff but does vary between live and test modes. Because of this, it is a good idea for you to implement some logic for deduplicating events or making your event processing idempotent.

A common solution for scaling webhook event processing is to make use of an external queuing system like Azure Service Bus or RabbitMQ. When events are received and validated, the webhook handler will publish a message to a queue on the message broker, and another process listening to that queue can start processing the messages. This allows the webhook handler to do very little work and return quickly. This also enables some scalability as additional listener processes can be added if queued messages need to be processed more quickly. In the .NET space, there are many options to choose from when it comes to message processing frameworks. MassTransit, NServiceBus, and Wolverine are some interesting examples. In the codebase for Oasis Hubs, we’re using an OSS messaging framework called Brighter along with RabbitMQ as the message broker.

When working with subscription based payments, there are many events that get triggered for a business to pay attention to. A few of them include:

• customer.subscription.created - triggered when a new subscription gets created
• customer.subscription.deleted - triggered when a subscription ends
• invoice.created - triggered when a new invoice gets created for a payment period
• invoice.paid - triggered when the invoice is successfully paid
• invoice.payment_failed - triggered when a payment attempt for an invoice fails

This is far from a complete list of the events that are involved in a subscription, but also keep in mind that a typical integration might only need to address a handful of these. For Oasis Hubs, we specifically focus on the customer.subscription.created, customer.subscription.updated and invoice.paid events.

switch (stripeEvent.Type) {
  case Events.InvoicePaid: {
    var invoice = (stripeEvent.Data.Object as Invoice)!;

    await this._commandProcessor.PostAsync(
        new InitiateFundsTransferCommand(invoice));
    break;
  }
  case Events.CustomerSubscriptionCreated: {
    var newSubscription = (stripeEvent.Data.Object as Subscription)!;

    await this._commandProcessor.PostAsync(
        new ActivateCustomerSubscriptionCommand(newSubscription));

    break;
  }
  case Events.CustomerSubscriptionUpdated: {
    var updatedSubscription = (stripeEvent.Data.Object as Subscription)!;

    await this._commandProcessor.PostAsync(
        new ActivateCustomerSubscriptionCommand(updatedSubscription));

    break;
  }
  default:
    _logger.LogInformation("Unhandled event type: {StripeEvent}",
                           stripeEvent.Type);
    break;
}

The sample above shows a slimmed down version of the actual implementation, but the core pattern is the same. Check the event type, cast the event object to its actual type, and then send a message to the queue. Instead of having to work directly with strings, the Stripe .NET library provides an Events class that contains constant string representations for all the event types. It’s definitely saved me time from having to debug typos in my webhook handlers.

To locally test your webhook integration, the Stripe CLI has two commands that are particularly useful. When running a project on localhost, you’ll want to be able to capture Stripe events in your local instance so you can inspect things with your debugging tools. In the command line, you can run “stripe listen --forward-to ”, supplying it with the local URL to forward the test mode events to. Here’s an example using the CLI command with the action method shown earlier.

stripe listen --forward-to http://localhost:5000/api/webhooks/platform

Now that you have a listener, you’ll want to trigger some test events. You can do this by interacting with objects through Stripe Dashboard or by triggering them manually using the CLI trigger command.

stripe trigger invoice.paid

Connected Events

Working with Stripe Connect accounts adds an interesting dynamic to handling events. If the main Stripe account has multiple connected accounts attached to it, each with their own activities occurring, how can we know who the trigger event belongs to? Luckily, we already have 90% of the setup already done. When registering your webhooks in the Stripe Dashboard, set the listen to option to “Events on Connected accounts”.

With the Stripe CLI, you can add the “--forward-connect-to” switch to the listen command.

stripe listen --forward-to http://localhost:5000/api/webhooks/platform --forward-connect-to  http://localhost:5000/api/webhooks/connect

A recommended approach, and how Oasis Hubs has been integrated, is to have separate webhook endpoints for regular account events and Connect events. This greatly helps with simplifying the logic of your handlers and makes the code more readable. In Oasis Hubs, for example, we look out for the account.updated events to get notified when a new connect account successfully completes onboarding. You can also look out for the account.application.deauthorized as well to know when a Connect account disconnects from your platform.

When handling Connect events, it is expected that there will be multiple Connect accounts associated with your application so it is important to know which account triggered the event. Conveniently, each event generated by a Connect account also contains a top-level “account” property that contains the id for the source account. Now, any actions run in response to Connect events will be able to operate in the correct context.

References

• Oasis Hubs GitHub Repository
• Stripe Connect
• Stripe Connect guide
• Stripe Connect Account Types
• Stripe CLI

Stay connected with Stripe

You can also stay up-to-date with Stripe developer updates on the following platforms:

📣 Follow @StripeDev on Twitter. 📺 Subscribe to our YouTube channel. 💬 Join the official Discord server. 📧 Sign up for the Developer Digest.

In this series of blog posts, we’ll explore some key highlights for a modest implementation of a Stripe integration that brings together the capabilities of Stripe Connect and Stripe Billing for a fictitious business, Oasis Hubs.

This "Airbnb for co-working spaces" business provides customers with access to unique private and commercial workspaces that can be conveniently booked for a given number of hours. Customers will be able to choose between different subscription tiers that will give them access to various workspace listings (hubs) which have been provided by the service vendors (hosts). Hosts will sign up to the platform to provide details of their available workspaces, and get paid monthly based on the number of hours booked for their workspace.

Throughout this series, we will cover topics such as setting up Stripe Connect Onboarding, managing Stripe events, implementing metered billing, and validating subscription logic with test clocks. You can find a link to the demo code for this series in the reference links below.

Get Connect(ed)

Before hosts can begin posting their workspace listings and getting paid for bookings, they first need to get signed up for an Oasis Hubs account and then go through host onboarding. For sign ups, we’ll see how to make use of ASP.NET Core Identity with a custom model to store some additional data.

What about onboarding though? Hosts need to be able to connect their business to Oasis Hubs in a compliant way before they can start getting paid for the usage of their workspaces. Since Oasis Hubs is already using Stripe to handle payments, we’ll use Stripe Connect to connect (see what I did there) the hosts with Oasis Hubs’ Stripe account so that payments from customers and to hosts can be handled in the same platform.

If you are unfamiliar with Stripe Connect, you can think of it as a solution that allows businesses to process payments and route those payments between multiple providers. This makes Stripe Connect an interesting choice for businesses that operate marketplaces or offer franchising opportunities. For our use case, the hosts will be the service providers for Oasis Hubs. As payments are processed by the main business, various amounts can be distributed between the respective providers.

There are a few things that need to happen first before Oasis Hubs, or even your own business, can start their Stripe Connect integration. Through the Stripe dashboard:

• Make sure the Stripe account has been activated

• Register the Stripe account for Connect

• Optionally, configure a payout schedule

A host will have to be associated with one of three Stripe Connect account types; Standard, Express and Custom. Choosing between one account type versus another really depends on the experience you want your users to have and also the available engineering resources to execute the integration. As you can probably tell from the title, this article and the rest of the series will focus on the usage of Express accounts. With this option, your integration effort is fairly low and Stripe handles all of the onboarding, account management, and identity verification for Oasis Hubs. This allows Stripe to gather any KYC (Know Your Customer) requirements enforced by global financial regulators. However, this choice also means that Oasis Hubs will have to be responsible for handling refunds, disputes, and providing customer support. If you’re interested in learning more about the other account types, I recommend taking a look at some of the references linked at the end of this article.

Signing up

For some background, Oasis Hubs is built on .NET 7 using a combination of ASP.NET Core Razor Pages, Entity Framework Core, Tailwind UI and some other interesting components that will be explored across this series. As mentioned earlier, ASP.NET Core Identity needs to be set up to handle the customer sign ups so the following NuGet packages will need to be added to the project.

• Microsoft.AspNetCore.Identity.EntityFrameworkCore

• Microsoft.EntityFrameworkCore.SqlServer

• Stripe .NET

Once the packages are installed, we will move forward with creating the custom model for the user. ASP.NET Core Identity comes bundled with an IdentityUser class that has some predetermined fields like UserName, Email, PhoneNumber, etc. In Oasis Hubs, the same user type will be used for both hosts and customers. In the image below, OasisHubUser extends IdentityUser with fields that will be used later on.

public class OasisHubsUser : IdentityUser {
   public string StripeCustomerId { get; set; }
   public string StripeAccountId { get; set; }
   public string ActiveSubscriptionId { get; set; }
   public bool IsHost { get; set; }
   public bool HasSubscriptionActive { get; set; }
   public bool IsEnabled { get; set; }
   public virtual ICollection<IdentityUserClaim<string>> Claims { get; set; }
}

Here is a listing of the custom properties that will need to be added to the model. Their usage will be covered as we progress through the series.

• StripeCustomerId - Id for the Stripe Customer object associated with this user

• StripeAccountId - Id of the Stripe Express account for a host. Shouldn’t be set for a regular user

• ActiveSubscriptionId - Id of the most recent Stripe Subscription for a user

• HasSubscriptionActive - Set to true if user has an active subscription

• IsHost - Set to true if the user is a host, false if they’re a regular user.

• IsEnabled - Set to true if a user is in good standing and allowed to log in

ASP.NET Core Identity (Identity) has support for using Entity Framework Core (EF Core) for data storage through the IdentityDbContext type. To make the EF Core and Identity aware of the OasisHubUser model, IdentityDbContext needs to be extended as well.

public class OasisHubsDbContext : IdentityDbContext<OasisHubsUser> {
   public OasisHubsDbContext(DbContextOptions<OasisHubsDbContext> options)
       : base(options) {
   }
}

Now that this is done, Identity and the customer EF Core class needs to be registered in the service collection for ASP.NET Core.

services.AddPooledDbContextFactory<OasisHubsDbContext>(options =>
 options.UseSqlServer(config.GetConnectionString("OasisHubsSQLServer"),
    opts => opts.EnableRetryOnFailure()));

services.AddIdentity<OasisHubsUser, IdentityRole>(options => {
    options.User.RequireUniqueEmail = true;
  })
 .AddDefaultTokenProviders()
 .AddEntityFrameworkStores<OasisHubsDbContext>();

The code above adds the custom IdentityDbContext and wires up Identity with ASP.NET Core with some custom password settings. While we’re here, why not register the Stripe client as well.

StripeConfiguration.ApiKey = config.GetValue<string>("SecretKey");

var appInfo = new AppInfo { Name = "Oasis Hubs", Version = "0.1.0" };
StripeConfiguration.AppInfo = appInfo;

services.AddHttpClient("Stripe");
services.AddTransient<IStripeClient, StripeClient>(s => {
     var clientFactory = s.GetRequiredService<IHttpClientFactory>();

     var sysHttpClient = new SystemNetHttpClient(
        httpClient: clientFactory.CreateClient("Stripe"),
        maxNetworkRetries: StripeConfiguration.MaxNetworkRetries,
        appInfo: appInfo,
        enableTelemetry: StripeConfiguration.EnableTelemetry);

     return new StripeClient(apiKey: StripeConfiguration.ApiKey, httpClient: sysHttpClient);
});

The code above isn’t absolutely necessary but it does provide a more elegant way of injecting an instance of StripeClient that works alongside HttpClientFactory.

With all this in place, we can move on to creating the sign up page. For the sake of brevity, we’ll focus on the Razor Page PageModel and not the html form markup.

The sign up form is fairly simple; three fields and a button.

public class SignUpModel : PageModel {
   private readonly UserManager<OasisHubsUser> _userManager;
   private readonly SignInManager<OasisHubsUser> _signInManager;
   private readonly IStripeClient _stripeClient;
   private readonly ILogger<SignUpModel> _logger;

   [BindProperty] [Required] public string Name { get; set; }

   [BindProperty]
   [Required]
   [EmailAddress]
   public string Email { get; set; } 

   [BindProperty]
   [Required]
   [DataType(DataType.Password)]
   public string Password { get; set; }

   [TempData] public string ErrorMessage { get; set; }

   public SignUpModel(UserManager<OasisHubsUser> userManager,
      SignInManager<OasisHubsUser> signInManager,
      IStripeClient stripeClient,
      ILogger<SignUpModel> logger) {
      this._userManager = userManager;
      this._signInManager = signInManager;
      this._stripeClient = stripeClient;
      this._logger = logger;
   }

The PageModel that serves the sign up page is set up to bind to the html form properties, and it also gets injected with some of the services that we registered earlier like the StripeClient and Identity services.

   public async Task<IActionResult> OnPostAsync() {
      if (ModelState.IsValid) {
         var customerService = new CustomerService(_stripeClient);
         var customers = await customerService.ListAsync(new() { Email = Email });

         if (customers.Any()) {
            ErrorMessage = "An account with that email already exists.";
            return Page();
         }

         var options = new CustomerCreateOptions { Name = Name, Email = Email };

         var newCustomer = await customerService.CreateAsync(options);
         var newUser = new OasisHubsUser {
            UserName = Email,
            Email = Email,
            EmailConfirmed = true,
            StripeCustomerId = newCustomer.Id
         };

         var createResult = await _userManager.CreateAsync(newUser, Password);
         if (createResult.Succeeded) {
            await _userManager.AddClaimAsync(newUser, new Claim(ClaimsConstants.OASIS_USER_TYPE, "customer"));
            await _signInManager.SignInAsync(newUser, isPersistent: false);
            return RedirectToPage("/Index");
         }

         this._logger.LogWarning("Unable to create user");
         foreach (var error in createResult.Errors) {
            ModelState.AddModelError(string.Empty, error.Description);
         }
      }

      return Page();
   }

When the form is submitted and the post handler fires, a few things happen on the backend.

First, the form fields get validated. Once that is successful, an instance of Stripe’s CustomerService is created and is passed the injected StripeClient.

The CustomerService is used to create a customer object in the Oasis Hub Stripe account for the newly registered user. Every Oasis Hub user will have a Stripe customer object created for them with the Oasis Hubs Stripe account regardless if they are a host or not. This is so that we can take account of the participants on both sides of a payment. After the customer object is created, the Id is attached to the OasisHubsUser which is then stored in the Identity database and the user is signed in.

If you’re interested in seeing the sign in/out page implementations, take a look at the linked Github repository below.

Host Onboarding

At this point, users are able to register and sign in to Oasis Hubs, but they still need to be onboarded before they can become hosts.

Once an authenticated user navigates to the host sign up page and clicks the “Become a Host” button, the OnPostAsync handler for the HostSignUpModel PageModel model gets invoked. There’s a few things going on here so let’s break it up.

var acOptions = new AccountCreateOptions {
   Country = "US",
   Type = "express",
   Email = currentUser.Email,
   Company =
     new AccountCompanyOptions {
        Name = companyName,
        Structure =
          "single_member_llc"
     },
   Capabilities =
     new AccountCapabilitiesOptions {
        UsBankAccountAchPayments =
          new AccountCapabilitiesUsBankAccountAchPaymentsOptions { Requested =
                                                                     true },
        LinkPayments =
          new AccountCapabilitiesLinkPaymentsOptions { Requested = true },
        CardPayments =
          new AccountCapabilitiesCardPaymentsOptions { Requested = true },
        Transfers = new AccountCapabilitiesTransfersOptions { Requested = true }
     },
   BusinessType = "company",
   BusinessProfile =
     new AccountBusinessProfileOptions {
        Name = companyName,
        Mcc = "6513", // https://stripe.com/docs/connect/setting-mcc#list
        ProductDescription = "Remote work rental space",
        SupportEmail = currentUser.Email
     },
   TosAcceptance =
     new AccountTosAcceptanceOptions { ServiceAgreement = "full" },
   Metadata = new Dictionary<string, string> { ["owner.customer.id"] =
                                                 currentUser.StripeCustomerId }
};
var accountService = new AccountService(this._stripeClient);
var newExpressAccount = await accountService.CreateAsync(acOptions);

First, the user record is retrieved and then an Express account is created using the Stripe AccountService class. The express account represents the host’s business that they wish to connect to the primary Oasis Hubs business. In Stripe terminology, we call the primary business the “platform" account and the host account would be known as a “connected account”.

The majority of the code here is prefilling some account information to help speed up the onboarding process for the user. For example, it sets the account type, country, business type, support email, and some metadata. It even requests that the account have certain capabilities such as the ability to take payments from US bank accounts, credit cards, or Link.

As we request more capabilities, Stripe will ensure that the hosts provide all of the KYC information required to enable each one.

// update Stripe customer with express account Id
var cuOptions = new CustomerUpdateOptions {
   Metadata = new Dictionary<string, string> { ["host.account.id"] =
                                                 newExpressAccount.Id }
};
var customerService = new CustomerService(this._stripeClient);
await customerService.UpdateAsync(currentUser.StripeCustomerId, cuOptions);

// Link account to platform
var basePageUri = _linkGenerator.GetUriByPage(this.HttpContext, "/Index");
var alcOptions =
  new AccountLinkCreateOptions { Account = newExpressAccount.Id,
                                 RefreshUrl = $"{basePageUri}/hosts/refresh",
                                 ReturnUrl = $"{basePageUri}/hosts/complete",
                                 Type = "account_onboarding",
                                 Collect = "eventually_due" };

var accountLinkService = new AccountLinkService(_stripeClient);
var acLink = await accountLinkService.CreateAsync(alcOptions);
return Redirect(acLink.Url);

All that’s left now is to redirect the user to Stripe’s hosted onboarding for the Express account that was just created. To do that, we have to make use of another service. Using the AccountLinkService, we provide the Id for the Express account, set the Type to “account_onboarding”, and also set Collect to “eventually_due” to collect as much company information as necessary during onboarding. Also notice that the RefreshUrl and ReturnUrl properties are set all well. These create links back to the Oasis Hubs site to either refresh the onboarding session or redirect the user once onboarding is successfully completed.

The create account link will contain a URL property that can be used to redirect the user to the hosted onboarding experience.

After the user completes the onboarding process, they should be redirected to the Oasis Hubs main site. In the background, Stripe will process and verify the collected information. Throughout the onboarding and verification process, Stripe will fire webhook events associated with the Oasis Hubs account that should be monitored to check the current status. For onboarding, the account.updated event will tell us if and when the business was verified and can start accepting pay outs. Now we can move forward to handle other concerns like invoicing, handling webhook events and testing.

Summary

Hopefully at this point, you have a better understanding of the considerations that need to be made when integrating Stripe Connect into an ASP.NET Core application. We've covered everything from custom Identity models, creating various stripe objects, and working with Express connect accounts.

In the next post in this series, we will discuss handling webhooks for connected accounts and take a look at some key events that we should pay attention to.

References

• Oasis Hubs GitHub Repository

• Stripe Connect

• Stripe Connect guide

• Choose your Connect account type

• Know Your Customer (KYC)

In the episode, Rich is joined by Sourabh who explains to us the importance of gathering application diagnostics and also gives us a demo of how to run dotnet-monitor in Kubernetes.

• Introducing dotnet-monitor
• .NET Diagnostics on GitHub
• Collect diagnostics in containers
• What diagnostic tools are available in .NET Core?

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

In this episode, Ismael talks to us about the issues around getting proper insurance coverage in the Dominican Republic. He also shares with us how .NET and Azure are enabling them to provide the solutions around this effort.

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

In this episode, Scott chats with Andres Pineda about getting started with open source and how he helped kickstart the .NET user groups in the Dominican Republic.

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

Useful Links

• .NET Meetups and User groups
• Become a social Developer
• Caribbean Developers Conference

In this episode, we chat with Raul at the Caribbean Developers Conference to learn how he's using technology to improve the lives of the people in this country.

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

Useful Links

• Getting started with ML .NET
• Get started with .NET
• Machine Learning in Azure

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

Useful Links

• Azure Event Hubs Documentation

• GitHub repo with samples

• Enable reliable messaging for Big Data applications using Azure Event Hubs

• Choose between Azure messaging services

• Azure IoT Documentation

• Send events to or receive events from Azure Event Hubs using .NET Core

• Microsoft.Azure.EventHubs NuGet package

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

Useful Links

• What is Azure Service Bus
• Choose between Azure messaging services
• Messaging Patterns
• Azure Service Bus Samples

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

Useful Links

• What is Azure Service Bus
• Choose between Azure messaging services
• Messaging Patterns

This concept is known as bindings, and with it you can interact with various external services as inputs or outputs to your serveless function. Of course, bindings are optional, and a function might have one or multiple input and/or output bindings.

Out of the box, Azure Functions provides a variety of supported bindings. These allow you to easily integrate with services like Twilio, Azure Service Bus, SendGrid, Cosmos DB, or even HTTP.

However, what if you want to create a binding to a service that's not in the list of supported bindings? This might be a 3rd party service that your company relies on or maybe even an internal service you created.

This is was such a common question that we decided to ask our friend Matías Quaranta to join us on On .NET to show us exactly how we can create our own custom bindings for Azure Functions. Matias was also kind enough to provide a GitHub repository with step-by-step instructions that any of us may follow along with.

If you liked this video and would like to see some more of our .NET content, please subscribe to our .NET Developers YouTube Channel.

Useful Links

• Azure Functions triggers and bindings concepts
• Walkthrough and code samples

Azure Event Grid is a new managed service that was recently released for public review, so I thought I'd take some time out to give it try. It's essentially a cloud scale event routing service, which comes in pretty handy if you're building reactive applications. Publishers will be generating events on one side, handlers responding to events on the other side, and Event Grid in the middle making sure that your events are reliably delivered.

What's exciting about this new service, and probably where you'll get the most value, is how deeply it's integrated into the DNA of the Azure platform. Imagine being able to react to events that get fired when something changes in any of your Azure resources. You can opt in to be notified when a file gets added to Blob storage or a new user gets added to Azure AD. Then, you can have these events trigger an Azure Function App or kick off a serverless workflow with Azure Logic Apps. The combinations you can put together are virtually endless.

In this post, we're going to see what it takes to publish your own custom events to Event Grid. This will give us a good understanding of what's going on and how to incorporate this service into your code.

Creating an Event Grid Topic

The first thing that we'll do is create an Event Grid topic. Topics are where publishers send outgoing events to and where subscribers listen for incoming events.

To create a topic, you'll need the topic name, location and the resource group. In the Azure portal, you can search for and create an Event Grid Topic. If you have the Azure CLI installed, you can quickly create a topic on the command line.

az eventgrid topic create --name -l westcentralus -g

While the Event Grid is in preview, you'll have to create your topic in westus2 or westcentralus locations.

Defining custom events

Whether you're working with custom or built-in events, there are some manditory fields that you'll expect see in every event.

• Id - The unique ID for event.
• Subject - Any name or label that would have meaning for your application. This would be a good place to put the name of the service/entity that the event is related to.
• EventType - A value you can create filters against, e.g. CustomerCreated, BlobDeleted, HttpRequestReceived, etc.
• EventTime - The timestamp for when the event happened in the publisher.
• Data - Relevant information that's need to act on this event. This field is optional.

With topics, there is an implicit expectation from the subscriber that certain event types published to a given topic will adhere to a given schema. Think of the event type as contract between publisher and subscriber. If a Blob storage event fires, you might expect that there's some contextual information about the file that was altered.

Here's a simple class in C# that we'll use to model our custom events.

public class GridEvent where T : class { public string Id { get; set; } public string Subject { get; set; } public string EventType { get; set; } public T Data { get; set; } public DateTime EventTime { get; set; } }

Handling events with Azure Functions

The next thing we'll need to do is create an endpoint that will receive and process our custom event. Today, the Event Grid preview supports webhook endpoints.

Instead of creating a new Web app to capture the webhook requests, we'll just use Azure Functions. We'll create a function app with two functions in it. One will be attached to our filtered Event Grid subscription and the other to the unfiltered subscription.

To keep it simple, we'll use the same code for both functions. The following code is what I wrote for the demo.

using System.Net;

public static async Task Run(HttpRequestMessage req, TraceWriter log) { var data = await req.Content.ReadAsAsync>(); foreach(var item in data) { log.Info($"Event => {item.EventType} Subject => {item.Subject}\n"); } log.Info("-------Event data reviewed-------\n");

return req.CreateResponse(HttpStatusCode.OK); }

These functions were created using the HttpTrigger template. That will provide us with unique URL for each function. Keep note of those URLs since we'll need them when we create subscriptions.

Creating subscriptions

Subscriptions are what tell Event Grid what events on a topic that a subscriber would be interested in. When creating a subscription, you will need to provide an endpoint (the destination) to send the events to, and an optional set of filters.

For this post, we want to create two subscriptions; one with a filter and one without. We'll use the endpoints from the two functions we created above.

no filters

az eventgrid topic event-subscription create --name SubAll --endpoint --resource-group --topic-name

filters

az eventgrid topic event-subscription create --name SubFiltered --endpoint --resource-group --topic-name --included-event-types filteredEvent

These commands should complete fairly quickly, and now we'll have two subscriptions ready to receive events. Notice that the second call to the Azure CLI uses the --included-event-types flag to provide filters for the Event Grid topic. You can list out multiple event types separate by spaces.

Publishing events

With all this in place, we should be ready to send some events over to the topic. We will need the endpoint that was created for the topic and also the shared access signature (sas) key.

You can easily copy these from the Azure portal from the blade of the Event Grid topic. They can also be retrieved from the Azure CLI.

This command will return the topic endpoint along with some other basic information.

az eventgrid topic show --name custom-events -g netcore-eventgrid

This command will return the sas keys.

az eventgrid topic key list -g netcore-eventgrid -n custom-events

At this point, all that's left to do is to start issuing requests to the topic. The following code sets up an instance of HttpClient, creates the required headers, and sends a few events over to the topic.

string topicEndpoint = ""; string sasKey = "";

HttpClient client = new HttpClient(); client.DefaultRequestHeaders.Add("aeg-sas-key", sasKey); client.DefaultRequestHeaders.UserAgent.ParseAdd("democlient");

List> eventList = new List>(); for (int x = 0; x < 5; x++) { GridEvent testEvent = new GridEvent { Subject = $"Event {x}", EventType = (x % 2 == 0) ? "allEvents" : "filteredEvent", EventTime = DateTime.UtcNow, Id = Guid.NewGuid().ToString() }; eventList.Add(testEvent); }

string json = JsonConvert.SerializeObject(eventList); HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, topicEndpoint) { Content = new StringContent(json, Encoding.UTF8, "application/json") };

HttpResponseMessage response = await client.SendAsync(request);

You might have noticed that there's a simple toggle that alternates the values when the EvenType property is set. If you recall the subscriptions we created earlier, one of them included a filter for the filteredEvent event type. After running the code, we should see the event filtering work for our custom event.

Summary

Hopefully this post showed you how easy it was to get started with publishing and handling events in Azure Event Grid. Even though it's still in preview, the service looks very promising. I'm looking forward to seeing some of integrations that the product team and as well as the community end up creating.

If you'd like to hear more about the service, I've included some links below that you might find interesting.

• Azure Event Grid Documentation
• Azure Event Grid on the Cloud Cover show
• Exploring Azure Event Grid - Are Service Bus Topics Dead?

In this post, you'll see how you can integrate webpack into an ASP.NET Web Forms project where we will set it up to transpile and bundle some TypeScript code.

At the time of writing, the current version of webpack is at 3.2.0, TypeScript is at version 2.4.1, and I'm using NodeJS 7.2.1.

I'll be using Visual Studio 2017 with the free Web Essentials 2017 extension installed. If you you're doing any web development in Visual Studio and you haven't checked out Web Essentials yet, go install it now. You'll thank me later. While you're at it, make sure you have a current version of NodeJS installed and available on your path. We're going to start off with a new Web Forms project created using the default template in Visual Studio.

Installing Webpack and TypeScript

Webpack is a NodeJS package so we can install it using npm. If you don't feel like opening up the command line, Web Essentials adds a useful feature that makes installing packages fairly easy. If you use the shortcut SHIFT-ALT-0, it will open a package install dialog that can be used to work with front-end package managers. Just select npm from the drop down and enter the packages you want to install, i.e. webpack. While we're here, let's install the TypeScript package and the ts-loader package too.

Once that's completed, you should notice that a package.json file was added to your project. We'll come back to that later on.

Let's add some code

There's should be a Scripts folder that got created by default whenever you generated the Web Forms project. Inside that Scripts folder, add two sub folders named src and dist. The src is where the 'raw' TypeScript files are going to go and the transpiled JavaScript will go in dist. If you prefer to keep your TypeScript and JavaScript files together, that's totally fine. I prefer to separate them.

We'll add these two simple scripts below.

// greeter.ts export class Greeter { to: string; constructor(to: string) { this.to = to; } greet():string { return Hi ${this.to}!; } }

// main.ts import { Greeter } from './greeter';

let greeter: Greeter = new Greeter('Cecil'); let greeting: string = greeter.greet();

console.log(greeting);

At the root of the project, we'll also add a TypeScript configuration file (tsconfig.json) that we'll use to tweak the compiler settings. You can use the Add New Item dialog in Visual Studio to create one for you. Here are the settings I'll be using.

{ "compilerOptions": { "noImplicitAny": false, "noEmitOnError": true, "removeComments": false, "sourceMap": true, "target": "es5", "module": "commonjs", "moduleResolution": "node"
}, "exclude": [ "node_modules"
] }

Optional Visual Studio 2017 comes with some built in support for TypeScript. Since we're going to be using the version of webpack and TypeScript we installed via npm, you might want to turn the TypeScript build feature off. To do that, simply add a TypeScriptCompileBlocked element to a PropertyGroup in your .csproj file and give it a value of true.

Adding Webpack configuration

By default, webpack will look for a webpack.config.js file in the current directory. Since there's no template for creating the configuration file, we can just add one manually.

// webpack.config.js const path = require("path");

module.exports = { context: path.resolve(dirname, "./Scripts/src"), resolve: { extensions: ['.ts'] }, entry: { main: './main' }, output: { publicPath: '/Scripts/dist', path: path.resolve(dirname, './Scripts/dist'), filename: '[name].build.js' }, module: { rules: [ { test: /.ts$/, use: 'ts-loader', exclude: /node_modules/ } ] } };

Let's break down what's going on in this file.

• context - This sets the base directory where webpack should look for files. Here we're setting it to the "Script/src" folder we created earlier.
• resolve.extensions - This lists the file extensions webpack should use to resolve modules. In our example, we're only looking for .ts files.
• entry - This specifies the root modules for the application. In our case, main.ts is the root. Since it imports greeter.ts as a dependency, webpack will include both files when generating the bundle.
• output - Here is where we tell webpack to send the final bundles. If you look at the config above, the bundles will be sent to the Scripts/dist folder. The [name] token in the filename setting will be replaced with the name of our entry point, so we should expect a bundle with a name of main.build.js.
• module - Out of the box, webpack only knows how to work with JavaScript files. To add support for bundling TypeScript files, we'll need to add a loader. Earlier on we install the ts-loader via npm. Here we'll create a rule that states any .ts files should be loaded with the ts-loader.

The last thing we're going to do to get webpack building the .ts files is to add a simple build script to the package.json file. This file should have been added to the project when we installed the npm packages earlier.

{ "devDependencies": { "ts-loader": "^2.2.2", "typescript": "^2.4.1", "webpack": "^3.2.0" }, "scripts": { "build": "webpack" } }

If we were to run npm run build on the command line we should see some output resembling the following screenshot.

With Web Essentials 2017 installed, you can use the ALT-SPACE shortcut to quickly bring up a command prompt in your project directory.

Take a look inside of the dist folder and you should see the bundled main.build.js file. You will have to manually include this file in your Visual Studio project. In the Solution Explorer, enable Show All Files then you can just right-click the file and select Include in Project.

Bundle on build

Having to open a command prompt and run npm run build gets annoying after a while. What we can do instead is add a MSBuild task to have Visual Studio run our webpack build whenever we hit F5.

With this task added to our .csproj file, we'll have the TypeScript and Web Forms code building together.

Registering with the ScriptManager

The Web Forms project templates come with a BundleConfig.cs file that allows you to add mappings for your client side scripts. You can do things like specify the debug file, the production file, or even a CDN path if you have one.

We can add the webpack bundled file to the ScriptManager like this like this.

// RegisterBundles method in BundleConfig.cs ScriptManager.ScriptResourceMapping.AddDefinition("myscripts", new ScriptResourceDefinition { Path = "~/Scripts/dist/main.build.min.js", DebugPath = "~/Scripts/dist/main.build.js" });

..... ......

Wait a minute! We never generated a minified version of our bundle. Let's do that now.

Minifying Webpack bundles

Webpack has built-in support for minification, so we just need to turn it on. The way we do this is by adding a plugin called UglifyJsPlugin to the configuration file. Also, let's set this up so that the plugin is only run during release builds.

Here's what the updated webpack.config.js looks like.

const path = require("path"); const webpack = require("webpack");

module.exports = function (env) { const isProduction = env === 'prod';

return { context: path.join(dirname, "./Scripts/src"), resolve: { extensions: ['.ts'] }, entry: { main: './main' }, plugins: isProduction ? [new webpack.optimize.UglifyJsPlugin()] : [], output: { publicPath: '/Scripts/dist', path: path.join(dirname, './Scripts/dist'), filename: isProduction ? '[name].build.min.js':'[name].build.js' }, module: { rules: [ { test: /.ts$/, use: 'ts-loader', exclude: /node_modules/ } ] } } };

The first thing we did was get a reference to the webpack npm package. Remember, webpack.config.js is just a JavaScript file.

We changed the module.exports assigment from a JavaScript object to a function that returns a JavaScript object. This allows us to accept command line parameters that we'll use to set the build environment.

We added a plugins section to our configuration. Here we're toggling the UglifyJsPlugin on or off based on if we're in production mode or not. We're also doing something similar with the filename setting in the output section.

Next we'll update the package.json file to pass the environment settings to webpack.

{ "devDependencies": { "ts-loader": "^2.2.2", "typescript": "^2.4.1", "webpack": "^3.2.0" }, "scripts": { "build-dev": "webpack", "build-prod": "webpack --env=prod" } }

We now have two npm build scripts for generating bundles, so we'll have to update the .csproj file too if you want to maintain that F5 experience.

Now you can toggle between Debug and Release mode in Visual Studio, and MSBuild will kick off webpack to create your bundles.

One thing you might notice, is that the MSBuild tasks doesn't run if there haven't been any changes in your .NET code since the last successful build. You can get around this buy just running the npm scripts directly by firing up the command line or you can install the handy NPM Task Runner extension from Mads Kristensen.

Conclusion

ASP.NET Web Forms is still a viable option for creating web applications. In this post you saw how to integrate webpack into your projects. Hopefully you'll take that further and figure out how to incorporate other technologies like VueJS, Aurelia or React.

Setting up a project

I'm starting off with an out of the box, new ASP.NET MVC application. If you're using ASP.NET Web Forms then the process should be pretty much the same.

First, let's initialize a package.json file and add some npm packages. You will need to have node installed on your machine. You can grab an installer for your OS on their downloads page. Next, open up a command line prompt at the root of your project.

To get to the command prompt quickly in Visual Studio, I recommend installing Mads Kristensen's Open Command Line extension. I use it all the time.

After the package.json file is created, make sure you include it in your project. As you might already know, Visual Studio does not automatically add files that are placed in the project folder.

$ npm init $ npm install toastr --save

Here I'm just installing toastr, it's a handy little JavaScript library for going growl like notifications. In the Scripts folder, I'll create a simple script called app.js that'll create a notification.

toastr.info("this is just a test message");

Now, the toastr JavaScript and CSS files need to be added to the page. Currently, they've both been installed into the node_modules folder. Instead of referencing that path, I'll create a simple Gulp script that I can use to copy the toastr files out, and do any other processing I'd need for my site's front-end assets.

First, make sure that Gulp is installed on the machine and in the project.

$ npm install --global gulp-cli $ npm install --save-dev gulp gulp-concat

Now create the gulpfile.js file.

const gulp = require('gulp'); const concat = require('gulp-concat');

const paths = { nodeModules: './node_modules/', scriptsDest: './Scripts/', stylesDest: './Content/' };

gulp.task('copy:css', () => { const cssToCopy = [ ${paths.nodeModules}toastr/build/toastr.min.css ];

return gulp.src(cssToCopy)
.pipe(concat('vendor.css')) .pipe(gulp.dest(${paths.stylesDest})); });

gulp.task('copy:js', () => { const javascriptToCopy = [ ${paths.nodeModules}toastr/build/toastr.min.js ];

return gulp.src(javascriptToCopy) .pipe(concat('vendor.js')) .pipe(gulp.dest(${paths.scriptsDest})); });

gulp.task('default',['copy:css', 'copy:js'])

There are 2 simple Gulp tasks here. One to copy the CSS files to the Content folder and the other copies Javascript files to the Scripts folder. To keep it simple, only the toastr files are being copied over but you can add any other dependencies you've installed.

Running gulp on the command line returns some output that looks like this.

Since these generated files aren't a part of the project, Visual Studio won't show them in the Solution Explorer by default. At the top of the Solution Explorer, click on the Show All Files icon. You should see vendor.css and vendor.js greyed out under their respective folders. Right click on each file and choose Include In Project.

Now you can just reference the files in your Razor template (or MasterPage if you're working with Web Forms).

Excluding node_modules from the project

If you followed through the last section and didn't skip ahead, you might have noticed that we included package.json, vendor.js and vendor.css but not the node_modules folder. Simply, excluding the node_modules folder from the project will exclude it from the published web application.

Excluding node_modules via MSBUILD

You might have your own reasons why you want to include the node_modules folder in the project. In that case, you exclude node_modules (or any other folder) from being published by using the ExcludeFromPackageFolders element.

First you'll need to unload your project from the solution and edit the project file. Next add an ExcludeFromPackageFolders element to an ItemGroup element. Using the Include attribute, you can provide a semicolon-separated list of folders that you want to exclude. For now, we're only interested in the node_modules folder.

Note that we also include a FromTarget element in our setup. This is an optional element and is only really there for descriptive purposes.

Once that's done, we'll save the file and reload the project. Doing a publish should now exclude the node_modules folder even though it's included in the project.

Excluding files

With our current setup, the published output also includespackage.json and gulpfile.js. If you want to exclude these files from your published output, you can use a similar technique to the previous one using a ExcludeFromPackageFiles element. The Include property even supports globbing.

Now with all this in place, your NodeJS artifacts will not get included in your published web application.

Conclusion

If you're like me, you prefer to keep your published output at lean as possible. Excluding the node_modules folder can greatly reduce the size of your deployed web application.

In general, I prefer not to let my project file know about the node_modules folder at all. I find that projects load faster and I don't have to worry about ridiculously large commit messages in source control.