דלג לתוכן הראשי
TAKBULL × LOVABLE · מדריך למפתחים ולבוני אתרים

סליקה ב־Lovable עם תקבול:
מהכפתור הראשון לתשלום מאומת

בניתם אתר, חנות או שירות ב־Lovable? חברו אליו תשלום באמצעות תקבול, הציגו דף סליקה בתוך האתר, ועדכנו את ההזמנה לאחר אימות התשלום בשרת.

iframe / Redirect · יצירת הזמנה · IPN · מסמכים אוטומטיים

תשלום כחלק מהאתר

טופס התשלום של תקבול בתוך חלון נגיש, עם אפשרות להפניה לדף התשלום.

עדכון גם אחרי סגירת הדפדפן

הודעת IPN מאפשרת לשרת להמשיך לטפל בתוצאה בלי להסתמך על חזרת הלקוח.

תשתית להמשך

שיוך הזמנות, הפקת מסמכים ואוטומציות בהתאם להגדרות החשבון ולצרכי העסק.

לפני שמתחילים: אתר, חשבון וצד שרת

החיבור מורכב משלושה חלקים: ממשק התשלום באתר, שרת שיוצר הזמנה מול תקבול, ונקודת קצה שמקבלת עדכונים ומאמתת את העסקה.

  • חשבון תקבול עם הרשאות API ואפשרות סליקה פעילה בהתאם להסכם שלכם.
  • מפתחות API_Key ו־API_Secret. לקבלת פרטי סביבת בדיקות יש לפנות לתמיכת תקבול.
  • Backend או פונקציות שרת בפרויקט, מסד נתונים להזמנות וכתובת HTTPS לקבלת IPN.
  • מסכי Checkout, בדיקת סטטוס ועמוד תודה.
המפתחות נשארים בשרת.

שמרו אותם במנגנון הסודות של סביבת השרת. אין להטמיע מפתחות אמיתיים בקוד React, במשתני סביבה שנחשפים לדפדפן, בווידג׳ט Elementor או בפרומפט המועתק לצ׳אט.

תיעוד המקור לכל שמות השדות והפעולות: Takbull API Documentation.

1. יוצרים הזמנה בצד השרת

כאשר הלקוח לוחץ על כפתור התשלום, האתר פונה לשרת שלכם. השרת מזהה את המשתמש, בודק את ההזמנה ומחשב את הסכום לפי הנתונים השמורים אצלו. אין לקבל את המחיר מהדפדפן כנתון סמכותי.

שלחו בקשת POST לכתובת:

https://api.takbull.co.il/api/ExtranalAPI/GetTakbullPaymentPageRedirectUrl

בכותרות הבקשה יש להעביר Content-Type: application/json,‏ API_Key ו־API_Secret. שם הנתיב ExtranalAPI מופיע כך בתיעוד ויש לשמור על האיות.

דוגמת גוף בקשה

זוהי דוגמה לתשלום חד־פעמי, ללא הפקת מסמך. החליפו את כתובות הדוגמה בכתובות שלכם.

{
  "order_reference": "ORDER-1001",
  "OrderTotalSum": 150,
  "Currency": "ILS",
  "Language": "he",
  "DealType": 1,
  "DisplayType": "iframe",
  "PostProcessMethod": "1",
  "RedirectAddress": "https://your-site.example/payment-return",
  "CancelReturnAddress": "https://your-site.example/checkout",
  "IPNAddress": "https://your-site.example/api/takbull/ipn",
  "CreateDocument": false
}

שומרים את מזהה ההזמנה שחזר

{
  "responseCode": 0,
  "uniqId": "89fd6612-2c4b-4a7b-91a3-dd9bdf0ee26a"
}

בדקו גם את תוצאת HTTP וגם את responseCode. קוד 0 מציין שהבקשה הצליחה — הוא אינו מעיד שהלקוח כבר שילם. שמרו את uniqId לצד מזהה ההזמנה המקומי, הסכום, המטבע והמשתמש. במקרה שגיאה, הציגו הודעה מתאימה ואל תפתחו iframe עם מזהה חסר.

2. מציגים את דף התשלום בתוך האתר

בנו את כתובת התשלום מתוך uniqId שהשרת קיבל, והעבירו אותה לממשק:

https://api.takbull.co.il/PaymentGateway?orderUniqId={uniqId}

ב־Lovable בקשו ליצור Modal נגיש המכיל iframe עם המזהה takbull_iframe, כותרת תיאורית ו־allow="payment". אין ליצור באתר טופס עצמאי שאוסף מספר כרטיס או קוד אבטחה; פרטי הכרטיס מוזנים בדף התשלום של תקבול.

  • כפתור סגירה עם שם ברור ונגיש למקלדת.
  • העברת המיקוד לחלון בפתיחה, שמירת המיקוד בתוכו והחזרתו לכפתור התשלום בסגירה.
  • תמיכה במקש Escape וסימון מצב טעינה ושגיאות בטקסט.
  • התאמה למסכים קטנים ולגובה דף התשלום.

סגירת החלון אינה מבטלת בהכרח עסקה שכבר נשלחה. לאחר סגירה או ניסיון חוזר, בדקו את הסטטוס בשרת. אם בוחרים בזרימת Redirect, יש להתאים גם את DisplayType ואת PostProcessMethod; אין להניח שכל אמצעי התשלום מתנהגים באופן זהה בתוך iframe.

3. קולטים הודעות מה־iframe

בזרימת PostProcessMethod="1", הודעת התוצאה מזוהה באמצעות event.data.message === "paymentreplay". פרטי התוצאה נמצאים בתוך event.data.value, וביניהם InternalCode,‏ InternalDescription,‏ transactionInternalId ו־uniqId.

הקוד הבא הוא דוגמה למאזין בצד הלקוח, ולא אינטגרציה שלמה. הוא בודק את מקור ההודעה, את חלון ה־iframe ואת ההזמנה הצפויה, ומטפל גם בגובה שמגיע כמספר או כמחרוזת מספרית.

// Frontend example only. Register after the iframe is mounted.
// expectedUniqId is the order ID returned by YOUR backend.
function attachTakbullListener(expectedUniqId, onPaymentSignal) {
  const iframe = document.getElementById("takbull_iframe");
  if (!iframe) throw new Error("Takbull iframe is missing");
  const allowedOrigin = "https://api.takbull.co.il";

  const handler = (event) => {
    if (event.origin !== allowedOrigin) return;
    if (event.source !== iframe.contentWindow) return;
    const data = event.data;

    if (data && typeof data === "object" &&
        data.message === "paymentreplay") {
      const result = data.value;
      if (!result || typeof result !== "object") return;
      if (result.uniqId !== expectedUniqId) return;
      if (typeof result.InternalCode !== "number") return;
      // Update UI / ask YOUR server for verified status.
      // Never mark an order paid based on this message alone.
      onPaymentSignal({
        reportedSuccess: result.InternalCode === 0,
        description: typeof result.InternalDescription === "string"
          ? result.InternalDescription : "",
        uniqId: result.uniqId
      });
      return;
    }

    const isNumeric = typeof data === "number" ||
      (typeof data === "string" && /^\d+(\.\d+)?$/.test(data.trim()));
    if (!isNumeric) return;
    const height = Number(data);
    if (!Number.isFinite(height) || height <= 0) return;
    iframe.style.height = `${Math.min(Math.max(height + 50, 320), 1400)}px`;
  };

  window.addEventListener("message", handler);
  return () => window.removeEventListener("message", handler);
}

ב־React רשמו את המאזין לאחר יצירת ה־iframe והחזירו את פונקציית הניקוי מתוך useEffect. התאימו את גבולות הגובה לעיצוב ובדקו שאינם מסתירים שדות. אם מקור ההודעות משתנה בסביבה מאושרת, הגדירו כתובת מדויקת לאחר בדיקה; אל תחליפו את האימות בקבלה של כל דומיין.

הצלחה בדפדפן אינה אישור סופי להזמנה.

אפשר להציג ״בודקים את התשלום״ ולבקש מהשרת סטטוס מאומת. אין להפעיל מנוי, לשחרר מוצר או לסמן תשלום כמושלם רק בעקבות postMessage או פרמטר בכתובת החזרה.

4. מאמתים את התשלום עם IPN

תקבול שולחת עדכון לכתובת IPNAddress שהוגדרה בהזמנה. לפי התיעוד, עדכון התשלום מגיע בבקשת GET עם פרמטרים בכתובת, ובהם uniqId,‏ order_reference,‏ statusCode ו־transactionInternalNumber.

ה־IPN עשוי להגיע לפני הודעת הדפדפן או אחריה. השרת צריך לטפל בו גם כשהלקוח סגר את האתר, ולאמת את המצב מול תקבול.

  1. אתרו את ההזמנה המקומית בעזרת המזהים שהתקבלו. אל תסמכו על הסכום או על קוד ההצלחה מהבקשה הנכנסת בלבד.
  2. שלחו מהשרת בקשת POST לנתיב האימות, עם מפתחות API בכותרות.
  3. בדקו את תוצאת האימות, סטטוס התשלום והסכום מול ההזמנה הצפויה. לפי הצורך, השלימו נתוני עסקה דרך GetTransaction, לרבות המטבע.
  4. עדכנו את ההזמנה וספקו את השירות רק לאחר אישור מאומת. במצב לא חד־משמעי השאירו את ההזמנה בהמתנה לבדיקה.
  5. מנעו טיפול כפול: קבלת אותה הודעה שוב לא תיצור מסמך נוסף, הרשאה כפולה או אספקה חוזרת.
POST https://api.takbull.co.il/api/ExtranalAPI/ValidateNotification
Content-Type: application/json
API_Key: <SERVER_SECRET>
API_Secret: <SERVER_SECRET>

{
  "uniqId": "89fd6612-2c4b-4a7b-91a3-dd9bdf0ee26a"
}
שימו לב לאותיות בשמות השדות.

בהודעת iframe מופיע InternalCode, ובתגובת האימות מופיע internalCode. אין להעתיק את בדיקת ההצלחה של הדפדפן לתגובת השרת בלי להתאים אותה לסכמת התגובה.

התיעוד מציג דוגמת תגובת אימות שאינה תקינה (INVALID), ואינו מפרט בסעיף זה את כל ערכי הסטטוסים. לפני עלייה לאוויר יש לוודא מול תקבול ובסביבת הבדיקות את תנאי האישור המדויקים. אין להמציא מיפוי ל־orderStatus או ל־tranSactionStatus.

5. מוסיפים מסמכים ואפשרויות תשלום

הפקת מסמך עם התשלום

כדי לבקש הפקת מסמך, השתמשו ב־CreateDocument=true, בחרו DocumentType מתאים, והעבירו Products ופרטי לקוח. לדוגמה, 320 הוא חשבונית מס קבלה ו־400 הוא קבלה. סוג המסמך חייב להתאים לעסק ולעסקה.

ודאו שסכומי הפריטים, הכמויות, ההנחות והמס תואמים לסכום ההזמנה. אם תקבול כבר מפיקה את המסמך כחלק מהתשלום, אל תוסיפו יצירת מסמך עצמאית ללא בדיקת כפילות.

Bit, מנויים וטוקנים

ל־Bit מתועדת זרימה עם PaymentMethodType=21. במובייל יש להעביר IsMobile=true ולהשתמש ב־url המוחזר לפתיחת האפליקציה. לכן אין להציג במדריך הבטחה שכל התשלום תמיד נשאר בתוך החלון.

מנויים וחיוב טוקן דורשים תכנון נוסף של מועדי החיוב, שמירת הנתונים וטיפול בתוצאות. אין להניח שכל עסקה רגילה מחזירה טוקן לשימוש חוזר. זמינות אמצעי התשלום והאפשרויות תלויה בהגדרות ובהרשאות החשבון.

פרומפט מוכן להדבקה ב־Lovable

העתיקו את ההנחיה הבאה לפרויקט. היא מגדירה את זרימת העבודה ואת בדיקות האימות; את המפתחות והכתובות האמיתיות הגדירו בנפרד בסביבת השרת. יצירת הקוד באמצעות AI אינה מחליפה בדיקת חיבור.

Build a Takbull payment integration for this Lovable project.
Use the official documentation: https://api.takbull.co.il/ApiDocs
Do not invent endpoint names, response fields or status enum meanings.

Backend:
- Use this project's server-side runtime and secret store.
- Keep API_Key and API_Secret exclusively on the server.
- Authenticate checkout requests and authorize access to each local order.
- Calculate amount and currency using trusted server-side order data.
- POST /api/ExtranalAPI/GetTakbullPaymentPageRedirectUrl at
  https://api.takbull.co.il with the two API headers and JSON content type.
- Send order_reference, OrderTotalSum, Currency, Language,
  DealType=1, DisplayType="iframe", PostProcessMethod="1",
  RedirectAddress, CancelReturnAddress and IPNAddress.
- Start with CreateDocument=false unless document creation is configured.
- Check HTTP errors, responseCode===0 and a valid uniqId.
- Persist uniqId against the local order before returning the payment URL.
- Construct https://api.takbull.co.il/PaymentGateway?orderUniqId={uniqId}.
- Prevent duplicate checkout attempts from generating uncontrolled payments.

Frontend:
- Create an accessible responsive modal containing takbull_iframe.
- Add a descriptive iframe title and allow="payment".
- Implement focus trapping, Escape, a labeled close button and focus return.
- Verify event.origin === "https://api.takbull.co.il" and
  event.source === iframe.contentWindow before processing messages.
- Handle event.data.message === "paymentreplay" using event.data.value.
- Require the returned uniqId to match the current expected order.
- InternalCode===0 is a UI signal, not final server confirmation.
- Handle finite positive heights provided as numbers or numeric strings.
- Clean up listeners on unmount and when switching orders.
- Ask our authenticated backend for verified order status, using bounded
  polling if needed; show pending, confirmed or failed states accessibly.
- Do not expose card tokens or full payment payloads in browser logs.

IPN and verification:
- Implement a public HTTPS GET callback for payment IPN query parameters.
- This callback cannot require a customer browser login or cookie.
- Treat incoming parameters as untrusted; identify a known local order.
- POST /api/ExtranalAPI/ValidateNotification with {uniqId} and API headers.
- Match the verified payment to the expected order and amount; retrieve
  transaction details through documented GetTransaction when needed,
  including currency and charge type.
- Do not infer undocumented orderStatus/tranSactionStatus meanings.
  Confirm approval criteria from sandbox responses and Takbull support.
  Unknown or ambiguous results must remain pending, never marked paid.
- Use transactional, idempotent order updates and fulfillment.
- Support duplicate IPN events and either callback/browser arrival order.
- Never fulfill an order based only on redirect parameters or postMessage.

Before launch:
- Configure real callback URLs and test credentials privately.
- Test success, decline, pending, cancellation, browser closure,
  duplicate IPN, amount mismatch, wrong message origin/source,
  a mismatched uniqId, API timeout and mobile layout.
- Clearly list any remaining backend configuration or approval criteria.
- Do not claim the integration is production-ready before these pass.

בודקים את החיבור לפני שמתחילים לקבל תשלומים

תרחישים שחשוב לבדוק בסביבת הבדיקות
תרחישהתוצאה המצופה
תשלום מאושרההזמנה מתעדכנת לאחר אימות שרת ונוצר שיוך לעסקה הנכונה.
סירוב או תוצאה לא ברורהמוצגת הודעה מתאימה; לא מסופק שירות ללא אישור.
סגירת הדפדפןה־IPN והאימות ממשיכים בצד השרת.
IPN כפול או מוקדםאין אספקה כפולה, ואין תלות בסדר הגעת ההודעות.
סכום או מזהה לא תואםההזמנה אינה מסומנת כשולמה ונשלחת לבדיקה.
הודעה ממקור לא מורשההמאזין מתעלם ממנה, גם אם היא נראית כמו הודעת הצלחה.
מובייל ומקלדתהטופס שמיש, המיקוד נשמר, אין חיתוך שדות וניתן לסגור את החלון.
תקלה ברשתמוצג מצב ברור ונבדק סטטוס לפני ניסיון תשלום נוסף.

שאלות נפוצות

האם אפשר לחבר תקבול לאתר שנבנה ב־Lovable?

כן. ניתן לבנות חיבור באמצעות ה־API של תקבול, עם יצירת הזמנה בצד השרת, הצגת דף תשלום ואימות התוצאה. יש להגדיר בפרויקט את רכיבי השרת והנתונים הנדרשים.

האם מספיק להוסיף iframe לאתר?

לא. ה־iframe מציג את דף התשלום. נדרשים גם יצירת הזמנה בשרת, שמירת המזהים וקבלת IPN עם אימות מול תקבול.

האם חייבים להוציא את הלקוח מהאתר?

אפשר להשתמש ב־iframe בתוך חלון באתר או בזרימת Redirect. יש להתאים את הזרימה לאמצעי התשלום ולמכשיר, ולבדוק אותה בפועל.

איפה שומרים את מפתחות ה־API?

במנגנון הסודות של צד השרת בלבד. אין להכניס אותם לקוד הדפדפן, לתוכן העמוד או לקוד Elementor.

מתי מציגים שהתשלום הושלם?

לאחר שהשרת אימת את תוצאת התשלום ושייך אותה להזמנה הצפויה. עד אז אפשר להציג הודעת בדיקה או המתנה.

האם ניתן להפיק מסמך עם התשלום?

כן, באמצעות הפרמטרים המתועדים להפקת מסמך, כולל CreateDocument, סוג מסמך ופריטי Products, ובהתאם להגדרות העסק.

מבוסס על תיעוד ה־API של תקבול, שנבדק ב־11.11.2026. דוגמאות הקוד הן להמחשה ודורשות התאמה לפרויקט ובדיקת סביבת בדיקות. מבנה התגובות בתיעוד הוא המקור הקובע.