VibeFox Satispay for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later with the OpenSSL extension. Without OpenSSL the plugin shows an error in the admin area and the payment method is not loaded.

Currency: EUR. Satispay charges euros only, so the payment method is hidden when the store currency (or, on the Pay for order page, the order currency) is not EUR.

Satispay account: a Satispay Business account. You do not copy any API keys: the plugin connects with a one-time activation code that you generate in the Satispay Business Dashboard (see Configuration). For tests you need a Satispay sandbox account, which you request from Satispay for developers.

Public site: your site must be reachable from the internet, so that Satispay can call it when a payment changes. Nothing has to be configured in Satispay for this.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_satispay_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Satispay > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Choose the environment: tick Sandbox Mode for tests, leave it unticked for real payments.

6. Paste an activation code of that environment into Activation Code and save. The connection status then shows the Key ID.

7. Turn on Enable/Disable and save. Test a payment in the sandbox, then untick Sandbox Mode and connect the live environment with a live activation code.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Satispay. The Satispay connection section shows the state of both environments, for example Live: Connected with the Key ID or Sandbox: Not connected, and marks the environment in use. While the environment in use is not connected, the page says Satispay is hidden at checkout until the environment in use is connected. In the WooCommerce list of payment methods, Satispay is marked as needing setup until the environment in use is connected, and shows a test mode badge while Sandbox Mode is on.

Enable/Disable: Enable Satispay payment turns the payment method on or off. Default: off.

Checkout

What customers see in the list of payment methods.

Title: the payment method name shown at checkout. Default: Satispay.

Description: the text shown under the payment method at checkout. Default: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Satispay connection

Sandbox Mode: Use the Satispay sandbox (staging) environment. Sandbox payments are not charged. Default: off. Sandbox and live have separate keys: connect each environment with an activation code of that environment. While the sandbox is in use, customers see Sandbox mode: no real money is charged. under the payment method.

Activation Code: to connect the environment selected above, paste a new 6-character activation code and save. Live codes are generated in the Satispay Business Dashboard, section Online shop. Sandbox codes come with a Satispay sandbox account. The code is used once and is not stored. Leave the field empty to keep the current connection.

When you save with a code, the plugin creates an RSA key pair, sends the public key and the code to Satispay and stores the Key ID and the keys of that environment in the WordPress database. On success the page shows, for example, Satispay Live connected. Key ID: followed by the ID. If Satispay rejects the code, the page shows Satispay's message and asks you to check that the code is for this environment and has not been used yet. A code with characters other than letters and digits is refused before anything is sent. Saving a new code for an environment replaces its previous connection.

Payment notifications

Nothing to configure in Satispay. Every payment carries its own callback URL, which Satispay calls when the payment changes, and the plugin re-reads the payment from the Satispay API before an order changes. The section shows an example of this URL. It looks like https://your-site/wc-api/satispay_payment_callback/?action=callback&order_id={order}&payment_id={uuid}. The URL must be reachable from the internet: no maintenance mode or password protection on /wc-api/.

Advanced

Debug log: Log API calls and payment events writes to WooCommerce > Status > Logs, source wcp_satispay_gateway, without keys or customer data. Errors are always logged, even when this is off. Default: off.

Delete data on uninstall: Remove the settings and Satispay keys when the plugin is deleted. Payment data saved on orders is kept. Default: off.

Checkout

The customer chooses the payment method (by default Satispay) and clicks Pay with Satispay. The plugin creates a Satispay payment for the order total in euros, with the order number as reference, and sends the customer to the Satispay payment page. On a computer the customer scans the QR code with the Satispay app. On a phone the customer confirms the payment in the app.

After the payment the customer returns to your store. The order is marked paid only after Satispay confirms it: the plugin reads the payment from the Satispay API, checks that it was created for this order and compares its status, amount (in cents) and currency with the order. This happens both when Satispay calls the callback URL and when the customer returns, whichever comes first. If the payment is not confirmed yet, the order received page shows Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives.

If the customer leaves the Satispay page without paying, the plugin cancels the payment at Satispay, so the abandoned page can no longer be paid. The customer is sent back to the checkout (or to the Pay for order page) with the message Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. The same message appears when the customer declines the payment in the app.

A customer can pay an unpaid order again, for example from the Pay for order page. Before a new Satispay payment is created, the previous one is checked: a pending payment is cancelled at Satispay, and if it was already paid, the order is marked paid with it and no second payment is created.

If the payment cannot be started, the customer sees a short message and can choose another payment method: Satispay is not available at the moment. Please choose another payment method. when the store is not connected or Satispay rejects the keys, or Unable to create the Satispay payment. Please try again or choose another payment method. for other errors. The reason is written to the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments in euros only. It has no subscriptions, saved payment methods, pre-authorisations or meal vouchers. There is no scheduled check of pending payments: if neither the Satispay callback nor the customer's return reaches your site, the order stays Pending payment, and the payment is visible in the Satispay Dashboard.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Satispay and has not paid yet, or Satispay has not confirmed the payment yet. The order note shows the Satispay payment ID, the amount and the environment (Live or Sandbox).

Processing or Completed: the payment was confirmed. The order follows the standard WooCommerce rule: Processing, or Completed for orders with only virtual downloadable products. The order note shows the Satispay payment, the amount and how it was verified (callback, redirect or checkout). The transaction ID is the Satispay payment ID.

On hold: Satispay reported a different amount or currency than the order total, or the payment was accepted after the order had been cancelled. The order note explains it, and the payment is saved as the transaction ID, so it can be refunded. Check the payment in the Satispay Dashboard, then complete the order or refund the payment.

Cancelled: the latest Satispay payment of the order was cancelled or expired, for example because the customer left the Satispay page. An older payment that expires does not cancel an order with a newer payment in progress. Orders that you created in the admin area (payment links) are not cancelled: they stay Pending payment with a note, so the customer can still pay them.

If a second payment is accepted for an order that is already paid, the order is not changed. A note asks you to refund the duplicate payment from the Satispay Dashboard. A repeated confirmation never reopens a cancelled or refunded order.

Refunds

Open the order, click Refund, enter the amount and click Refund via Satispay. Full and partial refunds are supported for orders paid with Satispay. The refund is sent to the environment the payment was made in (live or sandbox), so that environment must still be connected. A refund counts as done only when Satispay accepts it: a successful refund is added to the order notes with the Satispay refund ID and the reason. If Satispay does not accept the refund, WooCommerce shows the error and no refund is recorded.

Refunds made in the Satispay Dashboard are not turned into WooCommerce refunds. If needed, create a manual refund in WooCommerce without Refund via Satispay.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Satispay. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Satispay is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Satispay does not appear at checkout: check that the license is active, Enable/Disable is on, the environment in use is connected (the Satispay connection section shows Connected for it) and the currency is EUR.

The payment went through, but the order stays Pending payment: the order is updated when Satispay calls your site or when the customer returns. Check that your site is reachable from the internet, with no maintenance mode or password protection on /wc-api/, and look at WooCommerce > Status > Logs, source wcp_satispay_gateway. The payment is visible in the Satispay Dashboard.

Callback answers Payment status unavailable, retry later or Not configured: the plugin could not read the payment from Satispay, or the environment of the order is not connected. The order is not changed. Check the connection status and the log.

Callback answers Busy, retry later: the order was being updated by another request at the same moment. The order is not changed by this callback. It is updated by the next callback or when the customer returns.

Callback answers Unknown payment or Missing or invalid payment_id: the payment was not created for this order, or the request is not a Satispay callback. The order is not changed.

Activation fails: activation codes can be used once. Check that the code belongs to the environment selected in Sandbox Mode (a live code for live, a sandbox code for the sandbox), generate a new code and save again. If the page says that an RSA key pair could not be generated, ask your host to enable the PHP OpenSSL extension.

Satispay disappeared from the checkout after switching from sandbox to live: sandbox and live use different keys. Paste a live activation code with Sandbox Mode unticked and save.

Order is On hold with the note does not match the order: Satispay reported a different amount or currency than the order total, for example because the order was edited after the payment started. Check the payment in the Satispay Dashboard, then complete the order or refund the payment.

Refund fails because the environment is not connected any more: the payment was made in live or sandbox, and that environment has no keys now. Connect it again with an activation code, or refund the payment from the Satispay Dashboard.

Refund fails with Satispay did not accept the refund: Satispay returned a status other than accepted. WooCommerce did not record the refund. Check it in the Satispay Dashboard.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the Satispay keys of both environments and the plugin logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Satispay is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Satispay.