Wix

Wix integrates via the Wix Velo Service Plugin (Payment Provider) contract — a developer pattern Wix supports out of the box. There's no App Market install today; the merchant pastes four small JavaScript files into their Wix Studio backend, publishes the site, and pastes their Genius Checkout API key into the Wix Payments dashboard.

The full developer install guide with code lives at Wix Plugin. This page is the merchant-facing summary.

Wix Studio required

The Velo Service Plugin path is only exposed in Wix Studio editor. Classic Wix Editor sites need to upgrade to Studio first (free; takes seconds). After upgrade, Develop → Backend appears in the sidebar.

What you install

Four JavaScript files. All four are committed to our public repo under storefront-plugins/wix-genius-checkout/ and the full install guide at /en/wix-plugin embeds each one with copy buttons. The files and where they go in Wix Studio:

File	Wix Studio location	What it does
gc-payments.web.js	Develop → Backend (root)	Shared helpers — minor-unit math, HMAC signature verification
http-functions.js	Develop → Backend (root)	Public webhook endpoint at /_functions/gcPaymentNotify so we can notify Wix when a payment completes
genius-checkout.js	Develop → Backend → Service Plugins → Payment Provider → genius-checkout	The SPI handler — connectAccount, createTransaction, refundTransaction
genius-checkout-config.js	Same folder	Config that tells Wix this provider exists and what credential fields to render

Two wix-data collections also need to exist (created from Wix Studio's Databases sidebar with permission Anyone):

• gcConfig — holds the merchant's API key for this site (single row keyed by _id: 'singleton')
• gcEventLog — webhook idempotency log

Step-by-step

1. Open Wix Studio. Make sure your site is in Wix Studio, not the classic Editor. If you see Develop in the left sidebar, you're in Studio.
2. Create the two collections. Sidebar → CMS → Databases → + Add Collection. Name them exactly gcConfig and gcEventLog. Permissions → Anyone can read/write.
3. Paste the four files into the locations in the table above. Each file's full content is at /en/wix-plugin (the developer guide) with copy buttons.
4. Publish the site. This is required — the SPI's connectAccount step reads context.publicBaseUrl and refuses to connect if the site is still in preview-only mode.
5. Open Wix Payments. Site dashboard → Settings → Accept Payments. Genius Checkout now appears as a payment option.
6. Click "Connect." Wix renders a tiny form with a single field: Genius Checkout API key.
7. Paste your gc_live_… key (from the GC merchant portal → API Keys). For sandbox testing, paste a gc_test_… key instead.
8. Click Save. If everything's wired correctly, you'll see a green "Connected" badge. If you see an error, see the troubleshooting list below.

What happens automatically

When the merchant clicks Save on the API key form, our backend:

1. Validates the API key by calling GET /api/v1/webhooks. Bad keys reject with a clear "API key was rejected" message before anything is saved.
2. Auto-registers a webhook subscription at https://<merchant-site>/_functions/gcPaymentNotify so we can notify Wix when a payment completes. The signing secret is derived from the API key — no manual webhook secret pasting.
3. Persists the API key to the merchant's gcConfig collection so the http-functions.js webhook handler can re-derive the secret on every inbound notification.

No additional configuration needed.

Supported currencies

Genius Checkout accepts Wix payment requests in any currency your configured gateway supports. The Velo SPI converts Wix's major-unit amounts to the right minor-unit factor automatically:

• 0 decimals: JPY, KRW, BIF, CLP, VND, etc.
• 3 decimals: BHD, JOD, KWD, OMR, TND
• 2 decimals: everything else (USD, EUR, JMD, TTD, BBD, XCD, ...)

Subscriptions (recurring orders)

Wix's Stores SDK supports recurring billing through the same SPI. When a Wix order has a recurring line, our handler:

1. On the first charge, opens our hosted checkout with save_payment_method: true so the card is tokenized.
2. After payment completes, creates a MerchantSubscription row on the GC side tied to the Wix subscription.
3. On every renewal, Wix calls createTransaction again with offSession: true and the stored token — we charge the saved card non-interactively and return immediately.

Cancel a Wix subscription → recurring stops on the GC side. Cancel from the GC portal → the next Wix renewal attempt receives a decline.

Wix Pricing Plans

Wix's separate Pricing Plans product (memberships) is gated to apps installed via the official Wix App Market, not the Velo / Service Plugin flow. Pricing Plans support is on the roadmap once App Market submission completes.

Refunds

Refunds initiated in your Wix Studio → Order details → Refund dialog call our refund endpoint with the order id and amount. We issue the refund through your configured gateway and reply with success/failure plus the original card brand/last4 (rendered in the Wix refund row).

Refunds initiated from the GC portal also propagate to Wix via the payment.refunded webhook event — the Wix order updates to "Refunded" automatically.

Troubleshooting

"Service Plugin not available" (Wix error 2402) — the SPI files have a module-load throw. The most common cause is importing wix-secrets-backend.v2 or calling wix-auth.elevate() — neither is allowed in the Velo SPI sandbox. Use the exact files from our repo verbatim.

"Publish your Wix site first" — Wix's context.publicBaseUrl is undefined for unpublished sites. Click Publish in Studio (top-right), wait for the green confirmation, then click Save on the API key form again.

"That API key was rejected" — wrong key or revoked. Generate a fresh gc_live_… from API Keys and paste it.

"Could not write Genius Checkout config to the gcConfig collection" — the gcConfig collection doesn't exist, or its permissions block writes. Create it in CMS → Databases with permission Anyone and retry.

Payments complete on the hosted checkout but Wix order stays "pending" — the webhook from us isn't reaching /_functions/gcPaymentNotify. Check Webhook Deliveries for failed deliveries. Most common cause: the merchant's site is in Studio preview but never Published.