Match the error string or symptom, apply the fix. When you email support, send merchant id, session id if you have one, and request_id from the JSON error body.
Copy this page as a setup prompt for your coding assistant.
API and auth
Symptom
Fix
Invalid API key format
Bearer token must be full plurel_… key
Invalid or revoked API key
Rotate on Developers (Rotate publishable/secret key); the previous key is revoked immediately
Complete the sandbox checklist on your dashboard before activating live
Finish all five Setup guide steps, then open Activate live from the account menu
Checkout uses wrong payment mode
Charges follow the API key, not the Sandbox or Live view
Secret API keys must not be used from browser clients
Publishable key + signing in frontend; secret key on server
Too many requests
Honor Retry-After; stop tight retry loops on 401
Headless REST requires onboarding
Use publishable + sign, or contact Plurel Pay to enable headless
Cart signing
Symptom
Fix
Invalid cart signature
Wrong credential: use PLUREL_SIGNING_SECRET (plurel_sign_…), not secret API key (plurel_sk_…) or webhook secret (whsec_…)
Invalid cart signature
Secret correct but still fails: use createCartSignature from @plurel/sdk/signing ≥ 0.1.7 (includes fees: [] in HMAC)
Invalid cart signature
PLUREL_SIGNING_SECRET must match dashboard plurel_sign_… value; redeploy after env change or rotation
Invalid cart signature
Read the details[] array on the API error response for a checklist
Cart signing failed (client)
Your /api/cart/sign returned non-200; check server logs
cart.total, cart.currency required
total in smallest currency unit (cents for USD, whole yen for JPY); items array non-empty
SDK and modal
Symptom
Fix
Plurel Pay is undefined
Load plurel.js before init; await script onload if needed
Blank iframe
CSP frame-src must allow plurelpay.com; test without blockers
onGroupFunded never ran
Normal if user closed tab; fulfill on webhook
Callbacks fire twice
Idempotent handlers; webhook is authoritative
Webhooks
Symptom
Fix
401 on your handler
whsec_ for dashboard URL; signing secret for webhook_url
No deliveries
HTTPS public URL; check delivery log for last error
Retries forever
Return 2xx; fix 4xx/5xx; check TLS expiry
No group.funded
Session not fully paid; endpoint not subscribed to event
Payouts & settlement
Symptom
Fix
Payout account not ready
Finish setup in Payments in the merchant portal
Expected payout in preferred currency
Settlement transfers use checkout currency; preferred setting only triggers FX fee. See /docs/currencies#important-limitations
FX fields missing on group.funded
Omitted when checkout matches preference or mode is checkout; sandbox still includes FX fields when fee would apply live
Card declined in sandbox
Use 4242… test card; live card in live mode only
Settlement failed notification
Payout account capabilities, bank account, holds
Merchant sign-in
Symptom
Fix
No OTP email
Spam folder; production needs Loops configured on Plurel Pay side
OTP not configured error
Contact Plurel Pay ops for production email setup
Passkey sign-in failed
Use email OTP or Google; re-register passkey at Settings → Security
2FA code rejected
Check device clock; use backup code; disable and re-enable at Settings → Security
