Stripe Provider Integration

How to get started with payment provider integrations.

Stripe

Installing the integration

• Install the Ucommerce.Payments.Stripe NuGet package.

• Add the Stripe integration to the program.cs file to use the default Stripe implementation:

Program.cs

        services.AddUcommerce()    
            .AddBackOffice()
            .AddPayments()
            .AddStripe()
        
        app.UseUcommerce()
            .UseBackOfficeUi()
            .UsePayments()
            .UseStripe("OptionalCallbackUri");

OptionalCallbackUri is the URI where the Stripe webhook should be pointed to later. If left without a value, the default endpoint will be:{yourDomain}/Stripe/process/callback

Stripe is now available as a payment method service. It can now be selected for new and existing payment methods.

Creating a Payment Method

• In the back office UI, navigate to Settings -> Payment Methods.

• Click New to create a new payment method.

• Select Stripe as the service.

All added services will show up in the Service tab

Configuring Stripe

Connect the payment method to a Stripe account by filling out the Service properties section in UI.

This is what the default payment service property editor looks like - it contains PublicKey, CancelUrl, SuccessUrl, SecretKey and WebhookSecret properties.

The service properties available will vary depending on the payment service selected.

Property	Description	Required
Public Key	The account-specific public key for the Stripe account. It can be found in the Stripe Developer Dashboard and starts with `pk_`.
Secret Key	The account-specific secret key for the Stripe account. It can be found in the Stripe Developer Dashboard and starts with `sk_`.
Webhook Secret	The webhook-specific key. It is set up in the Stripe Developer Dashboard on the webhooks page and starts with `whsec_`. If using a Local listener it is output from the `stripe listen --forward-to` command response
Success URL	The partial route that the user is navigated to on a successful purchase.
Cancel URL	The partial route that the user is navigated to on an unsuccessful purchase.

The keys can be found on the Stripe Developer Dashboard located here. When setting up the webhook, remember to point it to the webhook set on startup.

Once configured, the payment method can be enabled by flipping the Enabled toggle in the UI.

When testing the Stripe integration, the Stripe CLI can greatly help. It does not require a tunnel to use and can give better results when implementing a stripe payment provider as it allows you to test the payment flow E2E.

Understanding the integration

When you install the integration, and configure it in the back office, you then need to know what its GUID is to use in requesting a payment. This can be found in either the database ([dbo].[uCommerce_PaymentMethod]) or in the URL on the payment method page in the back office UI.

Payment method id in the URL

• Once you have created a cart, added an order line, added a shipping address and a billing address, you can then create a payment (see: Converting a cart to an order).

• The response will include a paymentUrl. Redirect the customer to this URL to complete payment with Stripe. On completion, the customer will be redirected to the SuccessUrl or CancelUrl depending on the outcome.

• Once payment is completed, Stripe will send a checkout.session.completed webhook event to the URL specified in .UseStripe("OptionalCallbackUri"), or to {yourDomain}/Stripe/process/callback if none has been configured.

• The Stripe webhook handler will reconcile the payment and move it into Authorized status. The Stripe implementation uses manual capture, so funds are not taken at this point. The checkout pipeline will also execute, converting the cart into an order with New Order status.

• When you are ready to capture the funds — for example, after the goods have been dispatched — move the order to Completed status via the back office. This triggers the capture of the funds and completes the checkout process.