PrestaShop Integration Guide

This guide walks you through integrating the Frak Components into your PrestaShop store to enable referral acquisition, reward-aware sharing, and purchase tracking.

The Frak module auto-injects its components on the right pages — share button on product pages, banner at the top of the storefront, post-purchase card on the order confirmation and order detail pages — and forwards order status updates to Frak via a signed webhook (with retry queue + cron drainer). Everything can be toggled on/off and tuned from the Frak Integration configuration screen.

Prerequisites

Before you begin, ensure that:

You have a merchant account on the Frak business dashboard. Your main domain is registered automatically at sign-up — nothing else to enable on the Frak side.
You have admin access to your PrestaShop back office.
Your store runs on PrestaShop 8.1+ with PHP 8.1+.

Step 1: Install and activate the Frak module

Download the latest frakintegration-<version>.zip from the Frak Wallet releases. Pick the newest asset tagged prestashop-<version>.
Log in to your PrestaShop back office.
Go to Modules → Module Manager → Upload a module and drop the zip in.
Click Configure on the Frak Integration module to open its settings page (also reachable later from Modules → Frak in the back-office sidebar).

The module ships its vendor/ directory inside the zip — no merchant-side composer install required.

Step 2: Connect the merchant and webhook secret

The settings page's Purchase Tracking panel is where you connect the storefront to Frak. The webhook secret is owned by business.frak.id (single source of truth) — you generate it there and paste it into the module.

In the Frak business dashboard, open your merchant and go to Purchase Tracker → PrestaShop.
Generate (or copy) the Webhook Secret displayed there.
Back on the PrestaShop Frak Integration settings page, scroll to Purchase Tracking → Webhook Secret and paste the value.
Click Save Settings at the bottom of the form.

The Merchant row above the secret should now show a green ✓ Connected badge with your merchant name and UUID. If it still says ✗ Not resolved for this domain:

Confirm the storefront's domain (shown in the Site Information row) is registered in your dashboard. Main domain works automatically; subdomains need to be added under Allowed Domains.
Scroll to the Maintenance panel and click Refresh Merchant — it invalidates the resolver cache and re-queries Frak.

Step 3: Set the Brand fields

The Website Information panel feeds the brand metadata surfaced in the Frak modal:

Shop Name — defaults to PrestaShop's PS_SHOP_NAME. Used as the modal title.
Logo — paste a public Logo URL, or use Or upload a file to upload a JPG/PNG/GIF/SVG (≤ 2 MB). The preview pane on the right reflects the current value.

Click Save Settings.

Step 4: Pick which components render where

The Component Placements panel groups the Frak web components by surface. Each placement is a checkbox; checked = auto-render on that PrestaShop hook. All four placements are enabled by default, so on a fresh install the storefront already shows everything below — uncheck any you don't need.

Component	Placement id	PrestaShop hook	Default	Options
Share button	`share_product`	`displayProductAdditionalInfo`	enabled	Button style — `Primary`, `Secondary`, or `None`
Banner	`banner_top`	`displayTop`	enabled	Custom CSS class (letters / digits / spaces / dashes / underscores, ≤ 200 chars)
Post-purchase card	`post_purchase_confirmation`	`displayOrderConfirmation`	enabled	—
Post-purchase card	`post_purchase_detail`	`displayOrderDetail`	enabled	—

The post-purchase card is fired on both the post-checkout thank-you page (displayOrderConfirmation) and the customer-facing order detail (displayOrderDetail). The SDK is idempotent on the (customerId, orderId, token) triple, so customers landing on the order detail straight from the order email still get tracked.

Save the form to apply your choices.

Custom drop-ins via Smarty

If you need a Frak component on a surface the placement registry doesn't cover (a CMS page, a custom block in a .tpl file, …), use the bundled Smarty function plugins:

{frak_banner placement="hero" referral_title="Welcome back!"}
{frak_share_button text="Share & earn" use_reward=1 placement="sidebar"}
{frak_post_purchase variant="referrer" cta_text="Earn rewards"}

Snake-case attribute names are normalised to camelCase at the boundary so templates read naturally. The {frak_post_purchase} plugin emits the bare <frak-post-purchase> markup — order context (customerId / orderId / token) is only auto-injected by the order hooks, so pass the triple explicitly when calling it from a non-order endpoint.

Step 5: Wire the retry cron

Failed webhook deliveries are queued in a custom table and retried with exponential backoff (5 min → 24 h, 5 attempts). Two cron paths are supported and they share the same drainer (advisory-locked, safe to run in parallel):

Option A — `ps_cronjobs` module (recommended)

Install the official ps_cronjobs module from the Module Manager. The Frak module auto-registers its drainer with ps_cronjobs, and the Retry Cron row on the settings page flips to ✓ Auto-registered with ps_cronjobs. Nothing else to do — ps_cronjobs runs the drainer on its hourly tick.

Option B — server-level cron

The settings page's Retry Cron row exposes a token-guarded URL of the form:

https://your-shop.example/index.php?fc=module&module=frakintegration&controller=cron&token=<random>

Wire it into a 5-minute cron — for example, with crontab -e:

*/5 * * * * curl -fs 'https://your-shop.example/index.php?fc=module&module=frakintegration&controller=cron&token=<paste-from-settings>'

The token is generated on install and gates the front controller via hash_equals. To rotate, delete the FRAK_CRON_TOKEN configuration row and reinstall the module.

You can also drain the queue on demand: scroll to the Maintenance → Webhook queue panel and click Drain queue now.

Step 6: Monitor the webhook queue

The Maintenance → Webhook queue panel exposes the drainer's health:

Pending — queued deliveries waiting for the next attempt (with the next-attempt timestamp underneath).
Delivered — successful deliveries since the last queue reset.
Parked (failed) — deliveries that have exhausted their retry budget. A red Investigate logs badge appears as soon as this is non-zero.
Last error — the most recent error message captured by the drainer, with timestamp.

From this point on, every order whose status moves to Awaiting payment validation, Payment accepted, Delivered, or Awaiting payment, out-of-stock product triggers a confirmed webhook. Cancelled and Payment error map to cancelled; Refund maps to refunded. Any credit slip (full refund, partial refund, shipping-only refund, standard return) also fires a refunded webhook — partial refunds void attribution, mirroring the WooCommerce / Magento siblings. Preparation in progress and Shipping are skipped intentionally so they don't pollute the funnel.

Webhook bodies are HMAC-SHA256 signed (base64-encoded raw digest in the x-hmac-sha256 header) and POSTed to https://backend.frak.id/ext/merchant/{merchantId}/webhook/custom.

Troubleshooting

Merchant says "Not resolved for this domain" — Confirm the storefront domain is registered on business.frak.id. The main merchant domain works automatically; subdomains need to be added under Allowed Domains. Then click Refresh Merchant in the Maintenance panel.
Webhook deliveries failing with HTTP 401 / signature mismatch — Re-copy the secret from Purchase Tracker → PrestaShop on the dashboard, paste it back into Webhook Secret, and click Save Settings. The new secret applies to subsequent deliveries (and the queue drainer re-signs queued payloads with it).
Parked count keeps growing — Open Advanced Parameters → Logs and filter on FrakIntegration. The Last error field on the Webhook queue panel usually points straight at the cause (DNS, TLS, backend 5xx, …).
Components missing on the storefront — Confirm the corresponding placement is enabled in Component Placements and clear your PrestaShop cache (Advanced Parameters → Performance → Clear cache). Some themes strip the displayProductAdditionalInfo / displayTop hooks — check your theme's product.tpl / header template if the placement is enabled but nothing renders.
Logo doesn't load in the modal — Use Or upload a file instead of an external URL; uploaded files are served from /modules/frakintegration/uploads/ and bypass third-party caching/CORS issues.

Source Code

The Frak PrestaShop module is open source and lives inside the Frak wallet monorepo under plugins/prestashop. Open an issue or a PR if you want to contribute or report a bug.