WooCommerce Plugin

Spayon for WooCommerce connects a WooCommerce store to Spayon using an offsite checkout flow: the plugin creates a Spayon payment session for each order, redirects the customer to the hosted Spayon payment page, then updates the WooCommerce order when Spayon sends a signed callback.

Overview

For every order paid with Spayon, the plugin:

1. Requests a Bearer token from POST /api/tokens.
2. Creates a session with POST /api/product/session using the order's amount and currency.
3. Redirects the customer to the returned session_url.
4. Receives a signed callback from Spayon and updates the order status.
5. Falls back to polling GET /api/product/session/{id} when the customer returns to the store.

What You Need

• A WordPress site with WooCommerce installed
• A Spayon vendor account
• Your Client ID and Client Secret (from the Vendor Admin Panel)
• A production site served over HTTPS

TIP

Production callbacks must use HTTPS. In Sandbox, HTTP is also accepted.

Install the Plugin

1. Download the plugin ZIP provided by Spayon.
2. In WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Upload the ZIP file and activate the plugin.
4. Go to WooCommerce → Settings → Payments.
5. Find Spayon for WooCommerce and click Manage.

Configure the Plugin

Field	Source	Notes
Client ID	Vendor Admin Panel	Used to obtain Bearer tokens
Client Secret	Vendor Admin Panel	Used for API authentication
Callback Secret	Optional	Used to verify the X-Signature on callbacks. Leave empty to use the Client Secret.
Default Payment Method	Optional	Pre-selects a method: visamaster or mir
Available Methods	Optional	Comma-separated list, e.g. visamaster,mir
Payment Page Language	Optional	en, hy, or ru

Callback Secret

Spayon currently signs callbacks with your Client Secret. Leave the Callback Secret field empty and the plugin verifies callbacks with the Client Secret automatically. Only set Callback Secret if Spayon issues you a separate one in a future release — and if you do, it must match exactly, or callbacks fail with 401 invalid_signature.

Currency

The plugin forwards the WooCommerce order currency to Spayon. Only enable this gateway for currencies Spayon supports: AMD, RUB, USD, EUR, GBP. Orders in any other currency are rejected at session creation.

Callback and Return URLs

The plugin registers these REST routes on your store automatically:

URL	Purpose
https://your-store.com/wp-json/spayon/v1/callback	Receives signed payment callbacks (POST)
https://your-store.com/wp-json/spayon/v1/return	Lands the returning customer and polls session status (GET)

Both must be reachable from the public internet.

How the Flow Works

1. The customer selects Spayon at checkout.
2. The plugin requests a Bearer token from Spayon.
3. The plugin creates a payment session and stores session_id on the order.
4. The customer is redirected to the hosted Spayon payment page.
5. Spayon sends a signed callback to the store's callback URL.
6. The plugin verifies the X-Signature (HMAC SHA256) and updates the order.
7. When the customer returns, the plugin also polls the session status as a fallback.

See Callbacks & Returns for the signature scheme and payload details.

Order Status Mapping

Spayon status	Plugin action	Merchant-visible result
paid	Calls payment_complete()	Order moves to the paid / processing flow
pending	Keeps order on hold	Order waits for a later callback or return poll
failed	Adds a failure note	Order is not marked successful; status is left unchanged
expired	Adds an expiry note	Order is not marked successful; status is left unchanged

Failed and expired sessions

The plugin intentionally leaves the order status unchanged on failed or expired so a customer can retry without the order being force-cancelled. Review such orders manually and cancel them in WooCommerce if needed.

Troubleshooting

Spayon API errors

Where it happens	Technical error	Meaning	What to check
Token request	spayon_missing_creds	Client ID or Client Secret missing	Enter both credential fields and save
Token request	spayon_token_error	Could not get a Bearer token	Check Client ID, Client Secret, and outbound HTTPS access
Session creation	spayon_session_error	Spayon rejected the session	Check request fields, currency support, and available methods
Session status polling	spayon_status_error	Could not fetch session status	Check the stored session ID and token flow

Callback and return errors

Endpoint	Result	Meaning	Most likely cause
Callback	401 invalid_signature	Signature verification failed	Wrong secret, a Callback Secret set that does not match what Spayon signs with, wrong URL, or copied spaces
Callback	404 order_not_found	Valid callback but no matching order	Wrong order ID, missing stored session ID, or unknown order
Return	500 token_error	Could not authenticate to poll status	Wrong or missing API credentials
Return	404 order_not_found	Return URL reached but no order matched	Broken return parameters or missing session mapping

Customer pays but the order stays pending

• Check whether the callback reached the site (look for a Spayon order note).
• Check whether the callback signature passed — a 401 means the secret does not match. Leave Callback Secret empty so the plugin uses the Client Secret.
• Check whether the return poll fetched the session status successfully.

Go-Live Checklist

• [ ] Plugin installed and activated
• [ ] Payment method enabled in WooCommerce
• [ ] Client ID and Client Secret entered
• [ ] Callback Secret left empty (recommended) — the plugin then uses your Client Secret automatically
• [ ] Callback URL reachable from the public internet
• [ ] HTTPS enabled on the production site
• [ ] A test payment completed successfully