בונים עם Claude?
מחברים את התשלומים עם תקבול

איזה חיבור ל־Claude אתם צריכים?

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

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

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

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

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

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

איך נותנים ל־Claude את ההקשר הנכון?

לפני שמבקשים ״תוסיף סליקה״, הגדירו מה כבר קיים: שפת השרת, בסיס הנתונים, ניהול המשתמשים, טבלת ההזמנות וסביבת האירוח. Claude Code צריך לבדוק את הפרויקט ולהשתמש במבנה הקיים, בלי להניח שמדובר דווקא ב־React או בשרת מסוג מסוים.

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

בקשו קובץ .env.example עם שמות משתנים וערכים ריקים, והוראות הגדרה לסביבת האירוח. את המפתחות עצמם הגדירו באופן פרטי; אין לבקש מ־Claude להדפיס אותם או להכניס אותם למאגר הקוד.

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}

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

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

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. התאימו את גבולות הגובה לעיצוב ובדקו שאינם מסתירים שדות. אם מקור ההודעות משתנה בסביבה מאושרת, הגדירו כתובת מדויקת לאחר בדיקה; אל תחליפו את האימות בקבלה של כל דומיין.

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"
}

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

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

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

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

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

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

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

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

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

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

Implement Takbull payments in this existing project using Claude Code.
First inspect the repository: framework, backend runtime, database,
authentication, order model, deployment configuration and existing tests.
Use the project's architecture and conventions. Do not assume React,
Next.js, Supabase or any other stack unless the repository uses it.
If this is a chat without repository access, ask for the relevant files
and return file-by-file code and setup instructions without claiming
that changes were applied or tests were run.
Use the official documentation: https://api.takbull.co.il/ApiDocs
If you cannot read it, ask for the relevant sections instead of guessing.
For normal website checkout, call Takbull from the backend; MCP and the
Anthropic API are not required in the runtime payment flow.
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.

Deliverables:
- Implement code in the appropriate existing project files.
- Include necessary database migrations and an .env.example with no secrets.
- Document server-only secrets, callback URLs and deployment steps.
- Add meaningful tests using the project's test framework; distinguish
  mocked responses from real sandbox results.
- Keep unresolved approval status mapping explicit and fail closed.
- Do not execute real charges, refunds or subscription cancellations
  as a development test. Use the approved sandbox configuration.
- Summarize changed files, executed checks and missing configuration.

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.

רוצים להפעיל תקבול מתוך שיחה ב־Claude?

זהו מסלול פיתוח נוסף. בונים שרת MCP שמציג ל־Claude כלים מוגדרים, ומתרגם אותם לבקשות REST לשרת תקבול. מחבר מותאם ב־Claude מתחבר לשרת MCP; שרת ה־MCP הוא שמחזיק את החיבור העסקי לתקבול.

מתחילים בשני כלים ממוקדים

• create_payment_link — יצירת בקשת תשלום להזמנה קיימת והחזרת קישור לדף תקבול.
• get_payment_status — הצגת סטטוס מאומת של הזמנה מורשית.

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

איך מחברים בפועל?

1. מפתחים ופורסים שרת MCP עם אימות משתמשים ובדיקת הרשאות להזמנות ולעסקים.
2. מגדירים בצד השרת את מפתחות תקבול ואת כתובות החזרה וה־IPN.
3. מוסיפים ב־Claude מחבר מותאם עם כתובת שרת ה־MCP שפרסתם, בהתאם להרשאות החשבון ולהנחיות Claude.
4. מבצעים בדיקה עם משתמש מורשה, הזמנת בדיקה ותוצאה מאומתת.

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

פרומפט נוסף לבניית מחבר MCP

השתמשו בו רק אם המטרה היא הפעלת כלים מתוך Claude. לחיבור סליקה רגיל באתר מספיק הפרומפט הקודם.

Build a remote MCP adapter for Takbull, not a new payment processor.
Read https://api.takbull.co.il/ApiDocs and the current official MCP SDK
and Claude connector documentation before implementing transport/auth.
Do not assume Takbull exposes an existing MCP endpoint.

Expose only two initial tools (these are our names, NOT Takbull endpoints):
1. create_payment_link(local_order_id)
2. get_payment_status(local_order_id)

Authenticate MCP users and authorize every tool call for the correct
merchant and order. Resolve merchant credentials server-side from the
verified identity; never let the model choose arbitrary credentials.
Load totals, currency and customer/order data from trusted server data.
Keep Takbull API_Key/API_Secret in the backend secret store.
For create_payment_link, show order, amount and currency for explicit
user confirmation using a backend-enforced approval workflow before
creating a real payment request. Make retries safe using our own stored
request state; do not invent a provider idempotency header.

Create the payment order with the documented
POST /api/ExtranalAPI/GetTakbullPaymentPageRedirectUrl, using redirect
flow (DisplayType="redirect", PostProcessMethod="0"), configured callback
URLs and server-derived order details. Return only the hosted payment URL
and minimal order metadata. The customer pays on the Takbull page.

Keep the GET payment IPN endpoint separate from the MCP endpoint.
Validate IPN using POST /api/ExtranalAPI/ValidateNotification.
Map payment approval only from documented/confirmed response semantics.
For get_payment_status, use the verified backend state and refresh through
the documented API as needed. Never treat link creation as payment.
Do not return full card tokens, API keys or unnecessary personal data.
Do not expose arbitrary HTTP requests, refunds, saved-token charges,
subscription cancellation or account creation in this initial version.

Deliver the adapter, deployment and authentication configuration,
tests, and instructions for adding the actual deployed MCP URL to Claude.
Do not invent an MCP URL or claim that a connector is already installed.

הנחיות החיבור העדכניות מופיעות ב־תיעוד המחברים המותאמים של Claude.

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

שאלות נפוצות על חיבור תקבול ל־Claude