Wix Plugin (Velo)

The Wix integration is a Velo Service Plugin SDK starter — drop it into a Wix Studio merchant's Velo backend to accept Genius Checkout payments through Wix's Custom Payments surface. This path is self-serve — no Wix App Market review required.

Two integration paths

Wix exposes the Payment Provider contract two ways:

Path	Integration target	Approval	When to use
REST app	Wix App Market app (server endpoints)	Wix Partner Program enrollment + 2-6 week review	A processor selling to many Wix merchants
Velo Service Plugin (this plugin)	One merchant's Velo site backend	Self-serve, immediate	A merchant who already has Wix Velo on their plan

If you're a single merchant, use the Velo plugin. If you're processing for many merchants, contact us about the REST app.

Install (5 minutes)

1. Open the Velo Service Plugin panel. In Wix Studio → Develop → Service Plugins → Add a Service Plugin → choose Payments → Wix Payments Provider.
2. Copy backend/payment-provider-spi.js from the GC-supplied starter into the file Wix generated (Wix auto-creates the right filename under backend/service-plugins/wix-payments/payment-provider/).
3. Add two secrets in Secrets Manager:
   • gcApiKey — copy from https://app.geniuscheckout.com/merchant/api-keys (use gc_test_… while testing, gc_live_… later).
   • gcReturnUrlBase — https://app.geniuscheckout.com (leave at default unless you're on a dedicated GC region).
4. Publish the Velo backend.

The plugin now appears as a Custom payments → Genius Checkout option in Wix → Settings → Accept Payments.

Configure on the GC dashboard

In the GC dashboard, set your Wix webhook URL to the URL Wix generated for the Velo backend (Wix exposes it under the Payments service-plugin panel as the "webhook URL"). Subscribe the endpoint to: payment.completed, payment.failed, payment.refunded.

Checkout flow

1. Buyer reaches Wix checkout, picks Genius Checkout.
2. Wix calls the Velo plugin's createTransaction(...) which POSTs to /api/v1/checkout-sessions and returns the hosted checkout_url for the buyer to be redirected to.
3. Buyer completes payment on the GC hosted page.
4. The merchant's Wix site receives the asynchronous status update; the buyer is returned to Wix with the final status (approved or declined).

Supported features

Capability	Status
Refunds	Yes — Wix calls refundTransaction(...) which hits POST /api/v1/payments/{id}/refund
Tokenization	Tokens stored on the GC platform; Wix doesn't expose a saved-card picker via the Service Plugin contract
Subscriptions	Not via Velo Service Plugin — use Wix's built-in Recurring Plans + GC's Subscriptions API if you need recurring billing
Currency-aware minor units	Yes — handled in the REST controller; the plugin passes currencyCode from Wix unchanged

Architecture notes

The Velo plugin uses the same /api/v1/checkout-sessions and /api/v1/payments/{id}/refund endpoints as the WC, Give, Odoo, PrestaShop, Magento, and OpenCart modules. All are live e2e-tested (see storefront-plugins/AUDIT-2026-05-13.md). The Velo file itself isn't e2e-tested because it requires a real Wix Studio site to install into — the merchant runs it.

Reference

• Velo Service Plugin docs (Wix)
• Genius Checkout API

Troubleshooting

• Method not appearing in Wix checkout — confirm the Velo plugin is Published (drafts don't propagate); the merchant's Wix plan must include Velo.
• gcApiKey not defined — re-check Secrets Manager; secret names are case-sensitive.
• 422 on session create — verify the cart currency is in the supported list; the plugin passes Wix's currencyCode straight through to GC.