> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/payments/integrations/providers/stripe.md).

# Stripe

Connect Stripe to Payments — keys, webhook URL and signing secret.

Stripe takes card, wallet and bank payments online and runs subscriptions. Norbix gets Stripe's webhook events (payments, refunds, disputes, invoices, subscriptions) and runs your triggers.

## Get your credentials

1. Sign in to the [Stripe Dashboard](https://dashboard.stripe.com/). Turn on **Test mode** first and repeat these steps in live mode when you go live (see [API keys](https://docs.stripe.com/keys)).
2. Open **Developers → API keys** and copy the **Publishable key** (`pk_test_…`) and the **Secret key** (`sk_test_…`, press **Reveal test key**).
3. Save the integration in Cloud once (below) to get its **Webhook URL**.
4. Open **Developers → Webhooks → Add endpoint**, paste the webhook URL, and select the events you want, for example `payment_intent.succeeded` and `charge.refunded` (see [Webhooks](https://docs.stripe.com/webhooks)). Open the new endpoint, press **Reveal** under **Signing secret** and copy it (`whsec_…`); the endpoint id (`we_…`) is shown at the top.
5. Paste the signing secret into **Webhook Signing Secret** in Cloud, type the secret key again, and press **Save**.

For a local or private test stack, the [Stripe CLI](https://docs.stripe.com/stripe-cli) can stand in for the dashboard endpoint: `stripe listen --forward-to <webhook URL>` prints a `whsec_…` for **Webhook Signing Secret**, and `stripe trigger payment_intent.succeeded` sends a test-mode event. Pay only with [Stripe's test cards](https://docs.stripe.com/testing) in test mode.

## Connect it in Cloud

**Where:** Payments → Integrations → **Add New Integration** → Stripe → **Connect** · `/projects/<project>/payments/integrations/new/stripe`

| Field                          | Required | What it does                                                                                                                                      | Example            |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Publishable Key                | yes      | Your Stripe publishable key, safe to use in client code.                                                                                          | `pk_test_…`        |
| Secret Key                     | yes      | Lets Norbix call Stripe. Secret; encrypted on save and never shown again — type it again whenever you press **Save**.                             | `sk_test_…`        |
| Webhook Signing Secret         | yes      | Checks that a webhook call really comes from Stripe. Secret; encrypted on save and never shown again — type it again whenever you press **Save**. | `whsec_…`          |
| Webhook Endpoint Id (optional) | no       | The id of the Stripe webhook endpoint, for your reference.                                                                                        | `we_…`             |
| Default currency (optional)    | no       | Three-letter currency code.                                                                                                                       | `EUR`              |
| Integration Name               | yes      | The name in your integrations list.                                                                                                               | `Stripe test mode` |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-e8133b50061bd6cc8430a8383bb1f6d46b657030%2Fstripe-form-1.png?alt=media" alt="New Stripe Integration form filled with example values"><figcaption><p>The filled form (placeholder values, the secret key is the test key of the stack).</p></figcaption></figure>

Press **Save**. The page turns into **Editing Stripe integration** with the badges **ENABLED**, **NOT TESTED**, **NOT CONFIRMED**, the integration id (`int_5Fg01ggCM3kAfgeSD1NMwV`) and the **Webhook URL** — `<Hub address>/v3/payments/webhooks/<account id>/<project id>/stripe/<integration id>`; outside PROD it ends with `?env=<ENV>`. Copy it with its copy button and paste it at Stripe (see **Get your credentials**). **Received webhooks** at the bottom lists every call Stripe makes to it.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-c884a4f3fcb79ed272a698966abd5c788f5eed4b%2Fstripe-saved-2.png?alt=media" alt="Editing Stripe integration after Save: ENABLED, NOT TESTED, NOT CONFIRMED, the integration id and the Webhook URL"><figcaption><p>After save: the webhook URL to paste at Stripe.</p></figcaption></figure>

Events Norbix accepts from Stripe (pick them at Stripe and in your [trigger](/codemash/cloud/payments/triggers/new.md)): `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `payment_intent.canceled`, `charge.refunded`, `charge.dispute.created`, `invoice.paid`, `invoice.payment_failed`, `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted`.

## Test and set as default

**Test integration** signs in to Stripe with the secret key. With the test key of this example it passed (**Connect — Success**); see [Test an integration](/codemash/cloud/payments/integrations/test.md). Two test-mode payments and one refund sent with the Stripe CLI were listed under **Received webhooks** with **200 — Processed.** and ran the payment triggers ([Create a trigger](/codemash/cloud/payments/triggers/new.md)). Payments has no default integration — every enabled integration gets its own calls ([Default integration](/codemash/cloud/payments/integrations/set-default.md)).

## Common errors

| Message                                                                     | Cause                                                                      | Fix                                                                                                       |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Stripe authentication failed for integration int\_… : HTTP 401 Unauthorized | Wrong or revoked secret key, or a live key on a test account.              | Copy the secret key again (same mode as the dashboard), type it, **Save**, test again.                    |
| **Received webhooks** shows **400**                                         | The webhook signing secret does not match the endpoint that sent the call. | Copy the **Signing secret** of exactly this endpoint, **Save**, then resend the event from the dashboard. |
| **Received webhooks** shows **409**                                         | The integration is disabled.                                               | **Actions → Enable**.                                                                                     |
| Required                                                                    | A required field is empty — secrets count too on every save.               | Fill the field; type every secret again before **Save**.                                                  |

## Do it from code

```ts
const { id } = await norbix.hub.payments.savePaymentsIntegration({
  integration: {
    provider: 'Stripe',
    integrationName: 'Stripe live',
    isEnabled: true,
    publishableKey: 'pk_live_your_publishable_key',
    secretKey: 'sk_live_your_secret_key',
    webhookSigningSecret: 'whsec_your_signing_secret',
    defaultCurrency: 'EUR',
  } as any, // the TS type knows only the shared fields
});
console.log(id); // int_…
```

```sh
norbix hub payments integration save --integration '{"provider":"Stripe","integrationName":"Stripe live","isEnabled":true,"publishableKey":"pk_live_your_publishable_key","secretKey":"sk_live_your_secret_key","webhookSigningSecret":"whsec_your_signing_secret","defaultCurrency":"EUR"}'
```

The client setup is on the [Payments page](/codemash/cloud/payments.md#use-it-from-code). API: [Save Payments Integration](/codemash/api-reference/payments/integrations/save-payments-integration.md)