---
title: "Stripe integration · RUAL Documentation"
description: "Use Stripe in RUAL blueprints. Create checkout sessions, customers, invoices, credit notes and subscriptions, with the secret key held by a service provider."
canonical: https://docs.rual.nl/integrations/stripe
language: en
---

# Stripe

Create checkout sessions, customers, invoices, credit notes and subscriptions, with the secret key held by a service provider.

> **Credentials** Create a [service provider](https://docs.rual.nl/blueprints/service-providers) for this service and point the blocks at it. The cluster holds the key, so it never sits on a pin or in a blueprint export.

## Guides

- [Service Providers](https://docs.rual.nl/blueprints/service-providers)

- [Tutorial: A Small Webshop](https://docs.rual.nl/web/build-a-shop)

## Blocks

Add these blocks on the canvas by searching for their name. Each block page lists its pins and how it behaves.

- [connect `function_create_stripe` Opens a Stripe connection. Point it at a Stripe service provider so the secret key stays in the provider store and never appears in this blueprint : the API key pin is the older way and leaves the key readable to anyone who can open the flow.](https://docs.rual.nl/block-types/stripe/function_create_stripe)

- [create checkout `stripeconnection_checkout_create` Creates a Stripe Checkout Session and returns the url of Stripe's hosted payment page to redirect the customer to : or, with ui mode set to embedded, a client secret for mounting Checkout inline on your own page. No card data reaches this cluster. Either wire line_items, or give amount + product name for a one-off price that needs nothing set up in Stripe first.](https://docs.rual.nl/block-types/stripe/stripeconnection_checkout_create)

- [get checkout `stripeconnection_checkout_get` Reads back a Checkout Session to answer did they pay. Branch on the paid pin, not on status : a session reaches status complete in subscription and setup modes where no money moved at all.](https://docs.rual.nl/block-types/stripe/stripeconnection_checkout_get)

- [create credit note `stripeconnection_credit_notes_create` Credits a customer against an invoice : the accounting way to give a subscriber a month back without refunding their card. credit_balance (the default) puts the amount on their Stripe balance so it comes off their next invoice; refund also sends the money back; out_of_band just records that you settled it elsewhere. The invoice id comes off get subscription as latest invoice id, or off list invoices.](https://docs.rual.nl/block-types/stripe/stripeconnection_credit_notes_create)

- [create customer `stripeconnection_customers_create` Creates the Stripe customer that saved cards, subscriptions and invoices hang off. Stripe enforces no uniqueness : creating this twice for one person gives them two billing histories and two sets of saved cards, so wire an idempotency key from your own user GUID.](https://docs.rual.nl/block-types/stripe/stripeconnection_customers_create)

- [get customer `stripeconnection_customers_get` Reads a Stripe customer. A customer deleted in Stripe comes back as a tombstone rather than an error : this block reports that as CUSTOMER_DELETED instead of handing back an almost-empty object that looks live.](https://docs.rual.nl/block-types/stripe/stripeconnection_customers_get)

- [list invoices `stripeconnection_invoices_list` The billing history for a customer or a subscription, newest first. Set at least one of the two filters : unfiltered this would walk the whole account. The latest invoice pins are the shortcut for "credit their last month".](https://docs.rual.nl/block-types/stripe/stripeconnection_invoices_list)

- [cancel payment `stripeconnection_paymentintents_cancel` Cancels a payment that has not completed. A payment that already succeeded cannot be cancelled : refund it instead.](https://docs.rual.nl/block-types/stripe/stripeconnection_paymentintents_cancel)

- [create payment `stripeconnection_paymentintents_create` Creates a PaymentIntent : the route for a custom card form, where the page confirms with Stripe.js using the client secret. For a hosted payment page use create checkout instead. Also the way to charge a card already on file, with off session.](https://docs.rual.nl/block-types/stripe/stripeconnection_paymentintents_create)

- [get payment `stripeconnection_paymentintents_get` Answers did this payment succeed, and what did they pay with. The payment method pins come off the charge, so they report the method actually used rather than the ones that were offered.](https://docs.rual.nl/block-types/stripe/stripeconnection_paymentintents_get)

- [list payment methods `stripeconnection_paymentmethods_list` The cards and mandates a customer has saved, for a "pay with a card on file" screen. Each entry carries a label so a picker can be rendered without digging through the nested object.](https://docs.rual.nl/block-types/stripe/stripeconnection_paymentmethods_list)

- [create refund `stripeconnection_refunds_create` Sends money back to whatever the customer paid with. Leave amount empty to refund the whole payment. This is one of the two ways to credit someone : it moves real money out of the account. The other is create credit note, which settles against a future invoice instead.](https://docs.rual.nl/block-types/stripe/stripeconnection_refunds_create)

- [cancel subscription `stripeconnection_subscriptions_cancel` Cancels a subscription. By default at the end of the paid-for period: the customer keeps their access until it runs out, the subscription stays active with cancels at period end set, and resume subscription undoes it. Tick immediately to stop access now : that is irreversible, and unless prorate is set the customer is not credited for the unused time.](https://docs.rual.nl/block-types/stripe/stripeconnection_subscriptions_cancel)

- [create subscription `stripeconnection_subscriptions_create` Starts recurring billing for a customer who already has a payment method on file. To collect the card and subscribe in one step, use create checkout in subscription mode instead.](https://docs.rual.nl/block-types/stripe/stripeconnection_subscriptions_create)

- [get subscription `stripeconnection_subscriptions_get` Reads a subscription : whether it is active, when the paid-for period ends, and whether it is set to run out. Also where the latest invoice id a credit note needs comes from.](https://docs.rual.nl/block-types/stripe/stripeconnection_subscriptions_get)

- [resume subscription `stripeconnection_subscriptions_resume` Renews a subscription that was going to stop: clears cancels at period end, and lifts a pause if one is set. A subscription that has already ended cannot be resumed by anything : the block says so rather than failing obscurely, and a new subscription has to be created.](https://docs.rual.nl/block-types/stripe/stripeconnection_subscriptions_resume)

- [update subscription `stripeconnection_subscriptions_update` Upgrades, downgrades or re-quantities a subscription. proration behaviour decides what happens to the part of the term already paid for: create_prorations credits the unused time and bills the new plan pro rata on the next invoice, always_invoice bills it straight away, none leaves the customer on the old amount until the term ends. Changing the plan needs the subscription item's id, which this block looks up for you when you give a price id.](https://docs.rual.nl/block-types/stripe/stripeconnection_subscriptions_update)

- [verify webhook `stripeconnection_webhook_verify` Proves an incoming webhook really came from Stripe, and unpacks the event. Wire the raw request body into payload : a body that has been parsed into an object and re-encoded will never verify, because the signature covers the exact bytes Stripe sent. Without this block an endpoint acts on anything POSTed to a URL that appears in the Stripe dashboard, the blueprint and every log it passed through.](https://docs.rual.nl/block-types/stripe/stripeconnection_webhook_verify)

## Next steps

- [Third-Party Integrations](https://docs.rual.nl/tutorials/third-party-integrations): Calling outside APIs, receiving their webhooks, keeping data in sync and handling failures.

- [All integrations](https://docs.rual.nl/integrations): Everything RUAL connects to, by what it is for.