---

🧾 מדריך מלא – Hosted Fields של PayPlus

לכניסה למדריך באנגלית והדוקומנטציה שלנו לחצו כאן

גרסה: v1.0
תאריך עדכון: ינואר 2026

---

1️⃣ מבוא

Hosted Fields מאפשרים לך לבנות דף תשלום משלך באתר מבלי להשתמש בדפי תשלום חיצוניים.

• שדות רגישים (כרטיס אשראי, CVV, תוקף) מוטענים ב-iframe מאובטח של PayPlus.

• השדות הנוספים (שם, טלפון, כתובת) נשארים אצלך באתר.

• מאפשר שליטה מלאה בעיצוב וחוויית משתמש מותאמת אישית.

דרישות בסיסיות

כדי להריץ את הדמו:

1. פרטי API / credentials מבית PayPlus עם הרשאת API.

2. שרת עם SSL ותמיכה ב-PHP 7.4 או יותר (אפשר להשתמש בשפות שרת אחרות במקום PHP).

3. ידע ב-HTML, JS ו-NPM (או כלי אחר שמאפשר קריאת API).

---

2️⃣ קבצים עיקריים בדמו

הדמו מגיע עם 3 קבצים עיקריים:

קובץ	תיאור
payment.php	יוצר את בקשת דף התשלום (Payment Page) עם פרטי API שלך. צריך למלא credentials, כתובת חזרה (success, failure, cancel) ופרטי דף.
index.html	מבנה דף התשלום – כולל עיצוב בסיסי (Bootstrap בדמו).
script.js	יוזם את Hosted Fields, ממפה את השדות ומגדיר callbacks / אירועים.

---

3️⃣ התקנה

1. הורד או שיבוט את הרפוזיטורי לשרת שלך.

2. ערוך את payment.php עם credentials וכתובות החזרה שלך.

3. התקן תלותיות (Dependencies) עם:

npm i

4. גש לדף הראשי (index.html) – תראה את הטופס עם השדות.

---

4️⃣ תהליך העבודה – Overview

1. הלקוח מבצע בקשה ל-payment.php.

2. השרת מחזיר את ה-hosted_fields_uuid ו-page_request_uid.

3. הדפדפן טוען את index.html ומאתחל את הפלאגין (script.js) עם כל השדות.

4. השדות הרגישים מוטענים כ-iframe מאובטח. השדות הנוספים נשארים אצלך.

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

---

5️⃣ הפעלת Hosted Fields (script.js)

// יצירת אובייקט Hosted Fields
const hf = new PayPlusHostedFieldsDom();

// מיפוי השדות הראשיים (Hosted Fields)
hf.SetMainFields({
	cc: { elmSelector: "#cc", wrapperElmSelector: "#cc-wrapper" },
	expiryy: { elmSelector: "#expiryy", wrapperElmSelector: ".expiry-wrapper" },
	expirym: { elmSelector: "#expirym", wrapperElmSelector: ".expiry-wrapper" },
	expiry: { elmSelector: "#expiry", wrapperElmSelector: ".expiry-wrapper-full" },
	cvv: { elmSelector: "#cvv", wrapperElmSelector: "#cvv-wrapper" }
});

💡 הערות:

• cc – מספר כרטיס.

• cvv – קוד אבטחה, שולט על כל התהליך.

• expiry / expirym / expiryy – תוקף הכרטיס. ניתן למפות חודש/שנה בנפרד או שדה אחד משולב.

---

5.1 שדות נוספים (Non-hosted Fields)

hf
.AddField("card_holder_id", "#id-number", "#id-number-wrapper")
.AddField("card_holder_name", "#card-holder-name", "#card-holder-name")
.AddField("card_holder_phone", ".card-holder-phone", ".card-holder-phone-wrapper")
.AddField("card_holder_phone_prefix", ".card-holder-phone-prefix", ".card-holder-phone-prefix-wrapper")
.AddField("customer_name", "[name=customer_name]", ".customer_name-wrapper")
.AddField("vat_number", "[name=customer_id]", ".customer_id-wrapper")
.AddField("phone", "[name=phone]", ".phone-wrapper")
.AddField("email", "[name=email]", ".email-wrapper")
.AddField("contact_address", "[name=address]", ".address-wrapper")
.AddField("contact_country", "[name=country]", ".country-wrapper")
.AddField("custom_invoice_name", "#invoice-name", "#invoice-name-wrapper")
.AddField("notes", "[name=notes]", ".notes-wrapper")
.SetRecaptcha('#recaptcha');

💡 הערות:

• שדות אלו נשארים אצלך באתר.

• מומלץ למפות את כל השדות גם אם חלקם לא חובה – קל להוסיף בעתיד.

• .SetRecaptcha('#recaptcha') מחליף את האלמנט ב-iframe reCAPTCHA אם מוגדר.

---

5.2 יצירת דף התשלום

$.get("payment.php", async (resp) => {
	if (resp.results.status == "success") {
		try {
			await hf.CreatePaymentPage({
				hosted_fields_uuid: resp.data.hosted_fields_uuid,
				page_request_uid: resp.data.page_request_uid,
				origin: 'https://restapidev.payplus.co.il'
			});
		} catch (error) {
			alert(error);
		}
		hf.InitPaymentPage.then((data) => {
			$("#create-payment-form").hide();
			$("#payment-form").show();
		});
	} else {
		alert(resp.results.message);
	}
});

---

5.3 הגשת התשלום

$("#submit-payment").on("click", () => {
  hf.SubmitPayment();
});

---

6️⃣ אירועים (Events)

hf.Upon("pp_pageExpired", (e) => { /* דף פג תוקף */ });
hf.Upon("pp_noAttemptedRemaining", (e) => { /* אין ניסיונות נוספים */ });
hf.Upon("pp_responseFromServer", (e) => { /* תשובה מהשרת */ });
hf.Upon("pp_submitProcess", (e) => { /* תהליך הגשה פעיל */ });
hf.Upon("pp_ccTypeChange", (e) => { /* שינוי סוג כרטיס */ });

💡 הערות:

• מאפשרת טיפול מותאם אישית בהצלחה/כשל/טעינה.

• ניתן להוסיף פעולות כמו הצגת הודעת תודה או טופס כשלון.

---

7️⃣ עדכון 2024-08-12 – 3D Secure

• חובה: card_holder_name + card_holder_phone

• card_holder_phone_prefix – מאפשר קידומת למדינה, חובה רק אם לא ממירים את המספר ידנית.

• דוגמא: ישראלי 052-123456 → נשלח כ-97252123456.

---

8️⃣ יתרונות Hosted Fields

• UX מותאם אישית לחלוטין

• שליטה מלאה בעיצוב ובזרימת התשלום

• אבטחה מלאה – הנתונים הרגישים לא עוברים דרך השרת שלך

• תמיכה ב-3D Secure

---

9️⃣ מתי להשתמש Hosted Fields?

• מוצרי SaaS או מערכות מורכבות

• דרישה לחוויית תשלום מותאמת אישית - למרות שבדרך כלל ה-iframe שלנו מספק לחלוטין

• צוות מפתח שמוכן לתחזק Frontend + Backend

⚠️ אתרים פשוטים / חנויות קטנות – עדיף להשתמש ב-Payment Link /Iframe/ Redirect.

---

10️⃣ טבלה מסכמת – Hosted Fields מול Redirect

נושא	Redirect / Link	Hosted Fields
עיצוב	מוגבל ל-PayPlus	מותאם אישית
UX	סטנדרטית	מותאמת אישית
מורכבות	נמוכה	גבוהה (Backend + Frontend)
אבטחה	מאובטח	מאובטח (iframe לשדות רגישים)
קהל יעד	רוב העסקים	SaaS / מערכות מורכבות

---

•