VibeFox SimplePay 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.

Order currency: HUF, EUR or USD. SimplePay does not accept other currencies, and the payment method is not offered for carts in them. Your store must offer the currency itself; the module does not add currencies or currency rates.

SimplePay merchant accounts: SimplePay gives a separate merchant account for each currency, and separate accounts for live and sandbox. For each account you need its MERCHANT and SECRET KEY from the SimplePay merchant admin (admin.simplepay.hu for live, sandbox.simplepay.hu for sandbox), account > Technical data. If you sell only in HUF, the HUF account is enough. No other keys are needed.

Reachable store: SimplePay sends the IPN to your store after each payment, so the site must be reachable from the internet.

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-simplepay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/SimplepayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_SimplepayPayment 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 SimplePay 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. Enter the merchant IDs and secrets of your SimplePay accounts for every currency you sell in: the sandbox accounts for testing and the live accounts for real payments. Copy the IPN URL shown at the top of the group into every merchant account (live and sandbox) in the SimplePay merchant admin. Keep Sandbox mode at Yes, set Enable to Yes, click Save Config and place a test order. When everything works, set Sandbox mode to No and click Save Config.

The module adds the SimplePay (Card Payment) 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 its own tables for the SimplePay payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox SimplePay 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. The license block and the Log are shown in the Default Config only. Delete Settings on Uninstall is read from the Default Config only, so set it there. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title (Enter a title for the payment method.); an Order Status After Payment that is not in the list (Select a valid order status.); 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.). Use a dot as the decimal separator, for example 9.99. Merchant IDs are saved without spaces at the start and end; their format is not checked when you save.

IPN URL

The first row after the license block shows Configure this IPN URL in each SimplePay merchant account: and the IPN URL of your storefront (the default store view, also when the Admin has its own address), which looks like https://your-store/wcpsimplepaygateway/checkout/notify, and the line HUF, EUR and USD are supported. Configure an account for the checkout currency. Set this URL for every merchant account, live and sandbox, in the SimplePay merchant admin. Copy the URL exactly as the settings show it, because a redirected IPN is lost.

While Enable is Yes, the row also shows warnings: No complete SimplePay account for the store currency and selected environment. The method is hidden. and, while sandbox mode is on, Sandbox mode is on. No real money is charged. The warnings follow the Default Config.

The IPN is the message SimplePay sends to your store when the payment status changes. It must be signed with the SECRET KEY of the merchant account the payment was started with, in the same mode (sandbox or live), and for the merchant account, order reference and SimplePay transaction of that payment. IPNs without a valid signature are rejected. The module confirms each accepted IPN to SimplePay in the signed form SimplePay requires. The IPN is handled with the settings of the store view where the order was placed, also when Enable is No or the license is not active. These IPN statuses are used:

A rejected, cancelled or timed-out status cancels the order only for the latest payment attempt of the order, and never after money was received. Other statuses change nothing. Without the IPN, an order is confirmed only when the customer comes back to the store after a successful payment.

General

Enable: shows or hides SimplePay at checkout. It is shown only when the cart currency has a complete merchant account in the current mode. Default: No.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: SimplePay (Card Payment). Required.

Description: the text shown under the payment method at checkout when the customer selects it. Default: Pay securely with your credit or debit card via SimplePay. Hungarian merchants can put the SimplePay data transfer declaration here.

Sandbox mode: No real payment in sandbox mode. A separate merchant account is required for every currency and environment. It switches both the SimplePay API address and the merchant accounts: the sandbox accounts while it is Yes, the live accounts while it is No. Default: Yes. Set it to No to take real payments. While it is on, customers see TEST MODE — no real payment. Do not ship test orders. under the payment method.

Merchant accounts

Fill in the accounts of the currencies your store sells in. The MERCHANT and SECRET KEY values are in the SimplePay merchant admin, account > Technical data: admin.simplepay.hu for the live accounts, sandbox.simplepay.hu for the sandbox accounts. An account is used only when both its merchant ID and its secret are filled in.

Sandbox HUF merchant ID and Sandbox HUF secret: the MERCHANT and SECRET KEY of your sandbox HUF account.

Sandbox EUR merchant ID and Sandbox EUR secret, Sandbox USD merchant ID and Sandbox USD secret: the same for your sandbox EUR and USD accounts.

Live HUF merchant ID and Live HUF secret: the MERCHANT and SECRET KEY of your live HUF account.

Live EUR merchant ID and Live EUR secret, Live USD merchant ID and Live USD secret: the same for your live EUR and USD accounts.

Magento stores the secrets encrypted and shows only a mask (******) after saving: Leave the mask to keep the saved secret. Empty field deletes it. Type a new value to change it. To delete a saved secret, clear the field and click Save Config.

Each payment remembers the merchant account and mode it was started with. Its IPNs, status requests and refunds always use that account, also after you switch between sandbox and live, so keep the accounts of the old mode while such payments are open or may be refunded.

Orders

Order Status After Payment: the order state set after a successful payment. Physical orders remain Processing until Magento shipment completes. Canceled or closed orders are never reopened.

A payment for another amount or currency than the order always puts the order On Hold.

Logging

Debug Logging: writes SimplePay requests, IPNs and returns to var/log/simplepay_op_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Secrets and e-mail addresses are hidden in the log. Errors and warnings are always logged, even when this is off. Default: No.

Log: the last row of the group shows the size and the latest entries of the log. Click Clear log to empty it.

Uninstall

Delete Settings on Uninstall: Deletes only this module settings and log. Transaction and refund history is always retained. It works when you uninstall the module with its data (see Uninstall). The license key is always removed. Default: No.

Restrictions

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

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

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

Maximum Order Total: offer SimplePay only up to this order total, in the base currency. Leave it empty for no maximum: a typed value such as 0.00 is treated by Magento as a limit and hides the payment method.

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

Checkout

At the payment step the customer chooses the payment method (by default SimplePay (Card Payment)) and sees the description and the note You will be redirected to SimplePay 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 starts a SimplePay card payment for the order total in the order currency, with the merchant account of that currency in the current mode, and sends the customer to the SimplePay payment page. Card data never touches your site.

HUF amounts are sent as whole forints, EUR and USD with two decimals. The customer's e-mail and, when it is complete (name or company, country, city, postcode and street), the billing address are passed to SimplePay. The payment page uses the language of the store view locale when SimplePay supports it, otherwise English. A started payment can be paid within 30 minutes. Each attempt gets its own SimplePay order reference: MG, the internal order ID and the attempt number, for example MG123-45.

After the payment the customer returns to your store. The return alone never pays an order: after a signed successful return the module asks SimplePay for the status of the transaction with a signed request, so the order is confirmed even if the IPN is late. The order is marked paid only after SimplePay confirms it. Then Magento creates the invoice with the SimplePay transaction ID as the transaction ID, the order moves to the state set in Order Status After Payment and the order e-mail is sent. The customer sees the standard order success page with Successful transaction. SimplePay transaction ID: and the ID.

If SimplePay has not confirmed the payment yet, the customer sees a SimplePay payment status page with Your SimplePay payment is being confirmed. Do not pay again while confirmation is pending. and a Check again button; the IPN confirms the order as soon as it arrives. The return page works only in the browser where the order was placed; in another browser the customer lands in the cart.

If the payment fails, is cancelled or times out, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with the message and the SimplePay transaction ID: Payment was cancelled. Please try again., Payment timed out. Please try again. or The transaction was unsuccessful. Please try again. The customer can pay again or choose another payment method. A new attempt is a new order.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees SimplePay could not be started. Please try again. If the order currency has no merchant account in the current mode or the method is disabled, the message is SimplePay is not configured for this order currency. The technical reason is written to the log.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If SimplePay later reports a payment for a cancelled order, the order is not invoiced and not reopened: a note asks you to reconcile or refund the payment in the SimplePay administration.

The module works with the standard Magento checkout. It takes one-time card payments only, captured on the SimplePay page. It has no saved cards or one-click payments, no subscriptions or recurring payments and no separate authorize and capture. SimplePay is not offered for orders created in the Admin or for checkout with multiple addresses.

Orders and refunds

Order statuses

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

Processing or Complete: SimplePay confirmed the payment. The state follows Order Status After Payment. The invoice is created with the SimplePay transaction ID, and a note shows the transaction ID and whether the IPN or the status request confirmed it.

On Hold: the paid amount or currency differs from the order, or the payment arrived while you had put the order on hold. No invoice is created. The note shows the reason. Check the order and fulfil it or refund the payment in the SimplePay merchant admin.

Canceled: the payment failed, was cancelled or timed out at SimplePay, the payment could not be started, or the order was cancelled in Magento.

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

A paid, cancelled or closed order is never reopened by a later IPN, and repeated IPNs and returns, even at the same moment, never invoice an order twice. If another payment succeeds for a cart that is already paid, the original payment is not changed: a note asks you to reconcile or refund the duplicate in the SimplePay administration. The notes are order comments that the customer does not see.

SimplePay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, SimplePay transaction ID, SimplePay environment (sandbox or live) and SimplePay refund. 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 SimplePay. 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 SimplePay.

The refund is sent for the SimplePay transaction that paid the order, in the order currency, with the merchant account and in the mode (sandbox or live) of that payment, so that account must still be in the settings. The credit memo total can be at most the amount SimplePay charged minus the amounts already refunded. HUF is refunded in whole forints: Magento keeps HUF totals with decimals, while SimplePay charged the rounded total, so each credit memo sends its rounded share (for example 600.28 and then 634.28 of an order of 1234.56 HUF paid as 1235 send 600 and 635), and the credit memo that closes the order sends exactly the rest of the payment. EUR and USD are refunded to the cent. If SimplePay does not accept or confirm the refund, Magento shows the error and the credit memo is not created. After a successful refund Magento records it on the order with a refund transaction ID, and a full refund closes the order. An order on hold has no invoice and cannot be refunded online: refund it in the SimplePay merchant admin.

Every refund request is recorded before it is sent. If the answer of SimplePay is lost or unclear, no further online refund of that order is sent, so that money is never refunded twice: check the refund in the SimplePay administration. Refunds made in the SimplePay merchant admin are not recorded in Magento. Create a credit memo with Refund Offline to record them.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox SimplePay Gateway is the first row of the VibeFox SimplePay Gateway group in Stores > Configuration > Sales > Payment Methods (Default Config scope), 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 store. Below them are the line Product: magento-payment-simplepay 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, SimplePay 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 This payment method is not available. Please choose another one. 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

SimplePay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the cart currency is HUF, EUR or USD, and that this currency has both the merchant ID and the secret in the current mode: the sandbox fields while Sandbox mode is Yes, the live fields while it is No. 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 IPN did not reach the store. In the SimplePay merchant admin check the IPN URL of the merchant account you use (live or sandbox, the currency of the order). It must be exactly the URL shown in the settings, and your server must be reachable from the internet. The order is also confirmed when the customer returns to the store after paying. Turn on Debug Logging to see the IPN.

IPN answers Invalid signature: the IPN names a merchant account that is not in the settings, its secret is wrong, or it is signed by the account of the other mode than the payment. Enter the MERCHANT and SECRET KEY exactly as the SimplePay merchant admin shows them. SimplePay repeats unconfirmed IPNs.

IPN answers Order not found or Unknown transaction: the IPN is for a payment that this store did not start. Nothing is changed. Empty body. and Invalid JSON. mean that the request was not a SimplePay IPN.

IPN answers Busy, retry: the order was being processed by another request at the same moment, or the order could not be updated. SimplePay retries the IPN. The reason is written to the log.

IPNs fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the IPN and return URLs too. The order is confirmed by the next IPN or return that reaches the store.

The customer is back in the cart with SimplePay could not be started: look at the Log field. A wrong secret gives Invalid response signature from SimplePay. Check the secret key of the merchant account. SimplePay errors are logged with their error codes. The order of that attempt is cancelled.

The order is On Hold after payment: read the note on the order. Check the payment in the SimplePay merchant admin, then fulfil the order or refund the payment there.

The refund says Invalid refund amount or currency; exceeds captured funds.: the credit memo total is more than the amount left to refund through SimplePay, or the currency of the order is not the currency of the payment. Check the refunds already made, including those recorded with Refund Offline.

The refund says Stored-account SimplePay credentials are missing.: the merchant account (currency and mode) the payment was made with is no longer in the settings. Enter it again and try again.

The refund says SimplePay refund was not confirmed. Reconcile in SimplePay administration before retrying.: SimplePay refused the refund or its answer was lost. Look at the Log field and check the refund in the SimplePay administration. When SimplePay clearly refused it, you can try again. When the result is unclear, the next attempt says An earlier SimplePay refund is unconfirmed. Reconcile it before retrying. and no further online refund of the order is sent: finish it in the SimplePay merchant admin and record it with Refund Offline.

The refund says No matching paid SimplePay invoice. Review/refund in SimplePay administration.: the order has no payment confirmed by SimplePay through the module, for example it is On Hold after a mismatch. Refund it in the SimplePay merchant admin.

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 cannot be refunded online.

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.

For developers: the event simplepay_op_payment_data lets you add fields to the payment request; the amount, currency, merchant, order reference and return URL cannot be changed by it.

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_SimplepayPayment. It removes the data and the code.

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

The license key and license status are always removed. If Delete Settings on Uninstall is Yes, the module settings of all scopes and the log are removed too. If it is No, the settings are kept for a re-install. The tables with the SimplePay payment attempts and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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