> For the complete documentation index, see [llms.txt](https://dev.ucommerce.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.ucommerce.net/readme/payment-providers/stripe-provider-integration.md).

# Stripe Provider Integration

## 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:

{% code title="Program.cs" %}

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

{% endcode %}

{% hint style="warning" %}
`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`
{% endhint %}

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.

<figure><img src="/files/Agr1L5SyL0819dzePwd2" alt="" width="446"><figcaption><p>All added services will show up in the <em>Service</em> tab</p></figcaption></figure>

### Configuring Stripe

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

<figure><img src="/files/maFgqPMZCb5P5OxnKTSr" alt="" width="563"><figcaption><p>This is what the default payment service property editor looks like - it contains <em>PublicKey</em>, <em>CancelUrl</em>, <em>SuccessUrl</em>, <em>SecretKey</em> and <em>WebhookSecret</em> properties.</p></figcaption></figure>

{% hint style="info" %}
The service properties available will vary depending on the payment service selected.
{% endhint %}

<table><thead><tr><th>Property</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td>Public Key</td><td>The account-specific public key for the Stripe account. It can be found in the Stripe Developer Dashboard and starts with `pk_`.</td><td>true</td></tr><tr><td>Secret Key</td><td>The account-specific secret key for the Stripe account. It can be found in the Stripe Developer Dashboard and starts with `sk_`.</td><td>true</td></tr><tr><td>Webhook Secret</td><td>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</td><td>true</td></tr><tr><td>Success URL</td><td>The partial route that the user is navigated to on a successful purchase.</td><td>true</td></tr><tr><td>Cancel URL</td><td>The partial route that the user is navigated to on an unsuccessful purchase.</td><td>true</td></tr></tbody></table>

{% hint style="warning" %}
The keys can be found on the Stripe Developer Dashboard located [here](https://dashboard.stripe.com/). When setting up the webhook, remember to point it to the [webhook set on startup](#installing-the-integration).
{% endhint %}

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

{% hint style="info" %}
When testing the Stripe integration, the [Stripe CLI](https://stripe.com/docs/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.
{% endhint %}

### 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.

<figure><img src="/files/PsFXJ1vkCiu49ZdCw1Rj" alt="" width="446"><figcaption><p>Payment method id in the URL</p></figcaption></figure>

* 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](https://github.com/Ucommercenet/ucommerce-docs/blob/main/ucommerce-next-gen/headless/reference/cart/README.md#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.