עסקה שהושלמה ב-Paddle Billing הופכת למסמך, וזיכוי מאושר הופך לחשבונית זיכוי.
חשוב לפני שמתחילים: Paddle היא merchant of record. היא המוכרת ללקוח הקצה, גובה את המס בשמה ומעבירה אליכם תשלום. התייעצו עם רואה החשבון אם וכיצד להפיק מסמך על כל עסקה לפני שמפעילים את החיבור.
התקנה (5 דקות)#
- ב-Paddle: Developer tools → Notifications → New destination, סוג Webhook.
- ב-URL הדביקו את כתובת ה-Webhook שמוצגת אצלכם במסך החיבור.
- בחרו את האירועים
transaction.completedו-adjustment.updated. - אחרי השמירה פתחו את ה-destination, העתיקו את ה-Secret key והדביקו אותו בשדה הסוד.
- בחרו סוג מסמך ולחצו על "שליחת הזמנת בדיקה".
הערה: האירוע של Paddle כולל רק את מזהה הלקוח (ctm_…). שם ואימייל יופיעו במסמך רק כשהאירוע כולל אובייקט customer. אחרת הלקוח יירשם "לקוח/ה".
Developer reference#
Endpoint: POST /api/billing/ecommerce/paddle/<hookId>
Auth: Paddle-Signature: ts=<unix>;h1=<hex> = HMAC-SHA256(secret key, "<ts>:<rawBody>") as hex, compared in constant time. Every h1 is tried (secret rotation). Paddle's SDKs use a 5-second tolerance; this connector accepts 5 minutes, since a replay is harmless (idempotent by transaction id). Docs: https://developer.paddle.com/webhooks/signature-verification
| Event | Result |
|---|---|
transaction.completed | document |
adjustment.updated with action = refund and status = approved | credit note |
pending_approval / rejected refunds, chargebacks, all other events | 200 {skipped} |
Payload reference: https://developer.paddle.com/webhooks/transactions/transaction-completed/, https://developer.paddle.com/webhooks/adjustments/adjustment-updated/
| Paddle field | Document |
|---|---|
data.id (txn_…) | externalId, apiIdentifier = paddle-<id> |
details.line_items[].product.name, quantity | line name, quantity |
details.line_items[].totals.total (string, smallest unit, gross) | line gross (taxIncluded: true) |
details.line_items[].tax_rate ("0.18") | line vatBp (1800) |
details.totals.grand_total | the payment row; if the line gross does not add up it is spread proportionally so document = payment |
data.payments[captured].method_details.type | paypal → PayPal, else credit card |
data.currency_code | uppercased; non-ILS needs an exchange rate (recorded as error) |
data.customer (only when embedded) | customer name / email |
Refunds: refund id = adjustment.id, original = transaction_id, type: "full" → full credit, partial → totals.total.
Test with curl:
HOOK="https://<your-host>/api/billing/ecommerce/paddle/<hookId>"
SECRET="pdl_ntfset_..." # the secret you pasted in the connector
BODY='{"event_id":"evt_1","event_type":"transaction.completed","occurred_at":"2026-09-20T10:18:50Z","data":{"id":"txn_test_1","status":"completed","currency_code":"ILS","billed_at":"2026-09-20T10:18:48Z","details":{"totals":{"tax":"3600","total":"23600","grand_total":"23600"},"line_items":[{"quantity":1,"tax_rate":"0.18","product":{"name":"רישיון שנתי"},"totals":{"total":"23600"}}]},"payments":[{"status":"captured","method_details":{"type":"card"}}]}}'
TS=$(date +%s)
H1=$(printf '%s:%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -i -X POST "$HOOK" -H "Content-Type: application/json" -H "Paddle-Signature: ts=$TS;h1=$H1" -d "$BODY"Troubleshooting#
- 401 invalid signature: הסוד לא של אותו destination, או שהחתימה ישנה מ-5 דקות (בדקו שעון). לכל destination סוד משלו.
- 401 secret is not configured: עדיין לא הדבקתם Secret key.
- 404 unknown hook: כתובת ה-Webhook לא הועתקה במלואה.
- זיכוי לא הופק: Paddle שולחת
adjustment.updatedרק כשהזיכוי אושר. זיכוי שממתין לאישור מדולג עד שיאושר. - הזמנה בסטטוס blocked או dormant: מגבלת החבילה או מודול החיוב כבוי. אפשר להפיק ידנית מיומן ההזמנות.