Integration Guide: Stripe Payments

1. Get the Platform Publishable Key

Tokenizing cards requires the Innovorder platform publishable key. This key is provided as part of an integration project: contact support@innovorder.fr to set one up and receive the key for the target environment.

2. Tokenize the Card

Initialize the Stripe SDK (Stripe.js on the web, or the Stripe mobile SDK) with the platform publishable key, without any stripeAccount parameter, and create a PaymentMethod from the card fields. The resulting pm_… id lives on the platform account, which is exactly where our backend expects it.

const stripe = await loadStripe(INNOVORDER_PLATFORM_PUBLISHABLE_KEY); // no stripeAccount option

const { paymentMethod } = await stripe.createPaymentMethod({
    type: 'card',
    card: cardElement,
});
// paymentMethod.id → "pm_..." - send it in the order payment metadata (step 3)

3. Create the Order - the Metadata Contract

A Stripe payment is one entry of the payments array of POST /orders (see Create Orders for the full request body). The Stripe reference goes in the payment's metadata field, which must be a JSON-encoded string (a string containing JSON - note the escaping below) holding at least one of these two keys:

{
  "restaurantId": 2285,
  "channelId": 2,
  "consumptionMode": "MODE_TAKE_AWAY",
  "menuId": 24194,
  "cart": [
    {
      "productId": 1670891,
      "quantity": 1,
      "steps": []
    }
  ],
  "expectedAt": "2026-07-23T12:30:00.000Z",
  "payments": [
    {
      "paymentMethodId": 169092,
      "amount": 3150,
      "quantity": 1,
      "metadata": "{\"stripePaymentMethodId\":\"pm_1AbCdEf...\"}"
    }
  ]
}

{
  "status": 200,
  "code": "order_created",
  "message": "Your order was successfully created.",
  "data": {
    "orderId": 1927055,
    "ticketNumber": "1747_2285_2026-07-23_2",
    "mainStatus": "VALIDATED",
    "paymentStatus": "PAID",
    "requiredAction": null
  }
}

When is stripe_payment_metadata_invalid (400) returned?

• metadata is missing or an empty string (it is optional in the general order schema, but required for Stripe payments);
• metadata is not parseable JSON;
• the parsed object contains neither key (e.g. "{}");
• cardId is not a JSON integer - "{\"cardId\":\"42\"}" (string) fails, "{\"cardId\":42}" passes;
• stripePaymentMethodId is not a string, or is an empty string;
• cardId is sent on an unauthenticated request - guest checkout can only use stripePaymentMethodId.

4. Save a Card for Reuse (Optional)

To let an authenticated customer reuse a card, register it through the Cards (Stripe) SetupIntent flow - the SDK stays initialized with the platform key (no stripeAccount):

// 1. Request a SetupIntent (no cardToken) - POST /cards/v2
//    { "name": "My Visa" }  →  { "client_secret": "seti_..._secret_..." }

// 2. Confirm it client-side with the card fields
const { setupIntent } = await stripe.confirmCardSetup(clientSecret, {
    payment_method: { card: cardElement },
});

// 3. Persist the card - POST /cards/v2
//    { "name": "My Visa", "cardToken": setupIntent.payment_method }
//    →  { "cardId": 4521, "brand": "visa", "last4": "4242", "name": "My Visa" }

// 4. Pay with the saved card - POST /orders
//    "metadata": "{\"cardId\":4521}"

The Stripe Customer is created automatically on our platform account at the first card save - you never create or fetch it. There are no Ephemeral Keys and no "PaymentSheet-style" Customer endpoints in the Innovorder API: our flow does not use them.

5. Handle 3-D Secure (SCA)

The PaymentIntent is confirmed server-side. If the cardholder's bank requires authentication, POST /orders still returns HTTP 200, but with code required_action:

{
  "status": 200,
  "code": "required_action",
  "message": "Additional action required.",
  "data": {
    "orderId": 1927055,
    "requiredAction": {
      "type": "challengeStripe",
      "intentId": "pi_xxx",
      "requires_action": true,
      "payment_intent_client_secret": "pi_xxx_secret_yyy"
    }
  }
}

1. Re-initialize the Stripe SDK on the restaurant's connected account: platform publishable key + stripeAccount: <stripeUserId> (acct_…). The stripeUserId is exposed in the restaurant's Stripe module configuration returned by Get Web Ordering Configuration (restaurant.moduleStripe.stripeUserId). This is the only place the connected account ever appears client-side - the PaymentIntent lives on the restaurant's account, so the challenge must run there.
2. Run the challenge: handleNextAction / handleCardAction(payment_intent_client_secret).
3. Confirm the order with POST /orders/confirm (see Confirm Payment), sending the intentId from requiredAction as paymentIntentId.

const stripeConnected = await loadStripe(INNOVORDER_PLATFORM_PUBLISHABLE_KEY, {
    stripeAccount: restaurant.moduleStripe.stripeUserId, // acct_...
});

const { paymentIntent, error } = await stripeConnected.handleCardAction(clientSecret);
if (!error) {
    // POST /orders/confirm  { "orderId": 1927055, "paymentIntentId": paymentIntent.id }
}

If the intent still requires action at confirm time, POST /orders/confirm returns a 400 stripe_still_requires_action with the client_secret again in extraData, so you can retry the challenge.