Shopify bridge setup

What this bridge does

• Merchant creates a manual Shopify payment method named Secure Card Payment.
• Customer places the Shopify order using that manual method.
• Shopify sends an orders/create webhook to the gateway.
• The gateway validates the order, restricted-item rules, merchant token, and connected account.
• The gateway creates a hosted payment checkout and stores a Shopify payment session.
• The gateway suppresses duplicate Shopify webhook retries so one order maps to one payment session.
• The gateway can email the hosted payment link to the customer when email sending is configured.
• Processor webhooks reconcile paid, failed, expired, and cancelled states back to the bridge ledger.
• When Shopify writeback is enabled, paid processor events mark the manual Shopify order as paid.

Merchant setup

1. Get the merchant's Payment Gateway API Base URL and Merchant Token.
2. In Shopify, create a custom/manual payment method named Secure Card Payment.
3. Set payment instructions to tell customers they will receive or open a secure payment link after placing the order.
4. Create a Shopify custom app with Admin API access to read_orders, write_orders, and webhooks.
5. Register the shop with the gateway using the endpoint below.
6. Create an orders/create webhook pointing at the webhook URL returned by registration.

Register shop endpoint

POST https://api.noramp.dev/shopify/register-shop
Authorization: Bearer <merchant_token>
Content-Type: application/json

{
  "shop_domain": "merchant-store.myshopify.com",
  "admin_access_token": "shpat_...",
  "scopes": "custom_app_admin_token"
}

The response includes the Shopify orders/create webhook URL and the required manual payment method name.

Webhook URL

Shopify signs this webhook with the Shopify app secret. The gateway rejects unsigned or incorrectly signed requests.

Operational notes

• This is a bridge, not a native Shopify payment app. It cannot insert card fields into Shopify checkout without Shopify Payments App approval.
• Set SHOPIFY_WRITEBACK_ENABLED=1 to mark paid manual orders in Shopify after the processor confirms payment. The Shopify custom app user must have permission to mark orders as paid.
• Set RESEND_API_KEY and EMAIL_FROM to email payment links automatically. Set SHOPIFY_PAYMENT_LINK_EMAIL_ENABLED=0 to disable those emails.
• Use Shopify API version 2026-04 by default, or override it with SHOPIFY_ADMIN_API_VERSION.