Paysafe Integration
Generate production-grade Paysafe payment integrations across both product surfaces — paysafe.js (tokenization SDK with hosted fields) and Paysafe Checkout (hosted overlay with broad payment-method support including ACH).
Before Writing Any Code
Does the integration require ACH / eCheck / bank payments?
- Yes → Paysafe Checkout is the only option. paysafe.js tokenizes cards, Apple Pay, and Google Pay exclusively (closed enum in
instance.tokenize()).
- No, cards only → either product works; see
COMPARISON.md for the UI-control vs integration-effort trade-off.
Identify the host.
- Plain web page (static HTML + JS) — Paysafe's docs assume this.
- Lightning Web Component on Experience Cloud — distinct constraints: CSP Trusted Sites for
hosted.paysafe.com / api.paysafe.com, iframe / overlay policy, Locker Service / LWS DOM restrictions, guest-user permissions, LWR vs Aura runtime. Cross-reference the lwc-experience-cloud skill. See COMPARISON.md LWC/EC section.
- Generic backend consuming only the REST API (no browser) — server-to-server via
/paymenthub/v1/ endpoints, no SDK needed.
Identify the environment.
- Test:
hosted.test.paysafe.com, api.test.paysafe.com.
- Production:
hosted.paysafe.com, api.paysafe.com.
- Keys, merchant accounts, and Business Portal are distinct per environment.
Identify PCI scope.
- Paysafe Checkout (hosted overlay) → SAQ-A.
- paysafe.js (hosted fields in iframes) → SAQ-A.
- Raw PAN on your server → SAQ-D (do not do this — Paysafe's two SDKs exist exactly to avoid it).
The Payment Handle Pattern (shared between both products)
Both products produce a Payment Handle Token (15-min TTL, single-use) as the client-side artifact. The merchant server then calls POST /paymenthub/v1/payments with the payment handle token plus amount / currency / merchant reference number to actually move money. Flow:
- Client: render paysafe.js fields or Paysafe Checkout overlay; user enters details; SDK returns a Payment Handle Token.
- Server: receive the token, call
POST /paymenthub/v1/payments immediately (do not queue — 15-min TTL).
- Webhook: Paysafe POSTs event(s) to your registered webhook URL; verify HMAC-SHA256 signature on the RAW body BEFORE JSON parse; update your order state.
For redirect-based methods in Paysafe Checkout (Skrill, NETELLER, PayPal, PaysafeCash, Interac, Play+, VIP Preferred), the payment flow opens an external browser tab — the resultCallback is unreliable for those methods. Webhook reconciliation is the only authoritative path for redirect methods.
Reference Docs
Read the relevant reference doc BEFORE generating code. Every file follows the instruction-oriented distillation format (scripts/distillation-template.md) — Rules, How It Works, Configuration Examples (code verbatim from Paysafe), Common Mistakes, See Also. Raw archival per-page summaries live under exa-data/archive/ if you need the source.
paysafe.js (client SDK)
| Topic |
File |
| Overview |
reference/paysafe-js/overview.md |
| Setup function |
reference/paysafe-js/setup-function.md |
| Show function |
reference/paysafe-js/show-function.md |
| Event handling |
reference/paysafe-js/event-handling.md |
| Tokenize |
reference/paysafe-js/tokenize.md |
| Transaction with payment handle |
reference/paysafe-js/transaction-with-payment-handle.md |
| 3D Secure integration |
reference/paysafe-js/3ds-integration.md |
| Multiple currencies |
reference/paysafe-js/multiple-currencies.md |
| Additional functions |
reference/paysafe-js/additional-functions.md |
| Saved cards integration |
reference/paysafe-js/saved-cards-integration.md |
| Integrate with Google Pay |
reference/paysafe-js/integrate-with-google-pay.md |
| Integrate with Apple Pay |
reference/paysafe-js/integrate-with-apple-pay.md |
| Instant Withdrawal — Interchecks |
reference/paysafe-js/instant-withdrawal-interchecks.md |
Paysafe Checkout (hosted overlay)
| Topic |
File |
| Checkout overview |
reference/paysafe-checkout/checkout-overview.md |
| How Checkout works |
reference/paysafe-checkout/how-checkout-works.md |
| Before you begin |
reference/paysafe-checkout/before-you-begin.md |
| Setup function |
reference/paysafe-checkout/setup-function.md |
| Callbacks |
reference/paysafe-checkout/callbacks.md |
| Customize Checkout |
reference/paysafe-checkout/customize-checkout.md |
| Example forms |
reference/paysafe-checkout/example-forms.md |
| Supported payment methods |
reference/paysafe-checkout/supported-payment-methods.md |
| About card payments |
reference/paysafe-checkout/about-card-payments.md |
| Typical card payment scenarios |
reference/paysafe-checkout/typical-scenarios-card-payments.md |
| Cards — 3DS |
reference/paysafe-checkout/cards-3ds.md |
| Configure 3DS |
reference/paysafe-checkout/configure-3ds.md |
| Save cards |
reference/paysafe-checkout/save-cards.md |
| Save cards and addresses |
reference/paysafe-checkout/save-cards-and-addresses.md |
| Improve transaction success rate |
reference/paysafe-checkout/improve-transaction-success-rate.md |
| Apple Pay |
reference/paysafe-checkout/apple-pay.md |
| Google Pay |
reference/paysafe-checkout/google-pay.md |
| Pay by Bank US |
reference/paysafe-checkout/pay-by-bank-us.md |
| Interchecks |
reference/paysafe-checkout/interchecks.md |
| NETELLER |
reference/paysafe-checkout/neteller.md |
| Skrill |
reference/paysafe-checkout/skrill.md |
| PaysafeCash |
reference/paysafe-checkout/paysafecash.md |
| Play+ / Sightline |
reference/paysafe-checkout/play-plus-sightline.md |
| Process payments |
reference/paysafe-checkout/process-payments.md |
| Process refunds |
reference/paysafe-checkout/process-refunds.md |
| Process settlements |
reference/paysafe-checkout/process-settlements.md |
| Process withdrawals |
reference/paysafe-checkout/process-withdrawals.md |
| Webhooks |
reference/paysafe-checkout/webhooks.md |
| Webhook events |
reference/paysafe-checkout/webhook-events.md |
Server-Side API (/paymenthub/v1/*)
| Topic |
File |
Payment Handle Token & /paymenthub/v1/payments |
reference/server-api/payment-handle-and-payments.md |
| Refunds, settlements, voids, withdrawals, standalone/original credits |
reference/server-api/refunds-settlements-withdrawals.md |
Webhooks
| Topic |
File |
| HMAC-SHA256 signature verification (Apex + Node examples) |
reference/webhooks/signature-verification.md |
| Event catalog (40+ events, 9 categories, handler dispatch) |
reference/webhooks/event-catalog.md |
| Idempotency and retry handling |
reference/webhooks/idempotency-and-retries.md |
Authentication & Environments
| Topic |
File |
| API keys and Business Portal |
reference/authentication/api-keys-and-business-portal.md |
| Test vs production environments and hosts |
reference/authentication/environments-and-hosts.md |
Cross-product synthesis
| Topic |
File |
| paysafe.js vs Paysafe Checkout — decision guide + LWC/EC callouts |
COMPARISON.md |
| Common pitfalls (81 doc-grounded pitfalls across 12 categories) |
reference/common-pitfalls.md |
Templates
Working code templates — copy and adapt.
| Pattern |
Directory |
| paysafe.js hosted-field tokenization page (card-only) |
templates/paysafe-js-page/ |
| Paysafe Checkout hosted-overlay embed (cards + ACH + wallets) |
templates/paysafe-checkout-page/ |
Server-side /paymenthub/v1/* client (Node + Apex with tests) |
templates/server-tracker-creation/ |
| Webhook receiver — Apex REST with HMAC-SHA256 verification and idempotency |
templates/webhook-handler-apex/ |
| Webhook receiver — Node/Express with raw-body HMAC and idempotency patterns |
templates/webhook-handler-node/ |
Checklists
| Checklist |
File |
| New integration setup |
checklists/new-integration-checklist.md |
| Production go-live |
checklists/production-go-live-checklist.md |
| Lightning Web Component / Experience Cloud embedding |
checklists/experience-cloud-embed-checklist.md |
1---2name: paysafe-integration3description: Integrate the Paysafe payment platform into web apps, Salesforce, or any backend. Covers both product lines: **paysafe.js** (client-side SDK with hosted-field tokenization, card-only — CARD / APPLEPAY / GOOGLEPAY — no ACH/eCheck, PCI SAQ-A via Paysafe-hosted iframes) and **Paysafe Checkout** (white-label hosted overlay — supports cards, Apple Pay, Google Pay, ACH, Instant ACH, Pay by Bank US, Interchecks, Skrill, NETELLER, PaysafeCash, Play+, PayPal/Venmo, and more — less UI customization). Use this skill whenever the user mentions paysafe, paysafe.js, paysafe-js, paysafe fields, Paysafe Checkout, hosted checkout, tokenization, hosted field, single-use payment handle, payment handle token, Paysafe REST API, `/paymenthub/v1`, Payments API, Customer Vault, single-use customer token, ACH, eCheck, Instant ACH, Pay by Bank US, Plaid (as a Paysafe Checkout embedded flow), 3DS, 3D Secure, SAQ-A, SAQ-A-EP, iframe checkout, overlay checkout, Paysafe webhook, Paysafe webhook signature (HMAC-SHA256), `hosted.paysafe.com4---56# Paysafe Integration78Generate production-grade Paysafe payment integrations across both product surfaces — `paysafe.js` (tokenization SDK with hosted fields) and Paysafe Checkout (hosted overlay with broad payment-method support including ACH).910## Before Writing Any Code11121. **Does the integration require ACH / eCheck / bank payments?**13 - Yes → **Paysafe Checkout is the only option.** paysafe.js tokenizes cards, Apple Pay, and Google Pay exclusively (closed enum in `instance.tokenize()`).14 - No, cards only → either product works; see `COMPARISON.md` for the UI-control vs integration-effort trade-off.15162. **Identify the host.**17 - Plain web page (static HTML + JS) — Paysafe's docs assume this.18 - **Lightning Web Component on Experience Cloud** — distinct constraints: CSP Trusted Sites for `hosted.paysafe.com` / `api.paysafe.com`, iframe / overlay policy, Locker Service / LWS DOM restrictions, guest-user permissions, LWR vs Aura runtime. Cross-reference the `lwc-experience-cloud` skill. See `COMPARISON.md` LWC/EC section.19 - Generic backend consuming only the REST API (no browser) — server-to-server via `/paymenthub/v1/` endpoints, no SDK needed.20213. **Identify the environment.**22 - Test: `hosted.test.paysafe.com`, `api.test.paysafe.com`.23 - Production: `hosted.paysafe.com`, `api.paysafe.com`.24 - Keys, merchant accounts, and Business Portal are distinct per environment.25264. **Identify PCI scope.**27 - Paysafe Checkout (hosted overlay) → SAQ-A.28 - paysafe.js (hosted fields in iframes) → SAQ-A.29 - Raw PAN on your server → SAQ-D (do not do this — Paysafe's two SDKs exist exactly to avoid it).3031## The Payment Handle Pattern (shared between both products)3233Both products produce a **Payment Handle Token** (15-min TTL, single-use) as the client-side artifact. The merchant server then calls `POST /paymenthub/v1/payments` with the payment handle token plus amount / currency / merchant reference number to actually move money. Flow:34351. **Client**: render paysafe.js fields or Paysafe Checkout overlay; user enters details; SDK returns a Payment Handle Token.362. **Server**: receive the token, call `POST /paymenthub/v1/payments` immediately (do not queue — 15-min TTL).373. **Webhook**: Paysafe POSTs event(s) to your registered webhook URL; verify HMAC-SHA256 signature on the RAW body BEFORE JSON parse; update your order state.3839For redirect-based methods in Paysafe Checkout (Skrill, NETELLER, PayPal, PaysafeCash, Interac, Play+, VIP Preferred), the payment flow opens an **external browser tab** — the `resultCallback` is unreliable for those methods. **Webhook reconciliation is the only authoritative path** for redirect methods.4041## Reference Docs4243Read the relevant reference doc BEFORE generating code. Every file follows the instruction-oriented distillation format (`scripts/distillation-template.md`) — Rules, How It Works, Configuration Examples (code verbatim from Paysafe), Common Mistakes, See Also. Raw archival per-page summaries live under `exa-data/archive/` if you need the source.4445### paysafe.js (client SDK)46| Topic | File |47|---|---|48| Overview | `reference/paysafe-js/overview.md` |49| Setup function | `reference/paysafe-js/setup-function.md` |50| Show function | `reference/paysafe-js/show-function.md` |51| Event handling | `reference/paysafe-js/event-handling.md` |52| Tokenize | `reference/paysafe-js/tokenize.md` |53| Transaction with payment handle | `reference/paysafe-js/transaction-with-payment-handle.md` |54| 3D Secure integration | `reference/paysafe-js/3ds-integration.md` |55| Multiple currencies | `reference/paysafe-js/multiple-currencies.md` |56| Additional functions | `reference/paysafe-js/additional-functions.md` |57| Saved cards integration | `reference/paysafe-js/saved-cards-integration.md` |58| Integrate with Google Pay | `reference/paysafe-js/integrate-with-google-pay.md` |59| Integrate with Apple Pay | `reference/paysafe-js/integrate-with-apple-pay.md` |60| Instant Withdrawal — Interchecks | `reference/paysafe-js/instant-withdrawal-interchecks.md` |6162### Paysafe Checkout (hosted overlay)63| Topic | File |64|---|---|65| Checkout overview | `reference/paysafe-checkout/checkout-overview.md` |66| How Checkout works | `reference/paysafe-checkout/how-checkout-works.md` |67| Before you begin | `reference/paysafe-checkout/before-you-begin.md` |68| Setup function | `reference/paysafe-checkout/setup-function.md` |69| Callbacks | `reference/paysafe-checkout/callbacks.md` |70| Customize Checkout | `reference/paysafe-checkout/customize-checkout.md` |71| Example forms | `reference/paysafe-checkout/example-forms.md` |72| Supported payment methods | `reference/paysafe-checkout/supported-payment-methods.md` |73| About card payments | `reference/paysafe-checkout/about-card-payments.md` |74| Typical card payment scenarios | `reference/paysafe-checkout/typical-scenarios-card-payments.md` |75| Cards — 3DS | `reference/paysafe-checkout/cards-3ds.md` |76| Configure 3DS | `reference/paysafe-checkout/configure-3ds.md` |77| Save cards | `reference/paysafe-checkout/save-cards.md` |78| Save cards and addresses | `reference/paysafe-checkout/save-cards-and-addresses.md` |79| Improve transaction success rate | `reference/paysafe-checkout/improve-transaction-success-rate.md` |80| Apple Pay | `reference/paysafe-checkout/apple-pay.md` |81| Google Pay | `reference/paysafe-checkout/google-pay.md` |82| Pay by Bank US | `reference/paysafe-checkout/pay-by-bank-us.md` |83| Interchecks | `reference/paysafe-checkout/interchecks.md` |84| NETELLER | `reference/paysafe-checkout/neteller.md` |85| Skrill | `reference/paysafe-checkout/skrill.md` |86| PaysafeCash | `reference/paysafe-checkout/paysafecash.md` |87| Play+ / Sightline | `reference/paysafe-checkout/play-plus-sightline.md` |88| Process payments | `reference/paysafe-checkout/process-payments.md` |89| Process refunds | `reference/paysafe-checkout/process-refunds.md` |90| Process settlements | `reference/paysafe-checkout/process-settlements.md` |91| Process withdrawals | `reference/paysafe-checkout/process-withdrawals.md` |92| Webhooks | `reference/paysafe-checkout/webhooks.md` |93| Webhook events | `reference/paysafe-checkout/webhook-events.md` |9495### Server-Side API (`/paymenthub/v1/*`)96| Topic | File |97|---|---|98| Payment Handle Token & `/paymenthub/v1/payments` | `reference/server-api/payment-handle-and-payments.md` |99| Refunds, settlements, voids, withdrawals, standalone/original credits | `reference/server-api/refunds-settlements-withdrawals.md` |100101### Webhooks102| Topic | File |103|---|---|104| HMAC-SHA256 signature verification (Apex + Node examples) | `reference/webhooks/signature-verification.md` |105| Event catalog (40+ events, 9 categories, handler dispatch) | `reference/webhooks/event-catalog.md` |106| Idempotency and retry handling | `reference/webhooks/idempotency-and-retries.md` |107108### Authentication & Environments109| Topic | File |110|---|---|111| API keys and Business Portal | `reference/authentication/api-keys-and-business-portal.md` |112| Test vs production environments and hosts | `reference/authentication/environments-and-hosts.md` |113114### Cross-product synthesis115| Topic | File |116|---|---|117| **paysafe.js vs Paysafe Checkout — decision guide + LWC/EC callouts** | `COMPARISON.md` |118| Common pitfalls (81 doc-grounded pitfalls across 12 categories) | `reference/common-pitfalls.md` |119120## Templates121122Working code templates — copy and adapt.123124| Pattern | Directory |125|---|---|126| paysafe.js hosted-field tokenization page (card-only) | `templates/paysafe-js-page/` |127| Paysafe Checkout hosted-overlay embed (cards + ACH + wallets) | `templates/paysafe-checkout-page/` |128| Server-side `/paymenthub/v1/*` client (Node + Apex with tests) | `templates/server-tracker-creation/` |129| Webhook receiver — Apex REST with HMAC-SHA256 verification and idempotency | `templates/webhook-handler-apex/` |130| Webhook receiver — Node/Express with raw-body HMAC and idempotency patterns | `templates/webhook-handler-node/` |131132## Checklists133134| Checklist | File |135|---|---|136| New integration setup | `checklists/new-integration-checklist.md` |137| Production go-live | `checklists/production-go-live-checklist.md` |138| Lightning Web Component / Experience Cloud embedding | `checklists/experience-cloud-embed-checklist.md` |
andrewdhood