VibeFox Peach Payments for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later with the OpenSSL extension (used to decrypt webhooks). The module refuses to install without them.

Currency: the cart currency must be ZAR, KES or MUR. For carts in other currencies the payment method is hidden. The settings page warns you when the default currency of the shop is not one of them.

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 shop (see Configuration). Your shop must be reachable from the internet to receive webhooks.

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 Peach Payments Pay 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. Enter the test Entity ID and 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).

5. Turn on Enable/Disable and click Save. Keep Test mode on and make a payment with a Peach Payments sandbox test card. Then turn off Test mode, enter the live credentials and the live webhook key, and click Save.

On install the module creates two order statuses, Awaiting Peach Payments payment and Peach Payments payment on hold. PrestaShop offers a new payment module for the currencies, countries and customer groups active at that moment. Countries added later must be enabled for the module in Payment > Preferences, where you can also limit them.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows notices: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; an error when the Entity ID or Access Token of the current mode is missing (until then the payment method is not shown at checkout); a warning when the webhook decryption key of the current mode is missing (then payments are confirmed only when the customer returns to the shop); and an error when the default currency of the shop is not supported. When you save, spaces are removed from the credentials, and a webhook key that is not a 64-character hexadecimal value is reported with a warning.

Peach Payments

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

Title: the payment method name shown to the customer at checkout. It is also the payment method name stored in the order. Default: Credit / Debit Card (Peach Payments). Required.

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

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). The section links to both dashboards and to the Peach Payments developer documentation.

Test mode: sends new payments to the Peach Payments sandbox with the test credentials, and no real money is charged. Turn it off 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: on.

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 Decryption 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 Decryption Key: the 64-character hexadecimal key used to decrypt the Card webhooks of the live account.

Saved access tokens and webhook keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick an access token or webhook key and click Save to remove it. An empty field keeps the saved value.

Webhook

Webhooks confirm payments even when the customer closes the browser before returning to the shop. The Webhook URL field shows the webhook URL of your shop. With friendly URLs it looks like https://your-shop/module/wcp_peach_pay/webhook, possibly with a language code such as /en/. Copy the URL exactly as the settings show it. Ask Peach Payments (support@peachpayments.com) to enable Card webhooks for your account with this URL, then enter the decryption key you receive in the Webhook Decryption Key field of the same mode.

Peach Payments encrypts every webhook (AES-256-GCM). A webhook that cannot be decrypted with the test or live key is rejected, so only Peach Payments can change your orders. A webhook decrypted with the key of one mode is applied only to payments started in that mode. The module uses payment notifications:

Debit payment (DB): the result of a card payment of a cart. The order is created as paid, on hold or awaiting confirmation, or the attempt is marked declined (see Orders).

Refund (RF), reversal (RV), chargeback (CB): a refund or reversal made in the Peach Payments dashboard, or a reported chargeback. It is added to the order notes; the order status is not changed.

Other notifications, for example the test notification sent when the webhook is activated, are answered with ignored. Without the webhook key, an order is created only when the customer comes back to the shop after paying.

Payment form

Card brands: the brands shown in the Peach Payments form: Visa, Mastercard, American Express, Diners Club. Select only brands enabled for your Entity ID. Default: Visa and Mastercard. If no brand is selected, the save shows a warning and the form shows Visa and Mastercard.

Advanced

Logging: logs API requests and payment results to logs/peach_p_debug.log.php in the module folder. The file cannot be read from the web. Errors and warnings are always logged. Logs contain no card data, keys or customer data. 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 deletes the module settings and logs. The Peach Payments data of the orders (checkout attempts, payment IDs) and the order statuses are kept, because they belong to the orders. Default: off.

Checkout

The customer chooses the payment method (by default Credit / Debit Card (Peach Payments)) and confirms the order. In test mode the payment method shows Test mode: no real payment will be made. The module prepares a Peach Payments checkout for the cart total in the cart currency and shows the Peach Payments payment page of your shop with the Peach Payments card form and the selected card brands, in the language of the customer when Peach Payments supports it. In test mode the page shows Test mode: use a Peach Payments test card, 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. The link Choose another payment method leads back to the checkout. No order exists yet at this point. Reloading the page reuses the same checkout for up to 25 minutes, unless the cart changed.

After paying, the customer returns to your shop. The order is marked paid only after Peach Payments confirms it: the shop reads the result of this cart's checkout from the Peach Payments API, in the mode the checkout was created in, and checks that the payment belongs to this cart. The webhook does the same independently, so whichever arrives first creates the order and the other one changes nothing. The customer then sees the standard order confirmation page.

If the payment is not completed, the customer is back at checkout with a message and can try again: Payment failed: followed by the reason from Peach Payments and Please try again or use another card., or The payment was not completed. Please try again. The cart is kept. If the result cannot be confirmed yet (for example, Peach Payments did not answer, or the webhook is processing the same cart at that moment), the message is We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. When no webhook key is set for the mode of the payment, the customer is instead asked to contact you.

If the payment form cannot be prepared, the customer stays at checkout with a short message: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (missing or wrong credentials), a message that some billing details were not accepted by the payment provider, or The payment form could not be loaded. Please try again in a moment. The technical reason is written to the log.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module 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.

Orders

Order statuses

No order yet: the customer has not paid, the payment was declined or not completed, or Peach Payments has not confirmed it yet. Only the cart exists, and the customer can pay again.

Payment accepted: the payment was confirmed and the amount and currency match the cart. The payment is recorded with the Peach Payments payment ID as the transaction ID, and a note shows the Peach Payments result code, description and payment ID. If Peach Payments flagged the payment for manual review, the note asks you to check it in the Peach Payments dashboard before shipping.

Awaiting Peach Payments payment: Peach Payments reported a payment that waits for a confirmation. The webhook later moves the order to Payment accepted or marks it failed.

Peach Payments payment on hold: the paid amount or currency differs from the cart (note amount/currency mismatch — manual review required), or the payment arrived after the order had been cancelled. The note explains what to check. Check the payment in the Peach Payments dashboard, then process the order or refund the payment.

Payment error: Peach Payments declined the payment the awaiting order was waiting for. A declined attempt never changes an order that is paid, on hold or cancelled.

If a second payment for an already paid order succeeds, the order is not changed. A note says it is a duplicate payment and asks you to refund it in the Peach Payments dashboard. A payment that arrives for a refunded order is only noted on the order.

Peach Payments payment block

The order page shows a Peach Payments payment block with the payment ID, the checkout ID, the merchant transaction ID, the amount sent to Peach Payments, the result and result code, a Test mode badge for test payments and the Peach Payments notes of the order.

Refunds

Refunds from the PrestaShop order page are not available. Refund the payment in the Peach Payments dashboard and record it in PrestaShop (partial refund or credit slip) if needed. With the webhook set up, refunds, reversals and chargebacks made in Peach Payments are added to the order notes with the amount and ID; 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 block on Modules > Module Manager > VibeFox Peach Payments Pay 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-peach 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, Peach Payments 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 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 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

Peach Payments does not appear at checkout: check that the license is active, Enable/Disable is on, the Entity ID and Access Token of the current mode are entered (Test Entity ID and Test Access Token in test mode, Live Entity ID and Live Access Token in live mode) and the cart currency is ZAR, KES or MUR. The notices at the top of the settings name the problem. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: the customer did not come back to the shop and the webhook did not arrive. Check that Peach Payments enabled Card webhooks for exactly the URL shown in the settings, that the Webhook Decryption Key of the mode the payment was made in is entered, and that no firewall or password protection blocks the URL. Turn on Logging and look at the Log field for rejected webhooks.

Webhook answers Decryption failed: the webhook could not be decrypted with the test or live key. The key is wrong or belongs to another account or mode. Enter the key Peach Payments sent for this webhook URL.

Webhook answers Webhook key not configured: neither webhook key is set or valid. Enter the 64-character key. Peach Payments sends the webhook again later.

Webhook answers Busy, retry later: the cart was being processed by the customer return at the same moment, or the order could not be created (for example, the module is disabled). Nothing was changed, and Peach Payments sends the webhook again. The log shows the reason.

Webhook answers Missing or malformed data: 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.

Webhook answers ignored: the notification is authentic but does not belong to a checkout of this shop (another shop on the same Entity ID, a deleted cart), or it came from the other mode than the payment. Nothing was changed.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Peach Payments.

The customer sees The payment form is not available right now: the Access Token or Entity ID of the current mode is wrong. Check the credentials and the mode, and read the log for the Peach Payments code.

The order is Peach Payments payment on hold after payment: read the notes in the Peach Payments payment block. The paid amount or currency differed from the cart, or the payment arrived after the order had been cancelled. Check the payment in the Peach Payments dashboard, then process the order or refund the payment.

Saving shows that the webhook key must be the 64-character hexadecimal key: the value is not the key from Peach Payments. Webhooks cannot be decrypted until it is corrected.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Peach Payments Pay Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and logs are removed. If it is off, all settings are kept for a later re-install. The checkout attempts, payment IDs and the order statuses Awaiting Peach Payments payment and Peach Payments payment on hold are always kept. Existing orders keep their payment notes, transaction IDs and Peach Payments checkout data.

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