# Paysafe Integration

> 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.com

- Skill: `andrewdhood/paysafe-integration` (Agent Skill, multi-file: 127 files)
- Install (CLI): `npx skillmds@latest add andrewdhood/paysafe-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andrewdhood/paysafe-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: andrewdhood (https://skillmd.com/u/andrewdhood)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/andrewdhood/paysafe-integration

---


# 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

1. **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.

2. **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.

3. **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.

4. **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:

1. **Client**: render paysafe.js fields or Paysafe Checkout overlay; user enters details; SDK returns a Payment Handle Token.
2. **Server**: receive the token, call `POST /paymenthub/v1/payments` immediately (do not queue — 15-min TTL).
3. **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` |