Plugins & Integrations

Connect an existing storefront to GullyPay to sync products and orders and accept payments through the GullyPay rails. Integrations are managed under the Plugins module — one connection per (platform, merchant, store).

Looking to take payments?

These connectors sync catalogs and orders only; they do not add Gully Pay as a payment method. To take payments, see Integrations: the WooCommerce payment plugin, payment buttons for Wix, Webflow, Squarespace and WordPress, payment links, QR codes, the checkout API, x402 and the SDKs. In the dashboard the connectors below are under Integrations, Catalog sync.

Supported Platforms

Platform	Auth	Capabilities
`shopify`	OAuth	Product sync, order webhooks, payment provider, checkout redirect
`woocommerce`	REST API keys or OAuth	Bidirectional product sync, order webhooks, payment gateway, checkout widget
`wordpress`	Application password or OAuth	Shortcode generator, block editor component, payment form embed
`webflow`	OAuth	Product sync, order webhooks, payment provider, checkout redirect
`wix`	OAuth	Product sync, order webhooks, payment provider, checkout redirect
`squarespace`	OAuth / API key	Product sync, order webhooks, payment provider, checkout redirect
`magento`	Integration token	Bidirectional product sync, order webhooks, payment provider
`opencart`	REST API	Product sync, order webhooks, payment gateway, checkout widget

Shopify, WooCommerce & WordPress are the flagship integrations

Shopify, WooCommerce, and WordPress ship with complete, production-ready connectors. The remaining platforms are registered in the facilitator and follow the identical connect / sync / webhook contract described below.

OAuth credentials are configured server-side

For OAuth platforms, the GullyPay server must have the platform's app credentials set as environment variables (SHOPIFY_CLIENT_ID / SHOPIFY_CLIENT_SECRET, etc.). The authorization URL returned by connect is only valid once those are configured.

Base URL

https://gullypay.xyz/api

Endpoints marked Auth require a Bearer JWT: Authorization: Bearer <accessToken>.

Endpoints

Method	Path	Auth	Description
`GET`	`/plugins`	—	List all available integrations and their catalog metadata
`POST`	`/plugins/:platform/connect`	Auth	Start an OAuth or direct-key connection
`POST`	`/plugins/:platform/callback`	—	Complete an OAuth flow (exchange `code` for tokens)
`GET`	`/plugins/:platform/callback`	—	OAuth redirect callback (`?code=&state=`)
`GET`	`/plugins/:platform/status`	Auth	Connection status + last-sync metadata
`POST`	`/plugins/:platform/sync`	Auth	Trigger a product sync
`DELETE`	`/plugins/:platform/disconnect`	Auth	Remove a connection
`POST`	`/plugins/:platform/webhook`	HMAC	Receive platform webhooks (verified by signature)

List Integrations

List available plugins

curl https://gullypay.xyz/api/plugins

Response (PluginListItem[])

[
{
  "platform": "shopify",
  "name": "Shopify",
  "description": "Connect your Shopify store to sync products, orders, and accept payments via GullyPay.",
  "version": "1.0.0",
  "icon": "shopify",
  "features": ["OAuth connect", "Product sync", "Order webhooks", "Payment provider", "Checkout redirect"],
  "docsUrl": "https://docs.gullypay.xyz/plugins/shopify",
  "status": "available"
}
]

Connect a Store

POST /plugins/:platform/connect starts a connection. The response depends on the platform's auth model.

Request body (ConnectPluginDto)

{
"merchantId": "merch_abc123",
"storeId": "store_def456",
"storeUrl": "your-store.myshopify.com",
"apiKey": "optional — WooCommerce consumer key / WordPress application password",
"apiSecret": "optional — WooCommerce consumer secret",
"redirectUri": "optional — overrides the default callback URL"
}

OAuth platforms (Shopify, and WooCommerce/WordPress without keys)

The response contains an authUrl. Redirect the merchant's browser there to authorize; the platform then redirects back to the callback with a code and state.

Response — OAuth required

{
"authUrl": "https://your-store.myshopify.com/admin/oauth/authorize?client_id=...&state=...",
"state": "a1b2c3d4e5f6...",
"platform": "shopify",
"requiresOAuth": true
}

Direct-key platforms (WooCommerce keys, WordPress application password)

When apiKey (and apiSecret for WooCommerce) are supplied, the store connects immediately — no redirect.

Response — direct connect

{
"platform": "woocommerce",
"status": "connected",
"requiresOAuth": false
}

One connection per store

Calling connect for a platform that is already connected to the same store returns 409 Conflict. Disconnect first to reconnect.

OAuth Callback

The state returned from connect is a single-use nonce that expires after 10 minutes. GullyPay exchanges the authorization code for access/refresh tokens and persists the connection.

Complete the OAuth flow

curl -X POST https://gullypay.xyz/api/plugins/shopify/callback \
-H "Content-Type: application/json" \
-d '{"code": "auth_code_from_platform", "state": "a1b2c3d4e5f6..."}'

Response

{
"platform": "shopify",
"status": "connected",
"merchantId": "merch_abc123",
"storeId": "store_def456"
}

The platform may instead redirect back with query parameters — the GET variant handles this:

GET callback

GET /plugins/shopify/callback?code=auth_code&state=a1b2c3d4e5f6

Connection Status

Get status

curl "https://gullypay.xyz/api/plugins/shopify/status?merchantId=merch_abc123&storeId=store_def456" \
-H "Authorization: Bearer <accessToken>"

Response (PluginConnectionInfo)

{
"platform": "shopify",
"status": "connected",
"merchantId": "merch_abc123",
"storeId": "store_def456",
"externalStoreUrl": "your-store.myshopify.com",
"externalStoreName": "Your Store",
"connectedAt": "2026-07-18T12:00:00Z",
"lastSyncAt": "2026-07-18T13:30:00Z",
"productCount": 42,
"orderCount": 18,
"scopes": ["read_products", "write_products", "read_orders"]
}

If no connection exists, status is "disconnected"; if credentials fail to initialize, status is "error".

Sync Products

direction is one of import (platform → GullyPay), export (GullyPay → platform), or bidirectional.

Trigger a sync

curl -X POST https://gullypay.xyz/api/plugins/shopify/sync \
-H "Authorization: Bearer <accessToken>" \
-H "Content-Type: application/json" \
-d '{"merchantId": "merch_abc123", "storeId": "store_def456", "direction": "bidirectional"}'

Response (SyncResult)

{
"success": true,
"direction": "bidirectional",
"imported": 12,
"exported": 4,
"updated": 26,
"failed": 0,
"errors": [],
"startedAt": "2026-07-18T13:30:00Z",
"completedAt": "2026-07-18T13:30:07Z"
}

Disconnect

Remove a connection

curl -X DELETE https://gullypay.xyz/api/plugins/shopify/disconnect \
-H "Authorization: Bearer <accessToken>" \
-H "Content-Type: application/json" \
-d '{"merchantId": "merch_abc123", "storeId": "store_def456"}'

Response

{ "platform": "shopify", "status": "disconnected" }

Incoming Webhooks

Connected platforms push events to POST /plugins/:platform/webhook. GullyPay verifies the platform's HMAC signature, normalizes the topic (e.g. Shopify orders/create → order.created), matches it to a stored connection by shop domain, and dispatches it to the plugin handler.

Signature headers by platform

Shopify       X-Shopify-Hmac-Sha256, X-Shopify-Topic, X-Shopify-Shop-Domain
WooCommerce   X-WC-Webhook-Signature, X-WC-Webhook-Topic, X-WC-Webhook-Source
WordPress     X-WP-Webhook-Signature

Signatures are enforced

Requests carrying a signature header that fails verification are rejected with 400. Unmatched events (no connection for the source store) are acknowledged with { "received": true, "matched": false } and logged for debugging.

Managing Integrations in the Dashboard

The Commerce → Plugins & Integrations page in the merchant dashboard wraps all of the above: it lists the catalog, shows live connection status and last-sync time per platform, and provides Connect (with the OAuth redirect handled automatically), Sync now, and Disconnect actions.

Next Steps

Ecommerce — Products, orders, and inventory that plugins sync against
Webhooks — GullyPay-native event notifications to your own server
API Reference — Complete endpoint documentation