בניתם אתר, חנות או שירות ב־Lovable? חברו אליו תשלום באמצעות תקבול, הציגו דף סליקה בתוך האתר, ועדכנו את ההזמנה לאחר אימות התשלום בשרת.
iframe / Redirect · יצירת הזמנה · IPN · מסמכים אוטומטיים
טופס התשלום של תקבול בתוך חלון נגיש, עם אפשרות להפניה לדף התשלום.
הודעת IPN מאפשרת לשרת להמשיך לטפל בתוצאה בלי להסתמך על חזרת הלקוח.
שיוך הזמנות, הפקת מסמכים ואוטומציות בהתאם להגדרות החשבון ולצרכי העסק.
החיבור מורכב משלושה חלקים: ממשק התשלום באתר, שרת שיוצר הזמנה מול תקבול, ונקודת קצה שמקבלת עדכונים ומאמתת את העסקה.
API_Key ו־API_Secret. לקבלת פרטי סביבת בדיקות יש לפנות לתמיכת תקבול.שמרו אותם במנגנון הסודות של סביבת השרת. אין להטמיע מפתחות אמיתיים בקוד React, במשתני סביבה שנחשפים לדפדפן, בווידג׳ט Elementor או בפרומפט המועתק לצ׳אט.
תיעוד המקור לכל שמות השדות והפעולות: Takbull API Documentation.
כאשר הלקוח לוחץ על כפתור התשלום, האתר פונה לשרת שלכם. השרת מזהה את המשתמש, בודק את ההזמנה ומחשב את הסכום לפי הנתונים השמורים אצלו. אין לקבל את המחיר מהדפדפן כנתון סמכותי.
שלחו בקשת 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 עם מזהה חסר.
בנו את כתובת התשלום מתוך uniqId שהשרת קיבל, והעבירו אותה לממשק:
https://api.takbull.co.il/PaymentGateway?orderUniqId={uniqId}ב־Lovable בקשו ליצור Modal נגיש המכיל iframe עם המזהה takbull_iframe, כותרת תיאורית ו־allow="payment". אין ליצור באתר טופס עצמאי שאוסף מספר כרטיס או קוד אבטחה; פרטי הכרטיס מוזנים בדף התשלום של תקבול.
סגירת החלון אינה מבטלת בהכרח עסקה שכבר נשלחה. לאחר סגירה או ניסיון חוזר, בדקו את הסטטוס בשרת. אם בוחרים בזרימת Redirect, יש להתאים גם את DisplayType ואת PostProcessMethod; אין להניח שכל אמצעי התשלום מתנהגים באופן זהה בתוך 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 או פרמטר בכתובת החזרה.
תקבול שולחת עדכון לכתובת IPNAddress שהוגדרה בהזמנה. לפי התיעוד, עדכון התשלום מגיע בבקשת GET עם פרמטרים בכתובת, ובהם uniqId, order_reference, statusCode ו־transactionInternalNumber.
ה־IPN עשוי להגיע לפני הודעת הדפדפן או אחריה. השרת צריך לטפל בו גם כשהלקוח סגר את האתר, ולאמת את המצב מול תקבול.
POST לנתיב האימות, עם מפתחות API בכותרות.GetTransaction, לרבות המטבע.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.
כדי לבקש הפקת מסמך, השתמשו ב־CreateDocument=true, בחרו DocumentType מתאים, והעבירו Products ופרטי לקוח. לדוגמה, 320 הוא חשבונית מס קבלה ו־400 הוא קבלה. סוג המסמך חייב להתאים לעסק ולעסקה.
ודאו שסכומי הפריטים, הכמויות, ההנחות והמס תואמים לסכום ההזמנה. אם תקבול כבר מפיקה את המסמך כחלק מהתשלום, אל תוסיפו יצירת מסמך עצמאית ללא בדיקת כפילות.
ל־Bit מתועדת זרימה עם PaymentMethodType=21. במובייל יש להעביר IsMobile=true ולהשתמש ב־url המוחזר לפתיחת האפליקציה. לכן אין להציג במדריך הבטחה שכל התשלום תמיד נשאר בתוך החלון.
מנויים וחיוב טוקן דורשים תכנון נוסף של מועדי החיוב, שמירת הנתונים וטיפול בתוצאות. אין להניח שכל עסקה רגילה מחזירה טוקן לשימוש חוזר. זמינות אמצעי התשלום והאפשרויות תלויה בהגדרות ובהרשאות החשבון.
העתיקו את ההנחיה הבאה לפרויקט. היא מגדירה את זרימת העבודה ואת בדיקות האימות; את המפתחות והכתובות האמיתיות הגדירו בנפרד בסביבת השרת. יצירת הקוד באמצעות 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 כפול או מוקדם | אין אספקה כפולה, ואין תלות בסדר הגעת ההודעות. |
| סכום או מזהה לא תואם | ההזמנה אינה מסומנת כשולמה ונשלחת לבדיקה. |
| הודעה ממקור לא מורשה | המאזין מתעלם ממנה, גם אם היא נראית כמו הודעת הצלחה. |
| מובייל ומקלדת | הטופס שמיש, המיקוד נשמר, אין חיתוך שדות וניתן לסגור את החלון. |
| תקלה ברשת | מוצג מצב ברור ונבדק סטטוס לפני ניסיון תשלום נוסף. |
כן. ניתן לבנות חיבור באמצעות ה־API של תקבול, עם יצירת הזמנה בצד השרת, הצגת דף תשלום ואימות התוצאה. יש להגדיר בפרויקט את רכיבי השרת והנתונים הנדרשים.
לא. ה־iframe מציג את דף התשלום. נדרשים גם יצירת הזמנה בשרת, שמירת המזהים וקבלת IPN עם אימות מול תקבול.
אפשר להשתמש ב־iframe בתוך חלון באתר או בזרימת Redirect. יש להתאים את הזרימה לאמצעי התשלום ולמכשיר, ולבדוק אותה בפועל.
במנגנון הסודות של צד השרת בלבד. אין להכניס אותם לקוד הדפדפן, לתוכן העמוד או לקוד Elementor.
לאחר שהשרת אימת את תוצאת התשלום ושייך אותה להזמנה הצפויה. עד אז אפשר להציג הודעת בדיקה או המתנה.
כן, באמצעות הפרמטרים המתועדים להפקת מסמך, כולל CreateDocument, סוג מסמך ופריטי Products, ובהתאם להגדרות העסק.
פתחו חשבון תקבול, הגדירו את החיבור ובדקו את התהליך מקצה לקצה לפני העלייה לאוויר.
מבוסס על תיעוד ה־API של תקבול, שנבדק ב־11.11.2026. דוגמאות הקוד הן להמחשה ודורשות התאמה לפרויקט ובדיקת סביבת בדיקות. מבנה התגובות בתיעוד הוא המקור הקובע.