VibeFox Satispay for Adobe Commerce — ヘルプ

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the OpenSSL and cURL extensions.

Currency: EUR. Satispay charges euros only, so the payment method is hidden when the cart currency is not EUR. The base currency of your store can be another one, as long as the customer's cart is in euros.

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

Public store: your store 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-satispay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/SatispayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_SatispayPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Satispay Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Choose the environment: set Sandbox Mode to Yes for tests, leave it at No for real payments. Paste an activation code of that environment into Activation Code, set Enable to Yes and click Save Config. The Satispay connection row then shows Connected with the Key ID. Test a payment in the sandbox, then set Sandbox Mode to No and connect the live environment with a live activation code.

The module adds the Satispay payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Satispay payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Satispay Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete settings on uninstall is read from the Default Config only. Save Config saves the whole page. Order totals accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort Order that is not a whole number (Sort order must be a whole number.); a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a number, 0 or greater.).

Enable: shows or hides Satispay at checkout. It is shown only when the environment in use is connected. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Satispay. Required, at most 128 characters.

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

Sandbox Mode: uses the Satispay sandbox (staging) environment, where no real money is charged. Default: No. Sandbox and live have separate keys: connect each environment with an activation code of that environment. While the sandbox is in use, customers see TEST MODE — no real charges will be made. under the payment method.

Satispay connection: the state of both environments, for example Live: Connected — Key ID: followed by the ID, and Sandbox: Not connected. While Enable is Yes and the environment in use is not connected, the row says Connect the selected Satispay environment to show it at checkout. The row also shows the callback URL (see Payment notifications).

Activation Code: to connect the environment selected in Sandbox Mode, paste a one-time code from Satispay, 4 to 64 letters or digits, and click Save Config. Sandbox codes come with a Satispay sandbox account. The code is used once and is never stored, so the field is always empty after saving. Leave the field empty to keep the current connection.

When you save with a code, the other settings are saved first. The module then 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 Magento configuration, for the scope you are saving (Default Config or a website). The keys are stored encrypted and the private key is never shown. On success the page shows Satispay live connected. Key ID: (or Satispay sandbox connected. Key ID:) followed by the ID. If the code has other characters or Satispay rejects it, the page shows Satispay activation failed. Existing connection was kept. and your other settings stay saved. Saving a new code for an environment replaces its previous connection.

Payment from Applicable Countries: All Allowed Countries offers Satispay for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Satispay only for billing addresses in these countries.

Minimum Order Total: offer Satispay only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Satispay only up to this order total, in the base currency. Empty means no maximum. Leave it empty rather than typing 0.00: Magento treats 0.00 as a limit and hides the payment method.

Sort Order: the position among the payment methods at checkout. A whole number.

Debug Log: writes API calls and payment events to var/log/satispay_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys and customer data are not logged. Errors and warnings are always logged, even when this is off. Default: No.

Debug log viewer: shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Delete settings on uninstall: when Yes, uninstalling the module with its data deletes the settings, the Satispay keys of both environments and the log (see Uninstall). The license key is always removed. The Satispay payments and refunds saved for orders always stay. Default: No.

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 changed. The Satispay connection row shows the storefront address of this URL, of the default store view or of the default store view of the selected website, for example https://your-store/wcpsatispaygateway/checkout/notify. The payment itself uses the address of the store view of the order, with the order and payment IDs added. The URL must be reachable from the internet: no basic authentication in front of it. A callback is accepted whichever store view the order belongs to.

Checkout

At the payment step the customer chooses the payment method (by default Satispay) and sees the description and the note You will be redirected to Satispay to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Satispay payment for the order total in euros 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. The internal Magento order ID is passed to Satispay as the external code of the payment.

After the payment the customer returns to your store. The order is marked paid only after Satispay confirms it: the module reads the payment from the Satispay API with a signed request, 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. Magento then creates the invoice with the Satispay payment ID as the transaction ID and sends the order e-mail, and the customer sees the standard order success page. A customer who comes back in another browser lands on the home page, and the order is confirmed by the callback.

If the customer comes back while the payment is still pending, the module cancels it at Satispay, so the abandoned page can no longer be paid. The order is cancelled (the stock goes back), the cart is restored and the customer is in the cart with Satispay payment was canceled. You can try again. The same happens when Satispay reports the payment as cancelled.

If the state cannot be settled at that moment, for example when Satispay cannot be reached, a Satispay payment status page shows Satispay has not confirmed your payment yet. with a Check again button and, while the order is waiting, a Pay again button. Pay again closes the previous Satispay payment and creates a new one for the same order.

Before a new Satispay payment is created for the same cart, every earlier one is checked: a pending payment is cancelled at Satispay, and if it was already paid, that payment is applied and no second payment is made. If the payment cannot be started, the customer is back in the cart with Satispay payment could not be started. Try again or choose another payment method. On the first attempt the order of that attempt is cancelled and the cart is restored.

There is no scheduled check of pending payments. If neither the callback nor the customer's return reaches your store, the order stays in Pending Payment until you or the Magento cron cancel it after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). Cancelling an order in Magento does not close its Satispay payment.

The module works with the standard Magento checkout. It takes one-time payments in euros only. It has no subscriptions, saved payment methods, pre-authorisations or meal vouchers. Satispay is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Satispay, but Satispay has not confirmed the payment yet. There is no invoice.

Processing: the payment was confirmed. The invoice is created with the Satispay payment ID as the transaction ID, and a note says Satispay payment accepted through signed API verification.

On Hold after a mismatch: Satispay reported a different amount or currency than the order total. No invoice is created. The note says Satispay amount/currency mismatch. Money received; review required. Check the payment in the Satispay Dashboard, then fulfil the order or refund the payment there. If a later check finds the right amount, the module releases this hold and invoices the order. A hold you set yourself is never released.

Canceled: the customer did not pay, the payment was cancelled at Satispay, the payment could not be started, or the order was cancelled in Magento.

Closed: the payment was fully refunded with a credit memo.

If a payment is accepted after the order was cancelled or held, the order is not reopened. The note says Satispay accepted payment after order stopped waiting. Money received; manual review/refund required. Order was not reopened. If a second payment is accepted for a cart that is already paid, the order is not changed, and a note gives the ID of the payment to review and refund manually. These payments have no invoice, so refund them in the Satispay Dashboard. The notes are order comments that the customer does not see.

Satispay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title, one Satispay attempt # row for each attempt (payment ID, environment, status and amount) and one Satispay refund # row for each refund (Satispay refund ID, amount and status). It is shown also while the payment method is disabled. On the storefront the customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Satispay. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Satispay.

The refund is made in euros, up to the amount Satispay charged minus the amounts already refunded. It is sent to the environment the payment was made in (live or sandbox), also while Enable is No, so that environment must still be connected. A refund counts as done only when Satispay accepts it. A full refund closes the order. Refunds are available once Satispay has confirmed the payment and the order has an invoice.

If Satispay does not confirm the refund, Magento shows Satispay did not confirm the refund. Review it before retrying. and the credit memo is not created. When Satispay clearly rejected the request, you can try again. When the result is unknown, for example after a timeout, the money may have been sent, so the module blocks further online refunds of that payment with A previous refund is unconfirmed. Reconcile it in Satispay before retrying. Check the payment in the Satispay Dashboard and, if needed, finish the refund there and create a credit memo with Refund Offline.

Refunds made in the Satispay Dashboard are not recorded in Magento. Create a credit memo with Refund Offline or 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 row of the VibeFox Satispay Gateway group in Stores > Configuration > Sales > Payment Methods, above the settings, in the Default Config scope. 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 store. Below them are the line Product: magento-payment-satispay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees Satispay payment could not be started. Try again or choose another payment method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Satispay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the environment in use is connected (the Satispay connection row shows Connected for it) and that the cart currency is EUR. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the order is confirmed when Satispay calls your store or when the customer returns. Check that your store is reachable from the internet, with no basic authentication in front of the callback URL, and turn on Debug Log to see the API calls in the Debug log viewer. The payment is visible in the Satispay Dashboard.

Callback answers Satispay unavailable; retry or Retry: the module could not read the payment from Satispay, the environment of the payment is not connected, or an error occurred while the order was being updated. No payment is recorded. The order is confirmed by a later callback or when the customer returns. Check the connection status and the log.

Callback answers Busy: the order was being confirmed by another request at the same moment. A later callback or the customer's return finishes the work.

Callback answers Unknown payment, Invalid payment ID or Payment identity mismatch: the payment was not created by this store for this order, or the request is not a Satispay callback. Nothing is changed.

Callbacks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the callback URL and the return page too. The payment can be confirmed only by a later callback or return after the site is open again.

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) and that it has only letters and digits, get a new code and save again. Errors from Satispay and connection errors are written to the log. Your server must be able to open outgoing HTTPS connections, and PHP needs the 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 at No and click Save Config.

Order is On Hold after payment: read the order notes (see Order statuses), check the payment in the Satispay Dashboard, then fulfil the order or refund the payment.

A payment was accepted for a Canceled order: the order is not reopened. Refund the payment in the Satispay Dashboard, or place a new order if you want to fulfil it.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Satispay Dashboard.

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. Magento shows The Satispay live environment is not connected. Connect it with an activation code, then refund again. (or the same for sandbox), and nothing is sent to Satispay. Connect that environment and create the credit memo again, or refund the payment from the Satispay Dashboard and record it with Refund Offline.

Refund fails with A previous refund is unconfirmed or An accepted Satispay refund has no credit memo: an earlier refund of this payment has no clear result, or Satispay accepted it but Magento could not save the credit memo. The module does not send another request, so the customer cannot be refunded twice. Check the payment in the Satispay Dashboard and use Refund Offline for the amount already returned.

Refund fails with Refund exceeds the remaining payment or has an invalid amount/currency: the credit memo is larger than the amount Satispay charged minus earlier refunds. Reduce the amounts on the credit memo.

Refund fails with No accepted Satispay payment found: the order has no confirmed Satispay payment of its own. Check it in the Satispay Dashboard.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_SatispayPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_SatispayPayment to remove the data, then bin/magento module:disable Vibefox_SatispayPayment, delete the folder app/code/Vibefox/SatispayPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete settings on uninstall is Yes, the settings, the Satispay keys of both environments and the log are removed too. If it is No, all settings and keys are kept for a re-install. The Satispay payments and refunds saved for orders are always kept, so orders paid before can still be refunded after a re-install once the environment is connected. Existing orders keep their invoices, payment notes and transaction IDs.

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