1.1
Buy your plan
Purchase a FinPay plan on this shop. After payment, open My Account to access downloads and licenses.
- You need an active subscription before the ZIP appears.
Guide
Setup, connect, and go live.
Pick your track. Follow one screen at a time — Payment Hub, WP Store, or Custom platform — with comics that match real FinPay screens.
1.2
Download the FinPay ZIP
From My Account → Downloads (or Licenses), download the FinPay plugin package for your release.
1.3
Open Upload Plugin
On the WordPress site that will be your Payment Hub, go to Plugins → Add New → Upload Plugin.
1.4
Install the ZIP
Choose the FinPay ZIP file and click Install Now. Wait until WordPress finishes unpacking.
1.5
Activate FinPay
Activate the plugin. WooCommerce should already be active on the hub site.
- Hub = Payment role. Do not activate the same seat as a store on this site.
2.1
Open FinPay Setup
On first install, open FinPay → Setup. Licensing lives on the Welcome → License wizard step. After the site is locked, use FinPay → License for status, refresh, or deactivate.
2.2
Choose Payment hub
Select Payment hub. This site will own PayPal, the store registry, bridged checkout, and outbound status notify.
2.3
Sign in with shop credentials
Enter the email and password for your account on this selling shop (LicensePress). That activates the root hub license and locks site_mode to payment.
2.4
Activation success
When activation succeeds, setup_completed and setup_locked are set. You can mint stores under FinPay → Stores and configure PayPal.
2.5
Hub vs store ownership
The hub owns PayPal credentials, the masked catalog, fee rules, and signed status notify. Stores keep the cart, catalog source of truth, and customer emails.
3.1
Open FinPay → Stores
Open FinPay → Stores on the hub. This is the registry of WooCommerce and custom storefronts (option fpmp_stores).
3.2
Check seat quota
Your LicensePress plan limits how many store slots you can mint (for example 7 / 10).
3.3
Add store (mint slot)
Use FinPay → Stores → Add store. That claims a LicensePress store slot and creates HMAC credentials. Do not invent store_id or secrets by editing the database.
- Hand-edited registry rows fail closed with STORE_KEY_NOT_MINTED / STORE_SLOT_INVALID.
3.4
Copy the seat token
Open the store credentials modal and copy the seat token for the WP Store License form. Treat it like a password.
- Seat token activates the Store role on the other WordPress site via LicensePress.
3.5
Copy hub API credentials
Copy Payment site URL, Store ID (site_id), API key, and API secret. WP Stores and custom apps use these for signed REST.
3.6
Label Woo vs Custom
Set platform to wordpress for Woo stores, or custom / laravel / nodejs / etc. for non-WP. Status delivery is HMAC REST for WordPress, signed webhook for other platforms.
4.1
Credential card
Each store has a credential card on the hub: IDs, secrets, and connection state.
4.2
Rotate keys
Rotate API secrets when staff leave or a key may be exposed. Update the store or custom app immediately after.
4.3
Pause or disable
Pause a store to stop new sessions without deleting the registry row.
4.4
Disconnect / release seat
Disconnect releases the seat back to your plan quota when a storefront is retired.
4.5
When to re-mint
Re-mint a seat token if the store site was wiped or the license activation was removed.
5.1
Gateway settings location
Configure PayPal on the hub — not on each store. Stores bridge checkout to this destination.
5.2
Sandbox vs Live
Start in Sandbox. Switch to Live only after a successful test capture and status return.
5.3
Client credentials
Enter Client ID, secret, and merchant identifiers for the selected environment.
5.4
Webhooks & Orders v2
Confirm webhook ID / Orders v2 readiness so captures and status events reach the hub reliably.
5.5
Hosted checkout UI
Hub checkout can present hosted fields or buttons. Stores only start the session.
5.6
Gateway smoke checklist
Sandbox login works, a test order captures, and the origin store receives paid status.
6.1
Why a hub catalog
The hub keeps a processor-facing catalog so PayPal receipts stay clean while stores keep real titles.
6.2
Synced SKUs appear
After a store pushes products, SKUs show on the hub catalog for checkout masking.
6.3
Placeholders
Unsynced line items can fall back to global placeholders so checkout still works.
6.4
Prices stay real
Masking changes presentation — amounts on line items remain authoritative.
6.5
Catalog health
Periodically review missing masks and stale syncs before a big campaign.
7.1
What PayPal sees
Masked title, description, and image are what the processor and receipts show — not your raw storefront name.
7.2
Mask title
Set a clean processor-facing title per SKU on the hub (or via store sync fields).
7.3
Mask description
Keep descriptions short and consistent so PayPal pages stay tidy.
7.4
Mask image
Optional mask image for checkout presentation when you do not want the storefront asset exposed.
7.5
Before / after
Noisy storefront names become structured titles on the hub receipt path.
7.6
Best practices
Use a naming scheme, avoid PII in masks, and re-sync after major catalog renames.
8.1
Fee rules per store
Define processing-fee rules on the hub per connected store (enabled, type, value, label, display_mode).
8.2
Estimate → handling
Stores may send totals.processing_fee as an estimate on orders/create. Set totals.total without that fee. The hub folds tax, shipping, other fees, and the processing fee into one handling line — do not mirror the hub fee back onto the store after pay.
8.3
Estimates via fee/info
Stores call POST /fee/info (action fee_info) to cache the resolved fee config before showing cart estimates.
8.4
Add-on entitlements
Some handling / fee behaviors require matching LicensePress plan entitlements.
8.5
Test a fee scenario
Run a sandbox order and confirm the store estimate, hub charged total, and handling line match expectations.
9.1
Redirect mode
Customer leaves the storefront, pays on the hub, then returns via your return URL.
9.2
Iframe mode
Embed hub checkout in an iframe when you want an in-context experience.
9.3
CSP allowlist
Allowlist store origins on the hub so iframe embeds are permitted securely.
9.4
postMessage is UI-only
Iframe completion may emit fpmp_payment_success or sp_paid for UI. Only signed hub status (HMAC REST or webhook) marks an order paid.
- Never trust the browser for payment finalization.
9.5
Pick mode per store
Choose redirect or iframe per store based on UX and CSP constraints.
10.1
Bridged hub order
The hub creates an attributed bridged order tied to the origin store.
10.2
Immediate notify
After PayPal capture, the hub notifies the origin store right away.
10.3
Signed payload
Status is HMAC-signed (Woo REST) or webhook-signed (custom) so stores can verify authenticity.
10.4
Declines & failures
Decline messages travel on the status payload so the origin store can react.
10.5
Emails stay on the store
Customer confirmation email is owned by the originating storefront — not duplicated from the hub.
10.6
Happy-path walkthrough
Store session → hub PayPal capture → signed paid status → origin order completed.
11.1
Why notify can lag
Network blips or a down store can delay the first status delivery.
11.2
Backoff retries
The hub retries with backoff so temporary outages self-heal.
11.3
Admin Order Sync
Use Order Sync on the hub to manually recover a stuck paid notification.
11.4
Idempotent paid
Stores must treat duplicate paid notices as safe — never double-fulfill.
11.5
When to escalate
If retries and Order Sync fail, capture logs (HMAC, PayPal, bridge) before contacting support.
12.1
Open logs
Open WooCommerce → Status → Logs and filter source fpmp. FinPay writes license, PayPal, bridge, and HMAC events there.
12.2
Filter by channel
Filter for license, PayPal, bridge, or HMAC failures to narrow the incident.
12.3
Common error shapes
Watch for signature mismatch, replay window, rate limit, and non-2xx webhook responses.
12.4
Clock & HTTPS
NTP clock skew and missing HTTPS break HMAC and secure cookies — fix hosting first.
12.5
What to send support
Include timestamps, store ID, hub order id, and the filtered log slice — never paste live secrets.
13.1
HPOS notes
FinPay targets modern WooCommerce high-performance order storage on hub and stores.
13.2
Rate limits & replay
Signed requests use a replay window and rate limits — do not retry blindly without new request ids.
13.3
Multi-store mesh
Many stores share one checkout destination. Attribution keeps money and status tied to the origin.
13.4
Plan entitlements
Seats, PayPal, custom stores, and addons are gated by LicensePress entitlements on the shop.
13.5
In-product API guide
Custom integrators: open FinPay → API Guide on the hub, use shortcode [fpmp_api_guide], or the versioned docs synced to My Account Documents.
13.6
Hub go-live checklist
Live PayPal, at least one connected store, catalog synced, test paid status, logs clean.
13.7
Next track
Continue with the WP Store guide or Custom platform guide from the tabs above.
Track complete
Continue with another track, or open Pricing / My Account when you are ready to buy.
1.1
Use the store site
Install FinPay on the WooCommerce storefront — not on the Payment Hub site.
- One site = one role. Hub and store are different WordPress installs.
1.2
Upload the plugin
Plugins → Add New → Upload Plugin, then choose the FinPay ZIP.
1.3
Install
Click Install Now and wait for WordPress to finish.
1.4
Activate
Activate FinPay. WooCommerce must already be active on this store.
1.5
Confirm site role
You are about to license this site as a Store with a seat token from the hub.
2.1
Open Setup → Store
In FinPay → Setup (License step), choose Store. The form asks for seat token plus hub connection fields together.
2.2
Seat then hub keys
Paste the seat token from the hub credentials modal, then Payment URL, Store ID, API key, and secret. FinPay validates the seat with LicensePress first, then connects to the hub.
2.3
Seat accepted
If the seat is valid, the Store role locks (site_mode = store). If hub connect fails after a good seat, you still land locked as Store with a reconnect warning — fix credentials and Test & Connect.
2.4
Wrong-token failures
Expired, already-used, or wrong-plan seat tokens fail closed. Re-open FinPay → Stores credentials on the hub and copy a fresh seat token if the store was rebuilt.
3.1
Payment hub URL
Enter the Payment Hub site URL exactly as shown on the hub credential card.
3.2
Store ID
Paste the Store ID from the hub registry for this storefront.
3.3
API key + secret
Paste key and secret. Keep them server-side and out of theme git repos.
3.4
Health check
Use Test & Connect. Health (POST /health) verifies reachability and signing — it does not require a minted license slot. Connect records remote_url and marks the registry connected.
3.5
Connect success
When connect succeeds, the hub allowlists your host for iframe CSP / redirects. The store can create payment sessions and receive signed /orders/status.
3.6
After key rotate
If the hub rotates secrets, update this screen immediately or sessions will fail.
4.1
Why sync
Push enabled products so the hub upserts locked managed products. PayPal line names come from mask fields (payload name), while prices stay the store prices.
4.2
Push catalog
Enable sync on products and save, or use bulk sync. The store POSTs /products/sync (action product_sync) with HMAC. Variable products flatten to simple SKUs on the hub.
4.3
Confirm on hub
Verify managed products appear on the hub (locked for hub-side edits) with the correct _fpmp_store_id attribution.
4.4
Re-sync changes
Re-sync after price or mask changes you want reflected on the hub pay page.
4.5
Unsynced SKUs
Unsynced lines can use a global placeholder (is_global_placeholder) so checkout still works — sync important SKUs before launch.
5.1
Product masks
Set mask title, description, and image on the store product (synced as name / description / image_url). Never send the raw storefront title as the Payment name.
5.2
Pay-iframe Style tab
Separately, FinPay → Style on the store pushes card_style via /style/sync for the pay iframe chrome and Card Fields shells — not WordPress theme header/footer.
5.3
Processor preview
PayPal and the pay page resolve product_key → masked hub name. Your storefront can keep internal titles.
5.4
Privacy
Do not put private supplier codes in masks if receipts are customer-visible.
6.1
Estimates
The store caches fee config from /fee/info and may show a processing-fee estimate so the shopper sees the charged total.
6.2
Checkout totals
On orders/create, send totals.processing_fee as the estimate and totals.total without that fee. The hub charges via the handling line — do not add a second store fee after pay.
6.3
Mismatch troubleshooting
If estimates drift, refresh fee/info, re-check hub fee rules and currency, then retest a sandbox order.
7.1
Gateway starts a session
At pay time the store creates a bridged session on the hub (`orders/create`).
7.2
Redirect flow
Customer pays on the hub and returns to the store thank-you / order path.
7.3
Iframe flow
If enabled, embed hub checkout — ensure CSP allowlisting on the hub.
7.4
Return URLs
Configure success/cancel return URLs so shoppers land correctly after PayPal.
7.5
Pay on the hub only
Money clears on the hub. The store must not invent offline PayPal credentials.
8.1
Origin order
The Woo order lives on the store. The hub holds the bridged payment attribution.
8.2
Paid only on HMAC status
Mark paid only after verifying the signed status from the hub — never from browser events.
8.3
Declines
Handle decline payloads so the customer can retry without corrupting order state.
8.4
Customer emails
Send order emails from the store after paid status is applied.
8.5
Test order checklist
Sandbox: place order → pay on hub → store shows processing/completed → email sent.
9.1
Late status
If the store never gets paid, check hub retries and network reachability first.
9.2
Store admin checks
Confirm credentials, HTTPS, and that the order is waiting — not already completed.
9.3
Hub recovery
Use hub Order Sync to resend status for a known paid bridge.
9.4
No double fulfill
Idempotent handlers prevent shipping twice when status is replayed.
10.1
Store log lines
Open WooCommerce → Status → Logs (source fpmp) on the store for connect, sync, and status apply lines.
10.2
Clock & HTTPS
Skewed clocks break signatures. Always serve the store over HTTPS in production.
10.3
Credential mistakes
Trailing spaces, wrong hub URL, or old secrets after rotate are the top failures.
10.4
Support checklist
Collect store ID, approximate time, order id, and redacted logs.
11.1
HPOS
Keep WooCommerce and FinPay updated for high-performance order storage compatibility.
11.2
Many stores, one hub
Each storefront uses its own seat and credentials against the shared hub.
11.3
Paused from hub
If the hub pauses this store, new sessions stop until re-enabled.
11.4
Store go-live checklist
Seat active, hub connected, catalog synced, sandbox paid, emails OK, then flip live gateway on the hub.
11.5
Custom platforms
Non-WP storefronts use the Custom platform track instead of this Store license flow.
Track complete
Continue with another track, or open Pricing / My Account when you are ready to buy.
1.1
Hub + custom_stores
The Payment hub must be licensed (FinPay → License) and your plan must allow custom stores. PayPal on the hub must be configured (sandbox or live).
1.2
Mint custom store
On the hub: FinPay → Stores → Add store. Set platform to custom (or laravel, nodejs, shopify, …). That mints the LicensePress slot and HMAC pair — there is no public self-registration API.
1.3
Store secrets server-side
Save payment_base_url, store_id, api_key, and api_secret only on your backend. Never ship them to browsers or mobile apps.
- HMAC credentials alone from a hand-edited registry do not unlock connect / sync / create — minting is required.
1.4
Versioned API docs
Use FinPay → API Guide → Custom on the hub, shortcode [fpmp_api_guide], or the versioned docs synced to My Account Documents.
2.1
Base URL
All custom→hub calls hit the Payment hub: {payment_base_url}/wp-json/fpmp/v1/…. This is not the LicensePress shop kit base_url (that is only for product license activation inside FinPay).
2.2
site_id + secret
Every signed request sets site_id to your Store ID and proves possession of api_secret. Also send X-FPMP-* headers mirroring envelope fields.
2.3
HMAC fields
Canonical string: timestamp \n request_id \n site_id \n action \n compact JSON payload. Signature = HMAC-SHA256 hex with api_secret. Empty payload signs as [] (new clients); hub also accepts {}.
2.4
Replay window
Timestamps must fall within security.replay_window (default 300s). Duplicate request_id is rejected (health exempt). Always mint a fresh request_id.
2.5
Rate limits
Respect per-IP rate limits — backoff instead of hammering create_payment.
3.1
Health action
POST /health with action health first. It verifies reachability and signing and does not require a minted license slot.
3.2
Connect
POST /connect with site_url (required) and webhook_url (recommended). Connect requires the store to be licensed/minted on the hub — otherwise STORE_KEY_NOT_MINTED / STORE_SLOT_INVALID / LPRESSINT_NOT_LICENSED.
3.3
Verify response
Persist connection state only after status connected. site_url becomes registry remote_url (CSP frame-ancestors / origin checks).
4.1
product_sync
POST /products/sync with action product_sync. Default payload is one flat product (required: product_key, name). Optional batch via payload.products[].
4.2
Mask over API
Send masked display as name, description, and image_url — never your real storefront title as name. Prices are real string decimals.
4.3
Placeholders
For unsynced lines, sync a global placeholder once with is_global_placeholder true (hub price $0) and put real prices on create_payment.
4.4
Prices on lines
On create_payment, line names are ignored for PayPal — hub resolves product_key → masked name. Item qty/prices and totals stay authoritative.
5.1
fee_info
POST /fee/info (action fee_info) returns enabled, type, value, label, display_mode. Cache locally for cart estimates.
5.2
Fees on create
Send totals.processing_fee as the estimate; totals.total must exclude that fee. Hub folds it into handling with tax/shipping/other fees — do not put processing fee in totals.fees[].
5.3
Addon gates
Handling addons require matching LicensePress entitlements on the hub license.
6.1
Session fields
POST /orders/create with action create_payment. Required: token, store_order_id, non-empty items[] (each needs product_key + qty/prices). Also send currency, delivery, return/cancel URLs, customer/addresses, totals.
6.2
Items & totals
Keep product_key aligned with synced catalog. Money as string decimals. Same token + same cart lines reuses the hub session.
6.3
Return URLs
Provide return_url, cancel_url, and store_origin hosts that match your connected site_url host.
6.4
PAYMENT_SESSION_CREATED
On success, data includes order_id, checkout_url, transaction_id, and charged total/processing_fee. Send the customer to checkout_url.
6.5
Redirect vs embed
Open checkout_url as redirect or iframe (append fpmp_compact=1 for nested embeds). Never invent a local PayPal flow — money clears on the hub.
7.1
Embed checkout
Create with delivery iframe, then embed checkout_url. Push pay-iframe styles with style_sync (card_style) — parent CSS only wraps the iframe, not Card Fields inputs.
7.2
Allowlist origin
Connect records your site_url host for CSP frame-ancestors. Keep store_origin aligned or embeds fail.
7.3
postMessage ≠ paid
Listen for fpmp_payment_success or sp_paid (verify event.origin). Update UI only — finalize from the signed webhook.
7.4
Mobile notes
Test iframe and redirect on mobile browsers before launch. Prefer warm iframe remounts so Card Fields do not reload unnecessarily.
8.1
Verify signature
Payment POSTs a signed envelope to your webhook_url (actions order_status / payment_result). Verify HMAC with the same canonical rules before trusting status.
8.2
Status payloads
Payload includes store_order_id (string), token, status, optional transaction_id, remote_order_id, and decline messages. Source of truth for paid is the webhook — not postMessage.
8.3
Return 2xx quickly
Acknowledge with 2xx quickly, then process asynchronously if needed — non-2xx triggers hub backoff retries (fpmp_notify_store).
8.4
Idempotent mark-paid
Duplicate paid notices must not double-fulfill. Treat PAYMENT_ALREADY_PROCESSED-style outcomes as success.
8.5
Map to your orders
Key off the store_order_id you sent at create_payment (string UUID or numeric id).
9.1
Hub backoff
Non-2xx responses cause hub backoff retries.
9.2
Order Sync recovery
Hub admins can resend status via Order Sync when your endpoint was down.
9.3
Your dead-letter
Keep a replay-safe consumer for events you failed to apply locally.
10.1
Signature mismatches
Usually wrong secret, bad payload canonicalization, or clock skew.
10.2
Unsynced SKUs
Sync catalog before blaming checkout when masks look wrong.
10.3
Webhook timeouts
Optimize your endpoint latency; use async workers after 2xx.
10.4
Sandbox vs live
Confirm hub gateway mode matches the credentials your tests expect.
11.1
Entitlement gates
paypal, custom_stores, and addons must be present on the license resources.
11.2
Security checklist
HTTPS everywhere, secrets in a vault, verify signatures, rotate on leak.
11.3
Sandbox → live
Cut over hub PayPal to live after end-to-end paid webhook success in sandbox.
11.4
Full API guide
Use the in-product / release API document for field-level contracts — this Guide is the path, not the spec.
11.5
Custom go-live checklist
Connect OK, sync OK, create payment OK, webhook paid OK, idempotency OK, live credentials OK.
Track complete
Continue with another track, or open Pricing / My Account when you are ready to buy.