Shopify Custom Payment Gateways: Mastering Instant Redirects Without Payments Partner Status

Hey everyone,

I recently stumbled upon a really insightful question in the Shopify Community that I know many of you developers and store owners, especially those operating in regions with unique payment landscapes, have probably grappled with. It came from hichem.hamdani, who was trying to integrate SATIM, the national Algerian payment network, with Shopify.

Hichem laid out a common challenge: how do you get a customer to redirect immediately to an external payment gateway (like SATIM, which isn't part of Shopify's Payments Partner program) right after they hit "Complete order"? The current workaround, while functional, involved sending an email with a payment link after an orders/create webhook fires. As hichem rightly pointed out, that's not exactly the seamless, instant experience we all strive for.

The Core Problem: Instant Redirects for Non-Partner Gateways

Let's break down hichem's situation, because it's a fantastic illustration of a broader issue. Shopify's checkout process is designed for security and consistency, which means direct manipulation of the checkout flow, especially for payment redirects, is tightly controlled. This is where the Payments Partner program comes in – approved partners get deeper integration points.

But what if you're integrating a regional gateway that isn't (or can't be) a Shopify Payments Partner? Hichem's current flow works like this:

1. Customer chooses a manual payment method (e.g., "CIB / Dahabia").
2. Order is created, triggering an orders/create webhook to hichem's server.
3. Server sends a payment link via email.
4. Customer clicks email link, goes to SATIM's hosted page.
5. After payment, hichem's server uses Shopify's Transactions API to mark the order as paid.

The biggest pain point? That email step. It introduces friction and a delay, which can lead to cart abandonment. So, how do we cut that out and get an immediate redirect?

Can We Redirect Immediately Without Payments Partner Status?

This was hichem's first and most critical question. The short answer for redirecting immediately after the "Complete order" button click but before the thank you page fully loads is usually "no" for non-partner gateways. Shopify's checkout flow is highly secure and locked down at that specific point to ensure order integrity and prevent malicious redirects.

However, we can get pretty darn close to an "immediate" redirect by leveraging the thank you page.

Why Custom Pixels and window.top.location Get Blocked

Hichem tried using a Custom Pixel with the checkout_completed event, attempting to use window.top.location for a redirect, but it was blocked by the sandbox. This is a common hurdle. Custom Pixels, by design, run in a sandboxed iframe for security reasons. This sandbox often restricts direct manipulation of the parent window's location for security, preventing malicious scripts from hijacking the user's browser.

So, while the checkout_completed event is indeed the right trigger point (it fires once the order is successfully created and the customer lands on the thank you page), a Custom Pixel isn't the ideal tool for initiating a full-page redirect.

Post-Purchase Checkout Extensions: A Limited Solution for This Use Case

Hichem also asked about post-purchase checkout extensions (checkout_post_purchase) and their restriction to Shopify Plus for custom apps. Yes, for custom apps, these extensions are indeed primarily available to Shopify Plus merchants. Even for Plus stores, their main purpose is for presenting upsells or cross-sells after the initial purchase, not typically for redirecting to a primary payment gateway to complete the initial order's payment. It's an "after the fact" extension, not a "during payment" one.

The Best Approach: Leveraging the Thank You Page for Immediate Redirects

Based on how Shopify's checkout environment works, the most practical and effective way to achieve an "immediate" redirect for a non-partner gateway is to initiate it from the thank you page (Order Status Page). This page loads right after the order is created, and it's where you have more control to inject scripts.

Step-by-Step Instructions for a Seamless Redirect:

Here's how you can implement a much smoother UX, drawing on common community insights for these scenarios:

1. Set Up a Custom Manual Payment Method:

   • Go to your Shopify Admin > Settings > Payments.
   • Under "Manual payment methods," click Add manual payment method.
   • Name it something descriptive like "CIB / Dahabia (SATIM)".
   • Add brief instructions for the customer, but keep in mind they'll be redirected instantly, so it can be something like "You will be redirected to SATIM to complete your payment."
   • This method will appear as a payment option during checkout.

2. Inject Redirect Script into the Thank You Page:

   This is the crucial part. You'll use the "Additional scripts" section in your checkout settings. This script will trigger the redirect as soon as the thank you page loads for an order placed with your custom payment method.

   • Go to your Shopify Admin > Settings > Checkout.
   • Scroll down to the "Order status page" section and find the "Additional scripts" text area.
   • Paste your JavaScript code here. This script will execute on the thank you page.

   Here's the logic you'd implement:

   Important considerations for this script:

   • Server-Side URL Generation: You absolutely must generate the SATIM redirect URL on your backend server. Do NOT expose any API keys or sensitive information in your client-side JavaScript. Your backend will receive the Shopify order details, interact with the SATIM API, and return the secure redirect URL to the frontend.
   • Conditional Redirect: The script should only trigger if the specific manual payment method was selected and if there's an actual payment due (Shopify.checkout.payment_due > 0).
   • Fallback: Consider a fallback mechanism if your backend call fails or if the redirect URL isn't returned. Perhaps revert to showing the email link or a clear instruction.

3. Your Server Marks the Order as Paid:

   This part of hichem's original flow remains essential. After the customer successfully completes payment on SATIM's hosted page, SATIM will notify your server (via a webhook or callback). Your server then needs to call Shopify's Transactions API to mark the corresponding order as paid. This closes the loop and updates the order status in Shopify.

Wrapping It Up

While Shopify's stringent checkout security means a true "pre-thank you page" redirect for non-partners is generally off-limits, the thank you page offers a powerful and accessible alternative. By injecting a well-crafted script into the "Additional scripts" section, you can achieve a near-instant redirect that dramatically improves the customer experience compared to waiting for an email.

It's all about understanding the available hooks and working within Shopify's architecture. This approach provides the best balance of security, functionality, and a smooth journey for your customers using regional payment gateways like SATIM.