Stripe App Storefront Integration
This page shows how to accept Stripe payments in a Saleor storefront with the Stripe App, using Stripe’s Payment Element.
Integrate with your coding agent
The fastest way to integrate is to let your coding agent do it. The prompt walks the agent through the API calls, the data shapes, the outcomes, idempotency, and the error codes, links these docs as the source of truth, and asks it to test the result with Stripe test cards.
Stripe integration prompt
Paste it into your coding agent from your storefront project.
Integrate Stripe payments into this Saleor storefront's checkout using the Saleor Stripe App.
The docs below are the source of truth. Read them before writing code, and follow them if anything here disagrees:
- Storefront integration: https://docs.saleor.io/developer/app-store/apps/stripe/storefront-integration.md
- Request data shapes: https://docs.saleor.io/developer/app-store/apps/stripe/webhooks.md
- Supported payment methods: https://docs.saleor.io/developer/app-store/apps/stripe/supported-payment-methods.md
- Errors: https://docs.saleor.io/developer/app-store/apps/stripe/errors.md
How it works:
- The storefront renders Stripe's Payment Element (@stripe/stripe-js, plus @stripe/react-stripe-js in React) and confirms the payment with Stripe.js. Saleor calls the Stripe App, and the app creates the PaymentIntent in Stripe. The storefront never calls Stripe's API with a secret key and never handles raw card data.
- The payment gateway ID is `saleor.app.payment.stripe`. The flow is: paymentGatewayInitialize, transactionInitialize, stripe.confirmPayment, then transactionProcess and checkoutComplete on the page Stripe returns to.
- All calls below use the Saleor storefront GraphQL API and work for guests.
Build the payment step:
1. Check the app. Query the checkout's availablePaymentGateways { id } and offer Stripe only if `saleor.app.payment.stripe` is listed.
2. Initialize the gateway. Call paymentGatewayInitialize(id: <checkout ID>, paymentGateways: { id: "saleor.app.payment.stripe" }, amount: <checkout total>) and read gatewayConfigs[0].data.stripePublishableKey. Check gatewayConfigs[].errors and errors first.
3. Render the Payment Element. Call loadStripe(<publishable key>) once and create Elements in deferred mode: { mode: "payment", amount: <checkout total in the currency's smallest unit>, currency: <lowercase currency code> }. Convert the amount with a decimal library, and remember that some currencies have no minor unit. Update Elements when the total changes.
- Don't set paymentMethodTypes. The app uses the payment methods enabled in the Stripe Dashboard.
4. Pay. When the customer submits:
- Call elements.submit() and stop on error. Read the selected method from its selectedPaymentMethod. Link isn't returned there: read it from the Payment Element's onChange event (event.value.type) instead.
- Call transactionInitialize(id: <checkout ID>, amount: <amount to pay>, paymentGateway: { id: "saleor.app.payment.stripe", data: { "paymentIntent": { "paymentMethod": "<method>" } } }) and read transaction { id }, transactionEvent { type message }, data, and errors. `data` is untyped JSON and strictly validated: anything other than this shape fails with ParseError.
- paymentMethod is one of: card, apple_pay, google_pay, link, klarna, paypal, us_bank_account, sepa_debit, pay_by_bank, mobilepay, revolut_pay. Any other method fails with UnsupportedPaymentMethodError, so make sure only these are enabled in the Stripe Dashboard.
- On success, transactionEvent.type is CHARGE_ACTION_REQUIRED or AUTHORIZATION_ACTION_REQUIRED and the client secret is in data.paymentIntent.stripeClientSecret.
- On CHARGE_FAILURE or AUTHORIZATION_FAILURE, show an error from data.paymentIntent.errors and let the customer try again.
- Never put the amount, currency, or lines in data. They come from Saleor.
5. Confirm. Call stripe.confirmPayment({ elements, clientSecret, confirmParams: { return_url } }). Put the checkout ID and the transaction ID in return_url, because the page reloads after a redirect and React state is lost. Stripe adds payment_intent_client_secret to the URL when it redirects back. If confirmPayment returns an error, Stripe didn't redirect: show error.message and let the customer try again.
6. Process on the return page. Call transactionProcess(id: <transaction ID>) and read transactionEvent { type message } and errors. It asks the app to read the PaymentIntent from Stripe, so the storefront doesn't have to wait for Stripe's webhook. Saleor ignores whichever of the two reports arrives second.
7. React to transactionEvent.type, which starts with CHARGE_ or AUTHORIZATION_:
- *_SUCCESS: Payment is complete (AUTHORIZATION_SUCCESS: authorized, captured later from the Dashboard). Complete the checkout.
- *_REQUEST: Stripe is still processing the payment, which is normal for bank debits. Complete the checkout; the order shows the payment as pending until Stripe confirms it.
- *_ACTION_REQUIRED: The payment isn't finished, for example the customer abandoned a redirect or the payment failed. Don't complete the checkout. Let the customer pay again, starting from transactionInitialize.
- *_FAILURE: The app couldn't read the payment from Stripe, for example during a Stripe outage. This doesn't mean the payment failed: wait a moment and call transactionProcess again before showing an error.
8. Complete. Call checkoutComplete(id: <checkout ID>) and show the order. Its errors mean the checkout isn't paid yet.
Idempotency:
- Saleor generates an idempotency key for each transactionInitialize, and the app passes it to Stripe. To make retries safe after a network error or timeout, generate your own key per payment attempt, pass it as transactionInitialize(idempotencyKey: <key>), and reuse it when retrying that attempt. Use a new key for a new attempt.
Errors:
- Branch on data.paymentIntent.errors[].code and errors[].code, never on messages, which can change. Treat unknown codes as a generic failure.
- Codes in data.paymentIntent.errors: ParseError, UnsupportedPaymentMethodError, StripeCardError, StripeApiError. Card declines during confirmPayment come from Stripe.js as error.type "card_error", not from Saleor.
- In live mode the app hides error details. Stripe test mode returns them in messages, which helps while building.
Verify:
- Connect the app to a Stripe test mode account, then pay in the browser with Stripe test cards (any future expiry date and any CVC): 4242 4242 4242 4242 succeeds, 4000 0000 0000 0002 is declined, 4000 0025 0000 3155 requires 3D Secure. See https://docs.stripe.com/testing for other methods.
- Check that the declined card shows Stripe's error and creates no order, and that the other two reach *_SUCCESS after transactionProcess, create an order, and show up in the Stripe Dashboard.
When you're done, tell me which files you changed and what you verified.Manual integration
To build the integration yourself, follow the steps below. They show how to integrate the Stripe SDK and the app conceptually. To see a working example, check the Test Client. Refer to the Stripe documentation for details on how to use the SDK.
Assumptions
- This guide is assuming a React-based UI. Follow Stripe documentation for implementation in other frameworks.
- This guide hardcodes currency to be USD. If your storefront implements multiple currencies, you need to ensure you properly convert the amount to cents and use a Stripe currency format.
- For brevity, we do not handle errors in code examples and omit non-essential code. In the real storefront you will add much more code around loading, error handling, notifications, etc.
- Guide is not using Idempotency Key
- The GraphQL client is
request
Prerequisites
- Install Stripe App in your Saleor dashboard
- Install Stripe browser SDK in your storefront:
pnpm add @stripe/stripe-js @stripe/react-stripe-js - Enable payments methods in Stripe Dashboard
To initialize the payment, you should also have implemented flow that will:
- Create a checkout
- Set required fields, like address and shipping method
- Have a final amount to pay calculated
In this guide we will render a part of the UI that will have the “PAY” button rendered and working.
Initialize gateway
First, check that the app is available for the checkout: saleor.app.payment.stripe must be in the checkout’s availablePaymentGateways. If it isn’t, the Stripe App isn’t installed or isn’t active, so don’t offer Stripe.
Next, tell the Stripe SDK to display payment UI components. To do that, we will first fetch Publishable Key from the App, to inject it into the React component
Prepare the following GraphQL mutation:
mutation RetrievePublishableKey($checkoutId: ID!, $amount: PositiveDecimal!) {
paymentGatewayInitialize(
id: $checkoutId
paymentGateways: { id: "saleor.app.payment.stripe" }
amount: $amount
) {
gatewayConfigs {
id
data
errors {
field
message
code
}
}
errors {
field
message
code
}
}
}
If the app is properly configured, you should receive a response like this:
{
"data": {
"paymentGatewayInitialize": {
"gatewayConfigs": [
{
"id": "saleor.app.payment.stripe",
"data": {
"stripePublishableKey": "<YOUR KEY>"
},
"errors": []
}
],
"errors": []
}
}
}
Great! Now you can render some parts of the UI. We will create a parent component that will create necessary Contexts and a child component that will render the Stripe UI.
import { loadStripe } from "@stripe/stripe-js";
import {
Elements,
PaymentElement,
useElements,
useStripe,
} from "@stripe/react-stripe-js";
import {useRef, useState} from "react";
const PaymentFormWrapper = ({stripePk, checkoutTotal, checkoutCurrency }: {stripePk, checkoutTotal: number; checkoutCurrency: string}) => {
const stripe = useRef(loadStripe(stripePk))
return (
<Elements
stripe={stripe}
options={{
// Stripe expects amount in cents - you need to correctly convert it, note that not every currency has 2 decimal places!
// WARNING: In production setup you should use a library like currencyJs or Decimal.js to safely convert payment numbers
amount: checkoutTotal * 100,
currency: "usd", // Stripe currency is lowercase
mode: "payment",
}}
>
<PaymentForm
/>
</Elements>
)
}
const PaymentForm = ({onSubmit}) => {
// Stripe and Elements are now available in the context
const stripe = useStripe();
const elements = useElements();
const handleSubmit = () => {
// We will implement this in the next step
}
return (
<form onSubmit={handleSubmit}>
<PaymentElement />
<button type="submit" disabled={
// Wait for Stripe loads first
!stripe || !elements
}>PAY</button>
</form>
)
}
At this point we should see:
- Stripe UI rendered and clickable
- “PAY” button is visible, but doing nothing once clicked.
Submitting payment
The next step is to create the payment intent using Stripe SDK and Saleor Transaction mutations together. First, let’s create the mutation query:
mutation InitializeTransaction(
$checkoutId: ID!
$data: JSON
$paymentGatewayId: String!
$amount: PositiveDecimal!
) {
transactionInitialize(
id: $checkoutId
paymentGateway: { id: $paymentGatewayId, data: $data }
amount: $amount
) {
transaction {
id
}
data
errors {
field
message
code
}
}
}
Let assume your query is assigned to transactionInitializeSessionDocument variable.
Great! Now we can proceed to implement the form-submitting logic.
Let’s get back to the handleSubmit function and implement it:
import request from "my-graphql-client";
import { transactionInitializeSessionDocument } from "my-graphql-queries";
const stripe = useStripe();
const elements = useElements();
const handleSubmit = async () => {
// First submit Stripe form - to validate and get the payment method. Remember to handle errors here!
const { selectedPaymentMethod } = await elements.submit();
// Then, call Saleor transactionInitialize mutation from the previous example.
const initializeSessionResult = await request(
transactionInitializeSessionDocument,
{
// For brevity, we are not passing all the fields in React examples. Make sure you pass them to your component
checkoutId: checkoutId,
amount: checkoutAmount,
// Remember to pass the special "data" field to the mutation. It's a plain JSON object, so it will not be type-checked.
// Be careful about the typos - but don't worry, app will return an error if you pass wrong data.
data: {
paymentIntent: {
paymentMethod: selectedPaymentMethod,
},
},
},
);
// We are going to need them later, so let's store it in a variable
const clientSecret =
initializeSessionResult.data.transactionInitialize.data.paymentIntent
.stripeClientSecret;
const transactionId =
initializeSessionResult.data.transactionInitialize.transaction.id;
// We will need to use these keys later, so let's save them in the Session
window.sessionStorage.setItem("stripePk", stripePk);
window.sessionStorage.setItem("clientSecret", clientSecret);
};
// ... Rest of the UI from the previous code
At this point, we have:
- Payment Intent created in Stripe. You should be able to see it in your Stripe dashboard.
- Unique session
clientSecretgenerated by the app, assigned you the payment intent. We will use it to proceed with the payment. - We extracted and saved Transaction ID which we will need in the future.
- Both Publishable Key and Client Secret are stored in Session Storage so we can use them later.
Confirming payment
The next step will be allowing Stripe to confirm the payment. Depending on the Payment method, Stripe may require a few steps, including redirecting to the dedicated external pages.
Hence, we need to generate the return_url param, telling Stripe where to redirect after the payment is completed.
The redirection URL may be specific to your storefront, but let’s prepare an example:
const getRedirectUrl = (checkoutId: string, transactionId: string) => `${window.location.origin}/checkout/${checkoutId}/payment/summary?transactionId=${transactionId}`;
In this example we preserve Checkout and Transaction IDs, so we can extract them later. You can decide to store them in Session Storage as well.
Now, let’s get back to our handleSubmit
const handleSubmit = async () => {
// Code hidden for brevity
// We finished here:
const clientSecret =
initializeSessionResult.data.transactionInitialize.data.paymentIntent
.stripeClientSecret;
const { error } = await stripe.confirmPayment({
// We have it in the context from useElements
elements,
clientSecret,
confirmParams: {
return_url: getRedirectUrl(checkoutId),
},
});
// Normally you will handle errors here, but for brevity we will skip it.
// Internally, Stripe will proceed with the payment and initiate all necessary redirects.
};
At this point, payment should be already succeeded (or failed) on the Stripe side. You should be able to see the payment in your Stripe dashboard.
However, we still need to:
- Display a result to the customer
- Complete the checkout in Saleor
Displaying summary
Let’s navigate to our summary page, which we told Stripe to redirect to.
You should ensure you pass Publishable Key, Client Secret and Checkout ID to the page. Checkout ID will be accessible from the URL. Publishable Key and Client Secret can be stored in Session Storage.
We will render Stripe Elements again, so you need to wrap the page in Elements component again.
// summary.tsx
import {
Elements,
PaymentElement,
useElements,
useStripe,
} from "@stripe/react-stripe-js";
import { loadStripe } from "@stripe/stripe-js";
import {useEffect,useState} from "react";
// For brevity, we assume checkout is available in props. Depending on your framework, you may need to get it from the URL
const Page = ({checkoutId}) => {
// You can store it however you like, but keep in mind that page redirection (done by Stripe) will not preserve React state (or any client memory values)
const pk = sessionStorage.getItem("stripePk")
const clientSecret = sessionStorage.getItem("clientSecret")
return (
<Elements stripe={loadStripe(pk)}>
<SummaryPage checkoutId={checkoutId} clientSecret={clientSecret} />
</Elements>
)
}
const SummaryPage = ({checkoutId, clientSecret}) => {
const stripe = useStripe();
const [intent, setIntent] = useState(null);
useEffect(async () => {
const result = await stripe.retrievePaymentIntent(clientSecret);
setIntent(result.paymentIntent)
}, [])
if(!intent) {
return <div>Loading...</div>
}
// You should handle all the possible statuses here
if(intent.status === "succeeded") {
return <div>Payment succeeded!</div>
}
}
We haven’t used checkoutId yet - we will need it later. But you can use it to display checkout details from Saleor in the summary page too.
Updating checkout state in Saleor
At this point, payment is done and the user has seen the confirmation. However, Checkout in Saleor still must be completed. It can be done by calling checkoutComplete mutation.
However, we don’t know if Stripe has told Saleor about the payment yet! Let’s have a quick recap of the flow: Stripe will send a webhook with the payment status to Saleor. But this is an async operation, so we can’t be sure if the webhook has been received yet.
If storefront (automatically, or by user action) calls checkoutComplete too early, Saleor will not allow performing the operation. Only SUCCESS or PROCESSING statuses are allowed to complete the checkout.
In this step, we will use TransactionProcessSession mutation to force-update Saleor about the payment status.
Let’s start by defining the mutation query:
mutation ProcessTransaction($transactionId: ID!) {
transactionProcess(id: $transactionId) {
transaction {
id
}
data
errors {
field
message
code
}
}
}
Now, we can run the mutation “in the background.”
// summary.tsx
import { useEffect } from "react";
import { request } from "my-graphql-client";
import { transactionProcessDocument } from "my-graphql-queries";
// ...
useEffect(async () => {
await request(transactionProcessDocument, {
transactionId: props.transactionId, // get it from props/URL
});
}, []);
With this mutation, App will fetch the latest Payment Intent status from Stripe and update Saleor about it. We can’t be sure if ProcessSession mutation was before or after Stripe Webhook, but it’s not a problem. Saleor will ignore the event if reported a second time.
If transactionProcess returns CHARGE_FAILURE or AUTHORIZATION_FAILURE, the app couldn’t read the Payment Intent from Stripe, for example because of a temporary Stripe problem. It doesn’t mean the payment failed: call transactionProcess again before showing an error.
If payment has failed before, your storefront should handle the error (either based on direct Stripe Payment Intent status, or Saleor transaction status) and display it to the user, probably asking to retry the payment.
If the payment has succeeded (either SUCCESS or PENDING), we can proceed with completing the checkout.
Completing the checkout
The last mutation we will use is checkoutComplete. It will finalize the checkout and create the order.
mutation CompleteCheckout($checkoutId: ID!) {
checkoutComplete(id: $checkoutId) {
order {
id
}
errors {
field
message
code
}
}
}
We have passed the Checkout ID to the summary page, so we can use it here.
// summary.tsx
import { useEffect } from "react";
import { request } from "my-graphql-client";
import { transactionProcessDocument } from "my-graphql-queries";
import { completeCheckoutDocument } from "my-graphql-queries";
// ...
useEffect(async () => {
await request(transactionProcessDocument, {
transactionId: props.transactionId, // get it from props/URL
});
await request(completeCheckoutDocument, {
checkoutId: props.checkoutId, // get it from props/URL
});
}, []);
At this point, if no errors are returned, checkout is completed and the order is created.
Idempotency Key
Both Saleor and Stripe support idempotency to ensure that the same request (from the business perspective - like request to pay) is not executed multiple times.
Saleor will automatically generate the Idempotency Key, and the App will pass it to Stripe. If you want to control the Key usage, like setting your own, you can pass it to the mutation
Caveats
Stripe Link integration
Stripe Link payment method is not automatically returned by Stripe Elements.
You need to extract this value from PaymentElement onChange={...} handler, while other methods are available using elements.submit()