Beyond the Template: Mastering Salla Integrations and Apple Pay

For a long time, the e-commerce landscape in the MENA region was dominated by rigid, template-based storefronts. But as our users' expectations shifted toward high-performance, native experiences, I found myself tasked with a significant engineering challenge: decoupling the front-end from the Salla ecosystem while maintaining a rock-solid integration for "Universal Apps."

In this post, I’m skipping the “Hello World” stuff. I want to talk about the real architectural hurdles I faced—specifically the OAuth lifecycle, cross-platform state management, and the absolute beast that is Apple Pay decryption in a headless environment.

The OAuth Loop: More Than Just a Token

When you're building a custom mobile app or a high-performance Next.js storefront on top of Salla, the first wall you hit is the OAuth flow. Most documentation treats it as a one-time setup, but in production, managing the access_token and refresh_token lifecycle across thousands of concurrent sessions is where things get messy.

I realized early on that relying on the client to manage these tokens was a recipe for race conditions. I moved to a centralized Token Manager Service.

// Example of a centralized token refresh logic to prevent race conditions
async function getValidToken(merchantId: string) {
  const tokenData = await redis.get(`salla_token_${merchantId}`);
  
  if (isTokenExpired(tokenData)) {
    // Use a distributed lock (Redlock) to ensure only one refresh happens
    const lock = await redlock.acquire([`lock:${merchantId}`], 5000);
    try {
      const newToken = await refreshSallaToken(tokenData.refresh_token);
      await redis.set(`salla_token_${merchantId}`, newToken);
      return newToken.access_token;
    } finally {
      await lock.release();
    }
  }
  return tokenData.access_token;
}

By implementing a distributed lock using Redis, I eliminated the "401 unauthorized" spikes that usually occur when multiple serverless functions try to refresh the same merchant token simultaneously.

The "Universal" Bridge

One of my biggest breakthroughs was moving away from direct API calls from the mobile app to Salla. Instead, I built a BFF (Backend for Frontend). Why? Because Salla’s API, while robust, isn't always optimized for mobile payloads.

For a Universal App (iOS, Android, and Web), you need a unified data schema. I used GraphQL on the BFF to aggregate Salla’s REST endpoints. This reduced the mobile app's overhead by 60%, as we only fetched the specific product fragments needed for the view, rather than the massive JSON objects Salla returns by default.

Cracking the Apple Pay Nut

Apple Pay is the gold standard for conversion in our region, but integrating it into a custom Salla-powered app is notoriously tricky. The primary issue isn't the UI; it's the handshake between the Apple Merchant Identity, the Salla Gateway, and your custom backend.

The Breakthrough: Decryption Strategy

When a user taps the Apple Pay button, you receive a PKPayment object. If you're using a specific gateway like Checkout.com or Moyasar via Salla, you don't actually want to decrypt the token yourself on the mobile side. You want to pass the Encrypted Payment Data directly to the Salla payment completion endpoint.

However, the real engineering challenge I faced was handling the Shipping Contact updates. If your app changes the shipping cost based on the city selected in the Apple Pay sheet, you must respond within the 30ms window required by the didSelectShippingContact delegate.

func paymentAuthorizationController(_ controller: PKPaymentAuthorizationController, didSelectShippingContact contact: PKContact, handler completion: @escaping (PKPaymentRequestShippingContactUpdate) -> Void) {
    // I optimized this by pre-fetching shipping zones to the local DB
    let city = contact.postalAddress?.city ?? ""
    let shippingMethods = LocalShippingEngine.getMethods(for: city)
    
    let update = PKPaymentRequestShippingContactUpdate(errors: nil, paymentSummaryItems: calculateSummary(methods: shippingMethods), shippingMethods: shippingMethods)
    completion(update)
}

By caching shipping zones and rates in a local SQLite/Room database on the device, I bypassed the network latency that usually causes Apple Pay sessions to timeout.

Webhooks: The Source of Truth

In a headless setup, your local database can easily get out of sync with Salla's state. I treated Salla Webhooks as the "Source of Truth." But webhooks are unreliable—they can arrive out of order.

I implemented an Idempotency Layer. Every webhook event from Salla (like order.updated or product.created) was logged in a processed_events table with its unique Salla event ID. Before processing, we'd check if that ID existed. This saved us from double-counting revenue or duplicating orders during high-traffic sales events.

Final Thoughts

Engineering a modern storefront on Salla isn't just about making API calls; it's about building a resilient middle tier that can handle the nuances of mobile performance and secure payments. My journey from basic templates to a fully decoupled, Apple Pay-ready architecture taught me that the "boring" parts—token management, caching, and idempotency—are actually where the most critical engineering happens.

If you're building in this space, stop thinking about the UI and start obsessing over your data orchestration. That's where the real performance gains live.