Skip to main content

Shopify

Overview​

The PayWise Shopify integration is implemented as a server-hosted Azure Functions adapter in the paywise-plugin-shopify repository.

This is not yet a packaged Shopify App distribution like the WooCommerce ZIP flow. The current implementation is a managed integration path where PayWise deploys and configures the adapter with merchant-specific credentials.

The current v1 ownership model is:

  • Shopify remains the system of record for merchant order context.
  • PayWise is the payment rail.
  • Internal callers create, status, and cancel PayWise payments against an existing Shopify order.
  • The adapter mirrors correlation and payment status back onto Shopify order tags and notes.

Current Implementation Status​

  • Runtime: .NET 8
  • Hosting model: Azure Functions v4 isolated worker
  • Primary service shape: authenticated HTTP endpoints for payment create, payment status, and payment cancel
  • Current repo entrypoint: PaywiseShopifyFunctionApp
  • Catalog rollout: sandbox beta, production in review
  • Supported currencies: TTD, USD

What The Adapter Exposes​

The adapter currently exposes these routes:

  • POST /api/payment/request
  • GET /api/payment/status
  • POST /api/payment/cancel
  • POST /api/webhooks/shopify
  • GET /api/health/live
  • GET /api/health/ready

Payment-facing endpoints require:

  • Azure Function auth
  • internal bearer auth

The Shopify webhook endpoint requires:

  • X-Shopify-Hmac-Sha256 validation

Configuration Model​

The adapter expects PayWise configuration under the Paywise section, with per-merchant client blocks such as:

  • BaseUrl
  • Version
  • OriginCountry
  • Clients:{merchantId}:ApiKey
  • Clients:{merchantId}:SubscriptionKey
  • Clients:{merchantId}:BusinessMobile
  • Clients:{merchantId}:IpAddress

The repository also includes Shopify configuration for:

  • store domain
  • Admin API access token
  • API version
  • webhook shared secret

The adapter configuration also requires:

  • internal bearer token
  • supported currency allowlist

Local Inspection And Testing​

To inspect or run the adapter locally you need:

  1. .NET 8 SDK
  2. Azure Functions Core Tools for local function hosting
  3. A local.settings.json file based on local.settings.json.example
  4. Sandbox PayWise credentials for the target merchant

Suggested local validation sequence:

  1. Build the solution with dotnet build
  2. Run the function app locally
  3. Test payment/request with TTD
  4. Test payment/request with USD
  5. Confirm unsupported currencies are rejected
  6. Test payment/status
  7. Test payment/cancel
  8. Confirm invalid bearer auth is rejected
  9. Confirm invalid Shopify webhook HMAC is rejected

Merchant Onboarding Notes​

Shopify onboarding should still be treated as a managed integration:

  • PayWise provisions sandbox credentials
  • PayWise deploys the adapter
  • merchant-specific config is added server-side
  • end-to-end checkout, status, and cancel flows are validated before production approval

Business Portal Integration​

The Business Portal integrations page now surfaces Shopify from the control-plane plugin catalog so operators can:

  • see sandbox and production rollout state
  • open the Shopify setup guide
  • request onboarding help from the portal

Support Checklist​

When raising a Shopify integration issue, include:

  • store domain
  • merchant identifier used in the adapter config
  • PayWise request IDs
  • timestamp and timezone
  • function app environment
  • whether the failure happened on create, status, or cancel

Remaining Gaps Before Production Promotion​

  • run the adapter against a real sandbox Shopify store end to end
  • finalize deployment automation and environment promotion path
  • decide whether refund handling stays informational in v1 or performs additional PayWise-side automation
  • confirm whether this remains a managed adapter long term or becomes a distributable app flow