Paysafe

Adapter 0.1.0, documentation reviewed 2026-10-25. Overall status: limited.

Capabilities

Supported input

Notification delivery

• Repeated deliveries are recognized by eventName, resourceId, payload status and eventDate together; Paysafe documents no event id or delivery id; Paysafe documents that notifications can be delivered more than once.
• Delivery order: not documented by the provider.
• Paysafe asks merchants to ignore a notification received again for an already processed event and to make the endpoint idempotent. It sends at most 3 attempts (attemptNumber counts them) with undocumented intervals, documents no ordering, and recommends a GET call to reconfirm the status a webhook reports.

Known limitations

• Paysafe documents no chargeback or dispute resource, endpoint or webhook for the Payments API. Chargebacks and retrieval requests are handled in the Merchant Back Office, so no dispute timeline can be built. Error 3425 (refund blocked because a chargeback exists) is the only chargeback signal in the API.
• Settlements, refunds and void authorizations carry their parent id only in the request path (/payments/{paymentId}/settlements, /settlements/{settlementId}/refunds, /payments/{paymentId}/voidauths). They are linked to their parent only when a pasted HTTP request line contains that path; otherwise their own id is used as the reference and they are reported as not linked. A settlement made with settleWithAuth true (or by a one-step APM) shares its id with the payment and is linked through that id.
• Refund, void, settlement, credit and verification responses share their fields. Without a request path, a webhook event name, a documented webhook type or a distinguishing field (settleWithAuth, availableToSettle, settlements[] for payments, availableToRefund for settlements, handle fields for payment handles), the resource type is shown as unknown.
• The processor tables (OPN/NAG, MON, TAS/VPS, FRD, VAN) are documented by processor name without saying which field carries them. gatewayResponse.responseCode is read with the table named by gatewayResponse.code only by inference (the one documented example, VPS with 00, matches the TAS/VPS table), so these decodes are never stronger than possible; GPS and other acquirer codes have no table. The AVS letters listed under error 3007 are read from gatewayResponse.avsCode by the same kind of inference.
• Documented but not decoded, because Paysafe does not document which payload field carries them: the Interchecks issuer reasons of ERR_OCT_DECLINE, SafetyPay and PayPal downstream codes (Paysafe maps them to its own error codes), the ACH, BACS, EFT and SEPA return codes (Merchant Back Office reports only) and the Paysafe JS client codes. Interchecks names in error.code are decoded with possible confidence, except the three Add Card codes the OpenAPI file shows as error codes.
• Raw downstream statuses in gatewayResponse.status (for example Skrill Quick Checkout or SafetyPay values) are not explained by Paysafe and are shown as sent. Skrill data nested in a Paysafe payload stays a Paysafe record; Skrill's own formats belong to the Skrill adapter.
• Webhooks have no event id. The delivery key combines eventName, resourceId, the payload status and eventDate as the research suggests; whether eventDate stays the same across retries is not documented. attemptNumber above 1 marks a redelivery. Signatures (Signature header, HMAC-SHA256) cannot be verified from pasted data, so a pasted webhook is never treated as authentic; only the presence of the header is reported.
• Three webhook envelope shapes appear in Paysafe's material: a flat resource (read as a resource), a full envelope with eventType and mode, and the SDK envelope with type. attemptNumber is a string in examples and an integer in the SDK; mode is live even in examples that link to the test host. Several documented examples have trailing commas, which are accepted with a warning.
• A payment handle COMPLETED status only means the handle was used; Paysafe sets it whatever the payment outcome, so it is shown with an unknown outcome. Handles and payments are linked through the paymentHandleToken, which is never copied: only a one-way hash of it is used as a correlation key.
• merchantRefNum is shown but never used for linking: it is a merchant reference, settlement examples reuse the payment's value, and the duplicate check that keeps it unique can be turned off (dupCheck).
• Payment Scheduler webhooks (scheduled payments, retries, trials, suspension, cancellation) are interpreted from the event name only; their payload shape and where the execution stage appears are not documented. Registration events are shown without a payment reference.
• Statuses outside the OpenAPI enums (ERROR for handles, refunds, settlements and credits, CANCELLED for handles, PROCESSING for settlements and refunds) are accepted from the webhook pages. statusReason is shown as sent; only PSP_REJECTED, AUTH_EXPIRED and AUTO_SETTLE_EXPIRED_PAYMENT_HANDLE are documented. riskReasonCode values are not documented.
• A settlement COMPLETED means Paysafe completed its settlement batch; when funds reach the merchant is not documented. A COMPLETED standalone credit can later fail, be cancelled or be returned (SA_CREDIT_FAILED, SA_CREDIT_CANCELLED, SA_CREDIT_RETURN_COMPLETED).
• Timestamps without a time zone (for example txnTime 2025-04-10T17:21:33.4 in a webhook example) are shown as sent and not used as event time. settlements[].txnTime can be epoch milliseconds or an ISO string.
• List responses (meta with numberOfRecords, limit, page) and legacy Cards API requests are recognized but not analyzed; the name of the list array is not documented. Legacy Cards API responses pasted without the request line resemble Payments API payments and are read with the same rules, although the legacy reference was not reviewed.
• An error response with a plain-text or empty body is recognized only through the X-Application-Status-Code header; without it nothing in the record identifies Paysafe.
• Numeric code spaces overlap: 3060 means Strong Customer Authentication required on the card errors page but an unsolicited reversal in the Interchecks mapping, and 3703 differs in the same way. Both meanings are shown. DW-CUSTOMER-CONFLICT appears only in an SDK test fixture and is decoded as unknown.
• Category and retry guidance per code are PandaPayLens suggestions. Paysafe's own retry signals are the merchant advice codes (ADVICE-01 to ADVICE-14, ADVICE-42), code 1100 (retry later) and the VSPS rows of the processor tables; Paysafe documents no idempotency header, so a retry after an unknown outcome should start with a lookup by id or merchantRefNum.

Examples

• Paysafe: card declined with merchant advice: An HTTP 402 decline with a merchant advice code, an ISO response code and a raw processor code.
• Paysafe: EPS payment webhooks: A payment handle and its payment linked into one timeline.

Provider documentation

• Payments API reference
• Payments API OpenAPI file (Error Summary and processor tables)
• Card errors, merchant advice codes and ISO response codes
• Card payments and card webhook examples
• Payments API get started
• Settlement flow diagrams
• Configure webhooks
• Webhook events
• EPS webhooks (full envelope examples)
• Transactions and chargebacks
• Java SDK (error handling, correlation id, webhook handler)
• Onboarding criteria (rejected sectors)

PandaPayLens is not affiliated with Paysafe. Pasted notifications are never treated as verified: PandaPayLens does not check webhook signatures.