VibeFox Peach Payments 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 extension (used to decrypt webhooks).

Currency: the order currency must be ZAR, KES or MUR. For other currencies the payment method is hidden at checkout. The base currency of the store can be a different one.

Peach Payments account: you need the Card API credentials of your Peach Payments account: the entity ID and the access token. Test credentials come from the Peach Payments sandbox dashboard, live credentials from the Peach Payments dashboard; they are different. For webhooks you also need a webhook decryption key, which Peach Payments sends you when they enable Card webhooks for your store (see Configuration). Your store must be reachable from the internet to receive webhooks.

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

2. Run bin/magento module:enable Vibefox_PeachPayment 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 Peach Payments Pay 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 test entity ID and test access token from the Peach Payments sandbox dashboard, and ask Peach Payments to enable Card webhooks for the webhook URL shown on the settings page (see Configuration). Keep Test mode at Yes, set Enable to Yes, click Save Config and place a test order with a Peach Payments sandbox test card. When everything works, enter the live credentials and the live webhook key, set Test mode to No and click Save Config.

The module adds the Credit / Debit Card (Peach Payments) 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 Peach Payments checkout attempts and the processed notifications.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Peach Payments Pay Gateway, in the standard Magento configuration form. Every setting can be changed for a website or a store view with the Scope switcher at the top of the page. Delete own data on uninstall is read for the default store view, so set it in the Default Config. The license block is only in the Default Config. Save Config saves the whole page.

If Title is empty or longer than 128 characters, Magento shows an error and nothing on the page is saved: Payment title is required and must not exceed 128 characters. When you save, all spaces are removed from the entity IDs, access tokens and webhook keys. A webhook key that is not a 64-character hexadecimal value is still saved, with the warning Peach Payments: invalid webhook key was saved; use 64 hexadecimal characters. Webhooks of that mode cannot be decrypted until you correct it.

The group has one list of fields, without subsections. The headings below only group them for this Help, in the order of the page.

General

Enable: shows or hides the payment method at checkout. It is shown only when the entity ID and access token of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Credit / Debit Card (Peach Payments). Required, at most 128 characters.

Description: shown at checkout, under the payment method when the customer selects it. Default: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

Test mode: sends new payments to the Peach Payments sandbox with the test credentials, and no real money is charged. Set it to No to accept real payments with the live credentials. A payment started in one mode is always checked in that mode, even after you switch. Default: Yes.

Setup information

This row of the group shows notices for the values of the Default Config, whichever scope you have selected. While Enable is Yes: Test mode: no real payment will be made.; The active mode requires an entity ID and access token.; A valid webhook key is required for authenticated notifications. When a saved webhook key has the wrong format, it also says Invalid test_webhook_key was saved. It must contain 64 hexadecimal characters; notifications for this mode cannot be authenticated. (or Invalid webhook_key was saved… for the live key).

It always shows Supported order currencies: ZAR, KES, MUR. Other currencies are unavailable at checkout., Refunds, reversals and chargebacks are handled in the Peach dashboard. Verified notifications add notes only., the webhook URL and the link View module log.

API credentials

The access token and the entity ID of the Card API are shown in the Peach Payments dashboard (test credentials: in the sandbox dashboard).

Test entity ID: the entity ID (3-D Secure channel) of your sandbox account.

Test access token: the bearer access token of your sandbox account.

Test webhook key: the 64-character hexadecimal key used to decrypt the Card webhooks of the sandbox.

Live entity ID: the entity ID (3-D Secure channel) of your live account.

Live access token: the bearer access token of your live account.

Live webhook key: the 64-character hexadecimal key used to decrypt the Card webhooks of the live account.

Magento stores the access tokens and webhook keys encrypted and shows only a mask (******) after saving. Leave the mask or an empty field to keep the saved value, type a new value to change it. Clearing the field does not delete a secret. To delete one, set the switch below it (Clear Test access token, Clear Test webhook key, Clear Live access token, Clear Live webhook key) to Yes and click Save Config. The switch is not stored and is back at No after saving.

Returns and webhooks always use the credentials of the mode the payment was started in, and of the store view where the order was placed. Keep the credentials of the old mode until its payments are finished.

Webhook

Webhooks confirm payments even when the customer closes the browser before returning to the store. The Setup information row shows the webhook URL, built for the default store view. It looks like https://your-store/wcppeachpay/webhook/index/. Copy the URL exactly as the settings show it. Ask Peach Payments ([email protected]) to enable Card webhooks for your account with this URL, then enter the decryption key you receive in the webhook key field of the same mode.

Peach Payments encrypts every webhook (AES-256-GCM). A webhook that cannot be decrypted with a saved key is rejected, so only Peach Payments can change your orders. The same URL serves all store views, and orders of any store view are found. The key that decrypts the webhook must be the key of the mode of the payment and of the store view of the order, so enter it in the Default Config unless a website or store view uses its own Peach Payments account. The module uses payment notifications:

Other notifications, for example the test notification sent when the webhook is activated, are answered with ignored. Without the webhook key, an order is confirmed only when the customer comes back to the store after paying, and a payment that Peach Payments reports as waiting for confirmation is not confirmed at all.

Payment form

Card brands: the brands shown in the Peach Payments form: VISA, MASTER, AMEX, DINERS. Select only brands enabled for your entity ID. Default: VISA and MASTER. If no brand is selected, the save shows Peach Payments: empty brands selection uses VISA and MASTER. and those two are saved.

Advanced

Debug logging: writes API requests and payment results to var/log/peach_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always logged, also when this setting is off. Access tokens, webhook keys, e-mail addresses and long card-like numbers are hidden in the log. Default: No.

View module log: this link in the Setup information row opens the latest entries of the log, with a Clear module log button.

Delete own data on uninstall: when Yes, uninstalling the module with its data removes the module settings of all scopes and the log (see Uninstall). The license key is always removed. Orders, invoices and the Peach Payments history are always kept. Default: No.

Native restrictions

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

Payment from specific countries: offer the method only for billing addresses in these countries.

Minimum order total: offer the method only from this order total, in the base currency of your store. Leave it empty for no minimum.

Maximum order total: offer the method only up to this order total, in the base currency. Leave it empty for no maximum.

Sort order: the position among the payment methods at checkout. Default: 90.

Checkout

At the payment step the customer chooses the payment method (by default Credit / Debit Card (Peach Payments)), sees the description and clicks Place Order. Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module prepares a Peach Payments checkout for the order total in the order currency, with two decimals, and sends Peach Payments the customer's name, e-mail, phone and addresses where they fit the formats of the API.

The customer then sees the page Complete your Peach Payments payment of your store with the Peach Payments card form and the selected card brands, in the language of the store view when Peach Payments supports it. In test mode the page shows Test mode: no real payment will be made. The card details are entered in the Peach Payments form, and the form script is loaded with a Subresource Integrity hash. Reloading the page reuses the same checkout for up to 25 minutes; after that the page answers Payment form unavailable.

After paying, the customer returns to your store. The order is marked paid only after Peach Payments confirms it: the module reads the result of this checkout from the Peach Payments API, in the mode the checkout was created in, and checks that the payment belongs to this order and that the amount and currency match. The webhook does the same independently, so whichever arrives first invoices the order and the other one changes nothing. The return and the webhook are handled even when Enable is No or the license is not active.

After a successful payment Magento creates the invoice with the Peach Payments payment ID as the transaction ID, the order moves to Processing (Complete when nothing is left to ship) and the order e-mail is sent. The customer sees the standard order success page. The same page is shown when Peach Payments reports the payment as waiting for confirmation; the webhook then finishes the order. A customer who comes back in another browser lands on the home page.

If the payment is declined, or the customer clicks Cancel and return to cart without paying, the order is cancelled, the cart is restored and the customer is back in the cart with Your payment is not confirmed. Please contact the store if you were charged. The customer can pay again or choose another payment method. The same message appears when the result cannot be confirmed yet (Peach Payments did not answer, the customer has not finished the form, the status was already read twice in the last minute, the order is being processed by the webhook, or the amount does not match). In these cases the order stays as it is and the cart is not restored, so the webhook can still finish the order. A return link that does not match the payment attempt answers Invalid payment return.

If the payment form cannot be prepared, the customer is sent to the cart with an error, and the cart is not restored. Unable to prepare the payment. Please contact the store before trying again. means that Peach Payments rejected the request or did not answer. If it rejected the request (wrong credentials or parameters), the order is cancelled; otherwise the order stays in Pending Payment. Other messages are The payment form could not be verified. (the answer had no valid integrity hash), Peach Payments is unavailable. (the module is disabled, the credentials of the current mode are missing, or the currency is not supported), A payment is already awaiting verification. (an earlier attempt of the same cart has an open result), This order cannot be paid again., Payment is busy. Please retry. and Unable to open the payment form. An order left in Pending Payment is cancelled by Magento as described below. 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). The module does not stop such a cancellation and does not cancel anything at Peach Payments. If Peach Payments later reports a payment for a cancelled order, the order is not invoiced and not reopened: it stays Canceled and a note asks you to review the payment in the Peach Payments dashboard.

The module works with the standard Magento checkout. It has no card form on the checkout step itself, no saved cards, no subscriptions, no pre-authorisation and capture, and no EFT, BNPL, QR or other non-card methods. It 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, but Peach Payments has not confirmed the payment yet. There is no invoice. When Peach Payments reports a payment that waits for a confirmation, a note shows the result code and payment ID, and the webhook later finishes the order.

Processing: the payment was confirmed and the amount and currency match the order. The invoice is created with the Peach Payments payment ID as the transaction ID, and a note shows how the payment was confirmed (return or webhook), the payment type, the result code and the payment ID. If Peach Payments flagged the payment for manual review, the order is still invoiced and the note says Successful payment flagged for manual review. Check it in the Peach Payments dashboard before shipping.

On Hold: the paid amount or currency differs from the order. No invoice is created. The note says Received amount/currency differs from native order totals. No paid invoice created. Review externally. The received amount and currency are in the Peach Payments history. Check the payment in the Peach Payments dashboard, then fulfil the order or refund the payment there.

Canceled: the payment was declined, the customer cancelled the checkout, Peach Payments rejected the checkout before card entry, or the order was cancelled in Magento.

A paid order is never changed by a later webhook or return, and repeated webhooks and returns, even at the same moment, never invoice an order twice. If a second payment for the same cart succeeds, a note says Duplicate charge; review and refund in the Peach dashboard. A payment that arrives for a cancelled or closed order gets the note Late charge on a cancelled/closed order. Review in the Peach dashboard; order was not reopened. The notes are order comments that the customer does not see.

Peach Payments information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Peach payment ID. The Information tab also has a Peach Payments history section with one row for every attempt: Reference, Mode, Status, Amount, Currency, Received amount, Received currency, Checkout ID, Payment ID and Result. Both are shown also when the module is disabled or the license is not active. The customer sees only the payment method title.

Refunds

Online refunds from Magento are not available. Refund the payment in the Peach Payments dashboard. To record it in Magento, create a credit memo with Refund Offline, which does not send money back. With the webhook set up, refunds, reversals and chargebacks made in Peach Payments add a note to the order: Dashboard refund/reversal/chargeback reported; reconcile externally. No Magento refund or order transition performed. No credit memo is created and the order status is not changed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Peach Payments Pay Gateway is the first row of the VibeFox Peach Payments Pay 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-peach 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, Peach Payments is not shown to customers at checkout. If a payment is started anyway, the customer is sent to the cart and sees This payment method is not available. Please choose another one. The order stays in Pending Payment until Magento cancels it. 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 by the customer return and the webhook.

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

Peach Payments does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has an entity ID and access token: the test fields in test mode, the live fields in live mode. Check that the order currency is ZAR, KES or MUR. Check Payment from applicable countries and Payment from specific countries against the customer's billing address, and Minimum order total and Maximum order total. A value of 0.00 in Maximum order total hides the method for every order; leave the field empty for no limit.

The payment went through, but the order stays Pending Payment: the customer did not come back to the store and the webhook did not arrive. Check that Peach Payments enabled Card webhooks for exactly the URL shown in the settings, that the webhook key of the mode the payment was made in is entered, and that no firewall or password protection blocks the URL. Turn on Debug logging and open View module log. If Magento has already cancelled the order, see the note about late charges under Orders and refunds.

The webhook answers authentication failed (HTTP 401): the webhook could not be decrypted with a saved key, or the key that decrypted it is not the key of the mode and store view of the payment. Enter the key Peach Payments sent for this webhook URL.

The webhook answers not configured (HTTP 500): no valid webhook key is saved. Enter the 64-character key. Peach Payments sends the webhook again later.

The webhook answers retry (HTTP 503): the order was being processed by the customer's return at the same moment, or an error occurred while the order was being updated. Nothing was changed, and Peach Payments sends the webhook again. The log shows the reason.

The webhook answers malformed (HTTP 400): the request had no encrypted body or no X-Initialization-Vector / X-Authentication-Tag headers, for example because a proxy changed it. Nothing was changed.

The webhook answers ignored: the notification is authentic but does not belong to a checkout of this store (another store on the same entity ID, or a type of notification the module does not use). Nothing was changed.

The webhook URL shows a Page not found page in the browser: this is normal. The URL accepts only POST requests from Peach Payments.

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

The customer sees Unable to prepare the payment: the access token or entity ID of the current mode may be wrong, or Peach Payments did not answer. Check the credentials and the mode, and read the log for the Peach Payments code.

The customer is back in the cart with Your payment is not confirmed: open the order and read the notes and the Peach Payments history. If the order is still in Pending Payment, the result was not known yet, and the webhook can still finish the order.

The order is On Hold or a note asks for a review: read the note on the order, check the payment in the Peach Payments dashboard, then fulfil the order or refund the payment there.

Saving shows that an invalid webhook key was saved: the value is not the key from Peach Payments. Webhooks of that mode cannot be decrypted until it is corrected.

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

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

The license key and license status are always removed. If Delete own data on uninstall is Yes, the module settings of all scopes and the log are removed too. If it is No, the settings and the log are kept for a re-install. The tables with the Peach Payments checkout attempts and processed notifications are always kept. Existing orders keep their invoices, payment notes and transaction IDs.

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