Integrations API

The endpoints behind the dashboard Integrations hub: the registry, the per-store setup wizard (Install, Connect, Test, Go live), health, the event viewer, plugin version reporting and public payment links. The list of integrations itself is on the Integrations page.

Base URL: https://gullypay.xyz/api. Routes marked JWT need a dashboard session (Authorization: Bearer <accessToken>) of a member of the store's merchant; every store-scoped route checks that the caller can act for :storeId.

Method	Path	Auth	Description
`GET`	`/integrations/registry`	none	The registry. Networks behind a server flag (Gully Chain Testnet) are listed only while the flag is on.
`GET`	`/integrations/stores/:storeId/installs`	JWT	Wizard progress for every integration the store started
`GET`	`/integrations/stores/:storeId/installs/:integrationId`	JWT	Wizard progress for one integration
`POST`	`/integrations/stores/:storeId/installs/:integrationId/install`	JWT	Step 1: mark the plugin or snippet as installed
`POST`	`/integrations/stores/:storeId/installs/:integrationId/connect`	JWT	Step 2: create the store API key and webhook endpoint (secrets returned once)
`POST`	`/integrations/stores/:storeId/installs/:integrationId/test`	JWT	Step 3: open a test hosted checkout
`GET`	`/integrations/stores/:storeId/installs/:integrationId/test`	JWT	Step 3 status (poll)
`POST`	`/integrations/stores/:storeId/installs/:integrationId/live`	JWT	Step 4: go live (needs a passed test)
`GET`	`/integrations/stores/:storeId/health`	JWT	Health of every started integration
`GET`	`/integrations/stores/:storeId/events?limit=20`	JWT	Event viewer: recent `checkout.session.*` events and their deliveries
`GET`	`/payment-links/:slug`	none	Public payment link details
`POST`	`/payment-links/:slug/checkout`	none	Open a hosted checkout for the link's stored amount

Connect

Creates exactly what the integration needs, using the same services as Developer → API keys and Developer → Webhooks:

a store API key (rk_…) pinned to the store's merchant, with only the registry's requiredScopes (for WooCommerce and Hosted checkout: checkout:write);
a webhook endpoint for the registry's webhookEvents when a webhookUrl is sent (required for WooCommerce, optional for site builders and Hosted checkout).

Connect WooCommerce

curl -X POST https://gullypay.xyz/api/integrations/stores/$STORE_ID/installs/woocommerce/connect \
-H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
-d '{"webhookUrl":"https://shop.example.com/wp-json/gullypay/v1/webhook"}'

Response (shown once)

{
"install": { "integrationId": "woocommerce", "currentStep": "test", "steps": { "...": "..." } },
"credentials": {
  "apiKey": "rk_…",
  "apiKeyPrefix": "rk_1a2b",
  "scopes": ["checkout:write"],
  "storeId": "…",
  "webhookSecret": "…",
  "webhookUrl": "https://shop.example.com/wp-json/gullypay/v1/webhook",
  "webhookEvents": ["checkout.session.completed"],
  "apiBaseUrl": "https://gullypay.xyz/api"
},
"shownOnce": true
}

Secrets are shown once

The API key and the webhook signing secret are not stored in clear and cannot be read again. Calling Connect a second time rotates them: the previous key is revoked at once and the previous endpoint is disabled. Every connect and rotation is written to the audit log (without the secrets).

Test

POST …/test with an optional {"amount": 100} (cents, 50 to 10000, default 100) opens a real hosted checkout for the store with clientReferenceId gp-integration-test:<integrationId>. It is a real payment that settles to the store's settlement wallet; there is no separate test mode.

GET …/test returns status:

Status	Meaning
`not-started`	No test checkout yet
`awaiting-payment`	The session is open
`paid-awaiting-webhook`	Paid; the signed `checkout.session.completed` has not been accepted by the endpoint yet (`delivery` shows the HTTP status and next retry)
`completed`	Paid and delivered (2xx), or paid and shown in the event viewer when the integration has no endpoint

The response also carries event: the exact checkout.session.completed body the webhook sends.

Health

For each started integration: the plugin version it reported and the registry's current version (updateAvailable), the last successful payment made through it (sessions created with its API key, or through payment links for site builders), the last webhook delivery to its endpoint and the last successful one, the API key's last use, and webhook or API errors (HTTP 4xx/5xx with its key) from the last 7 days.

Plugin version header

Plugins send their name and version on every API call:

http

X-GullyPay-Plugin: woocommerce/1.2.3

The format is <slug>/<semver>; the slug is the registry's pluginReport.slug. The version is recorded only for calls authenticated with a store API key that belongs to the store's merchant, at most once a minute per store and version. WooCommerce builds that do not send the header yet are recognised by their User-Agent: GullyPay-WooCommerce/<version>.

Public payment links

https://gullypay.xyz/pay/<slug> shows the link and calls POST /payment-links/:slug/checkout, which opens a fresh hosted checkout for the amount stored on the link (the caller cannot change it) with clientReferenceId plink:<slug>. Inactive links return 400; unknown links 404. The endpoint is limited to 10 requests a minute per IP.

Downloads

Installable artifacts listed in the registry are served at https://gullypay.xyz/downloads/<file> (for example gullypay-woocommerce-1.0.0.zip). Only file names in the registry are served.