VibeFox Satispay for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later with the OpenSSL extension. The module refuses to install on older PHP versions or without OpenSSL.
Currency: EUR. Satispay charges euros only, so the payment method is hidden when the cart currency is not EUR.
Satispay account: a Satispay Business account. You do not copy any API keys: the module 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 shop: your shop 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox Satispay Gateway in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. Choose the environment: turn on Sandbox Mode for tests, leave it off for real payments.
5. Paste an activation code of that environment into Activation Code and click Save. The Status field then shows Connected with the Key ID.
6. Turn on Enable/Disable and click Save. Test a payment in the sandbox, then turn off Sandbox Mode and connect the live environment with a live activation code.
On install the module creates the order status Satispay payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences. The module must be allowed for the euro there.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox Satispay Gateway > Configure. Each section has its own Save button, which saves the whole page.
Checkout
What customers see in the list of payment methods.
Enable/Disable: Enable Satispay payment turns the payment method on or off. Default: off.
Title: the payment method name shown at checkout. It is also the payment method name stored in the order. Default: Satispay. Required.
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
Status: the state of both environments, for example Live: Connected with the Key ID or Sandbox: Not connected, and which environment is in use. While the environment in use is not connected, the field says Satispay is hidden at checkout until the environment in use is connected.
Sandbox Mode: uses 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 click 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 module 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 shop configuration. The private keys are never shown. 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 activation failed: with 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 module re-reads the payment from the Satispay API before an order is created or changed. The Callback URL field shows an example of this URL. With friendly URLs it looks like https://your-shop/module/wcp_satispay_gateway/callback?id_cart={cart}&payment_id={uuid}, possibly with a language code such as /en/. The URL must be reachable from the internet: no basic authentication in front of it. The callback works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.
Advanced
Debug log: writes API calls and payment events to logs/satispay_p_debug.log.php in the module folder. The file cannot be opened from the web. Keys and customer data are not logged. Errors are always logged, even when this is off. Default: off.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Delete data on uninstall: when on, uninstalling the module removes the settings, the Satispay keys of both environments and the log. The Satispay payments and refunds saved for orders and the order status Satispay payment on hold are always kept. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default Satispay) and confirms the order. The module creates a Satispay payment for the cart total in euros, with the cart 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. No order exists yet at this point.
After the payment the customer returns to your shop. The order is marked paid only after Satispay confirms it: the module reads the payment from the Satispay API, checks that it was created for this cart and compares its status, amount (in cents) and currency with the cart. This happens both when Satispay calls the callback URL and when the customer returns, whichever comes first. The order is then created and the customer sees the standard order confirmation page. If Satispay has not confirmed the payment yet when the customer comes back, a Payment confirmation page shows Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. and a Check again button. The callback creates the order as soon as it arrives.
If the customer leaves the Satispay page without paying, the module cancels the payment at Satispay, so the abandoned page can no longer be paid. The customer is back at checkout 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. The cart is kept.
Before a new Satispay payment is created for the same cart, the previous one is checked: a pending payment is cancelled at Satispay, and if it was already paid, the order is created with it and no second payment is made.
If the payment cannot be started, the customer stays at checkout with a short message: Satispay is not available at the moment. Please choose another payment method. when the shop 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 module 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 shop, no order is created, and the payment is visible in the Satispay Dashboard.
Orders and refunds
Order statuses
No order yet: the customer was sent to Satispay and has not paid, or Satispay has not confirmed the payment yet. Only the cart and the Satispay payment of the module exist.
Payment accepted: the payment was confirmed. The payment is recorded with the Satispay payment ID as the transaction ID, and a note shows the Satispay payment, the amount and how it was verified (callback, redirect or checkout).
Satispay payment on hold: Satispay reported a different amount or currency than the cart total (for example, the cart was changed in another tab after the payment started), or the payment was accepted after the order had been cancelled. The money received is recorded on the order, and the note explains it. Check the payment in the Satispay Dashboard, then fulfil the order or refund the payment. If another payment of the same cart with the right amount is accepted later, the order moves to Payment accepted.
Refunded: the payment was fully refunded through the module.
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.
Satispay payment block
The order page shows a Satispay payment block with the Satispay payment ID, its status, the amount paid and refunded, a Sandbox badge for sandbox payments, the refund history, the list Satispay payments of this cart with every payment attempt and its environment, and the Satispay notes of the order.
Refunds
In the Satispay payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Satispay. Confirm the question Refund this amount through Satispay? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the Modules pages is not needed. Refunds are limited to the amount Satispay charged for the payment, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. 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 refund history and the notes with the Satispay refund ID and the reason. If Satispay does not accept the refund, the block shows the error and no refund is recorded. A full refund sets the order to Refunded. A partial refund does not change the status.
The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Satispay. Refunds made in the Satispay Dashboard are not recorded in PrestaShop. Update the order manually if needed.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Satispay Gateway is the first block on Modules > Module Manager > VibeFox Satispay Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-satispay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.
Troubleshooting
Satispay does not appear at checkout: check that the license is active, Enable/Disable is on, the environment in use is connected (the Status field shows Connected for it) and the cart currency is EUR. In Payment > Preferences check that the module is allowed for the euro, the customer's country and the customer's group.
The payment went through, but no order was created: the order is created when Satispay calls your shop or when the customer returns. Check that your shop is reachable from the internet, with no basic authentication in front of the callback URL, and turn on Debug log to see the callbacks in the Log field. The payment is visible in the Satispay Dashboard.
Callback answers Payment status unavailable, retry later. or Not configured.: the module could not read the payment from Satispay, or the environment of the payment is not connected. No order is changed. Satispay calls again. Check the connection status and the log.
Callback answers Busy, retry later.: the cart was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). Satispay calls again. The log shows the reason.
Callback answers Unknown payment. or Missing or invalid payment_id.: the payment was not created by this shop for this cart, or the request is not a Satispay callback. Nothing is 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. If Satispay could not be reached, check that your server can open outgoing HTTPS connections.
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 off and save.
The customer sees This payment method is not available.: the payment method is not allowed for the cart (country, currency or customer group in Payment > Preferences), is disabled or the environment in use is not connected.
Order is Satispay payment on hold after payment: read the notes in the Satispay payment block (see Order statuses), check the payment in the Satispay Dashboard, then fulfil 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. PrestaShop did not record the refund, and a note says so. Check it in the Satispay Dashboard.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Satispay Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings, the Satispay keys of both environments and the log are removed. If it is off, all settings and keys are kept for a later re-install. The Satispay payments and refunds saved for orders and the order status Satispay payment on hold are always kept, so orders paid before can still be refunded after a re-install once the environment is connected again. Existing orders keep their payment notes and transaction IDs.
Satispay is a trademark of its respective owner. This module is not affiliated with or endorsed by Satispay.