VibeFox Peach Payments for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: the store currency must be ZAR, KES or MUR. In other currencies the payment method is hidden, and the settings page says so.

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 site 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_peach_pay folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Peach Payments > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. 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).

6. Turn on Enable/Disable and save. Keep Test mode on and make a payment with a Peach Payments sandbox test card. Then untick Test mode, enter the live credentials and the live webhook key, and save.

Settings of version 1.0 are moved to the new fields automatically after the update.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Peach Payments. Above the fields the page shows notices: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; a notice when the Entity ID or Access Token of the current mode is missing (until then the payment method is not shown at checkout); a notice when the webhook decryption key of the current mode is missing (then payments are confirmed only when the customer returns to the shop); and a notice when the store currency is not supported. In the list of payment methods, Peach Payments is marked as needing setup until the current mode has an Entity ID and an Access Token. When you save, spaces are removed from the credentials, and a webhook key that is not a 64-character hexadecimal value is reported with an error.

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. Default: Credit / Debit Card (Peach Payments).

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

Webhook

Webhooks confirm payments even when the customer closes the browser before returning to the shop. The section shows the webhook URL of your store. It looks like https://your-site/wp-json/peach-pay/v1/webhook. 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 plugin uses payment notifications:

Other notifications, for example the test notification sent when the webhook is activated, are answered with OK and ignored. Without the webhook key, an order is confirmed only when the customer comes back to the store 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.

Advanced

Logging: Log API requests and payment results writes debug information to WooCommerce > Status > Logs, source wcp_peach_pay. Errors and warnings are always logged. Logs contain no card data, keys or customer data. Default: off.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. Peach Payments data stored on orders is kept. Default: off.

Checkout

The customer chooses the payment method (by default Credit / Debit Card (Peach Payments)) and clicks Continue to payment. The customer is taken to the Pay for order page of your store. There the plugin prepares a Peach Payments checkout for the order total in the order currency and shows the Peach Payments card form with the selected card brands, in the language of the site 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.

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

If the payment is not completed, the customer comes back to the Pay for order page 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. If the result cannot be confirmed yet (for example, Peach Payments did not answer, or the webhook is processing the same order 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, the customer is instead asked to contact you with the order number.

If the payment form cannot be prepared, the customer sees a short message and a Try again button: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (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 order gets a note with the Peach Payments code and description.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no card form on the checkout page itself, no saved cards, no subscriptions, no pre-authorisation and capture, and no EFT, BNPL, QR or other non-card methods.

Orders

Order statuses

Pending payment: the customer has not paid yet, or the payment was not completed. The customer can pay the same order again.

Processing: the payment was confirmed and the amount and currency match the order. The order note shows the Peach Payments result code, description and payment ID; the payment ID is the transaction ID of the order. If Peach Payments flagged the payment for manual review, the note asks you to check it in the Peach Payments dashboard before shipping.

On hold: the payment is waiting for a confirmation from Peach Payments (the webhook completes it later or marks it failed); the paid amount or currency differs from the order (note amount/currency mismatch — manual review required); or the payment arrived after the order had been cancelled. The order note explains what to check.

Failed: Peach Payments declined the payment of a pending order, or declined the payment the on-hold order was waiting for. A declined attempt never changes an order that is paid, on hold for another reason or cancelled. The customer can pay again.

If a second payment of 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.

Refunds

Refunds from the WooCommerce order screen are not available. Refund the payment in the Peach Payments dashboard and record a manual refund in WooCommerce. With the webhook set up, refunds, reversals and chargebacks made in Peach Payments are added to the order as notes with the amount and ID; the order status is not changed.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Peach Payments. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed by the customer return and the webhook.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store currency is ZAR, KES or MUR. The notices at the top of the settings name the problem. Developers can change the list of currencies with the filter peach_p_supported_currencies; add only currencies your Peach Payments account processes.

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 Decryption Key of the mode the payment was made in is entered, and that no maintenance mode, firewall or password protection blocks the URL. Look at WooCommerce > Status > Logs, source wcp_peach_pay, 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 Order busy, retry later: the order was being updated by the customer return at the same moment. Nothing was changed, and Peach Payments sends the webhook again.

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 store (another shop on the same Entity ID, a deleted order), or it came from the other mode than the payment. Nothing was changed.

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 order note for the Peach Payments code.

The order is On hold after payment: read the order note. The paid amount or currency differed from the order, the payment arrived after the order had been cancelled, or Peach Payments still waits for the confirmation of the payment. 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The plugin settings and its logs (log files and database log entries of the source wcp_peach_pay) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes, transaction IDs and Peach Payments checkout data.

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