חיבור סליקה ותשלום להזמנה

שמרו את תהליך ההזמנה שלכם

הדפדפן מציג סל קניות וכפתור תשלום. הכפתור פונה לשרת שלכם עם מזהה הזמנה. השרת מאמת שהמשתמש מורשה לעסק, טוען את ההזמנה ושורותיה ומחשב את הסכום. הוא פונה ל־Daily עם מפתח העסק או עם מפתח Platform ראשי ו־X-Daily-Business-ID. רק approvalUrl חוזר לדפדפן.

לכל הזמנה שמרו את מזהה העסק שלכם ואת businessId, customerId, documentId, paymentRequestId של Daily. מזהה בקשת תשלום שונה ממזהה תשלום שנרשם במסמך. שני מסמכים של אותו לקוח נשמרים בנפרד; אין לבחור את המסמך האחרון של הלקוח.

הכינו את העסק לסליקה

קריאת מצב דורשת business:read; שינוי חיבור והגדרות עסק דורש integrations:write. 201 מאשר שה־API טיפל בפעולה; הוא אינו אישור שהעסק מוכן לסליקה.

סליקת אשראי

1. קראו GET /integrations/payme. בדקו paymentReady, approvalStatus ו־missingApprovalFields.
2. השלימו את פרטי העסק והבנק ב־PATCH /business/settings. השדות הם camelCase; bankDetails משתמש ב־bankCode, branchNumber, accountNumber ו־beneficiaryName. שלחו את הפרטים האמיתיים של העסק. המפרט כולל גם bankAccounts, פרטי SWIFT ויתר ההגדרות.
3. אם נדרש אישור, שלחו POST /integrations/payme/approval-request עם planCode שהוא minimum_109_0_8 או pay_as_you_go_0_95. missing_fields דורש השלמת השדות שבתשובה; pending_approval דורש המתנה ובירור מצב, ולא שליחה חוזרת ללא צורך.
4. להקמת מוכר שלחו POST /integrations/payme/sellers. פרטים זמינים מתמלאים מהעסק; השלימו את החסרים לפי config.sellerOnboarding.requiredFields, missingFields ו־fieldErrors שבתשובה. sellerSocialId ו־sellerIncCode, אם נשלחו, חייבים להתאים לאיש הקשר ולעסק הרשומים.
5. status=connected ו־config.paymentReady=true מאפשרים המשך. missing_fields דורש השלמת פרטים. רק fallbackAvailable=true מוביל למסלול POST /integrations/payme/onboarding והעברת redirectUrl לדפדפן.

אין להריץ onboarding אחרי הקמת מוכר מוצלחת: זו חלופה שמשנה את מצב החיבור. חזרה אוטומטית במסלול ההשלמה החלופי תלויה בתמיכת חברת הסליקה; יש לבדוק את מצב החיבור ב־API. אם כבר יש לעסק מזהה מוכר מאומת, אפשר להשתמש ב־POST /integrations/payme/connect עם sellerPaymeId במקום להקים מוכר נוסף.

PATCH /integrations/payme/settings עם defaultMaxInstallments קובע 1, 3, 6, 9 או 12 תשלומים לבקשות חדשות. עמוד קיים שלא שולם ושאומת נשאר בתנאיו המקוריים; שינוי ברירת מחדל אינו סיבה לבטל אותו או לטעון שהתשלום כבר התקבל.

PayPal

שלחו POST /integrations/paypal/onboarding ללא גוף, פתחו בדפדפן את data.redirectUrl, ולאחר הסכמת העסק קראו GET /integrations/paypal. רק paymentReady=true מאפשר התחלת סליקה. עמוד חזרה או status=CONNECTED לבדם אינם ראיה למוכנות או לתשלום.

צרו לקוח ומסמך מההזמנה בשרת

צרו לקוח דרך POST /customers עם customers:write ושמרו את data.id לפני המשך. לדוגמה:

{
  "name": "לקוח הדגמה",
  "email": "buyer@merchant.daily.test",
  "currency": "ILS"
}

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

למסמך פתוח לתשלום אפשר להשתמש ב־TRANSACTION_INVOICE דרך POST /documents, עם documents:write. שמרו UUID ב־client_request_id וגוף מסמך יציב לפני השליחה הראשונה. בדוגמה המחיר הוא ביחידות מטבע ראשיות והפרטים סינתטיים:

{
  "document_type": "TRANSACTION_INVOICE",
  "counterparty_id": "44f34dad-a427-4c65-ae26-b0a43f8f65f7",
  "client_request_id": "71511e2a-3380-4783-8f2c-fb9bbdd1ef7f",
  "date": "2026-10-13",
  "currency": "ILS",
  "items": [
    {
      "product_name": "שירות הדגמה",
      "quantity": "1.000",
      "unit_price": "125.50",
      "vat_included": true
    }
  ]
}

בחרו את סוג המסמך, המע״מ ותנאי העסק בהתאם להזמנה האמיתית. שמרו את data.id וודאו שסכום המסמך שנוצר תואם להזמנה; אפשר לקרוא GET /documents/{id} עם documents:read. אין ליצור קבלה או לסמן מסמך כשולם לפני אימות כסף. יצירה חוזרת עם אותו client_request_id מחזירה את המסמך המקורי ואינה מעדכנת את תוכנו.

צרו קישור מהמסמך וחברו אותו לכפתור

אחרי שיש לכם מסמך מאומת, שלחו POST /payments/payme/payment-links או POST /payments/paypal/payment-links עם payments:write וגוף camelCase:

{
  "documentId": "813d0b3f-ab6c-43d4-9173-8f224566ba2f"
}

Daily מחשבת את היתרה מהמסמך. אין שדה סכום בבקשה זו. הקוד הבא מתאים לפעולת התשלום בשרת שלכם; המיפוי והנעילה נשמרים בבסיס הנתונים שלכם.

// The application loads these values from its authenticated order and secret store.
declare const savedDocumentId: string;
declare const businessKey: string;
declare const providerKey: 'payme' | 'paypal';
declare const saveOrderPaymentMapping: (requestId: string, documentId: string) => Promise<void>;

const apiBase = process.env.DAILY_API_BASE_URL;
if (!apiBase) throw new Error('חסרה כתובת החיבור לדיילי');
const response = await fetch(`${apiBase}/payments/${providerKey}/payment-links`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${businessKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ documentId: savedDocumentId }),
  signal: AbortSignal.timeout(30000),
});
const result = await response.json();
if (!response.ok) throw new Error(`Daily ${response.status}: ${result.error?.code}; ${result.request_id}`);
const payment = result.data;
if (payment.documentId !== savedDocumentId || !payment.approvalUrl) throw new Error('פרטי בקשת התשלום אינם תואמים');
await saveOrderPaymentMapping(payment.id, savedDocumentId);
// Return only this object to the browser; redirect the existing payment button to its URL.
const browserResult = { paymentUrl: payment.approvalUrl };

בתשובה: id מזהה את בקשת התשלום, documentId את המסמך, businessId את העסק, amount הוא מחרוזת עשרונית, currency הוא המטבע, ו־approvalUrl הוא כתובת התשלום. קיימים גם status, expiresAt, paidAt ופרטי שיוך נוספים המוגדרים במפרט. הדפדפן אינו צריך לקבל מזהי ספק או סודות.

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

עדכנו את ההזמנה לפי כסף מאומת

הגדירו webhook חתום במפתח הראשי. אירוע payment.updated מכיל ב־data.id את בקשת התשלום ששמרתם. אתרו את ההזמנה לפי businessId ומזהה הבקשה, בדקו סכום ומטבע, ועבדו באותה transaction עם מניעת כפילות.

קבלה או PDF עשויים להתעכב אחרי CAPTURED. נסו שוב את קריאת המסמך; אין לחייב שוב כדי להפיק קבלה. גם תשלום לאחת משתי חשבוניות של אותו לקוח אינו משלם את האחרת.

השלימו מידע כאשר עדכון התעכב

עם המפתח הראשי ו־platform:manage ו־payments:read, קראו GET /platform/businesses/{businessId} וחפשו את הבקשה ב־data.recentPayments לפי id. הרשימה מוגבלת לעשר האחרונות; היעדר בקשה בה אינו הוכחה לכישלון או לאי־תשלום. GET /payments הוא API של תשלומים שנרשמו במסמכים, עם מזהים אחרים ו־status=recorded; הוא אינו רשימת בקשות סליקה.

למסמך אפשר לקרוא GET /documents/{id} ולבדוק payment_status, סכומים וקשרים למסמכים נוספים; עברו על תשלומים שנרשמו בעזרת pagination אם נדרש. אין בחוזה הציבורי הנוכחי GET /payment-requests/{id} עם מפתח API. כאשר אירוע חסר והבקשה כבר אינה בעשר האחרונות, נדרש בירור של Daily לפני החלטה להתחיל חיוב נוסף.

409 payment_already_completed מחייב בירור והשלמת ההזמנה, לא בקשת תשלום חדשה. payme_payment_awaiting_confirmation או תוצאה לא ידועה אחרי timeout דורשים בירור; אין לייצר מסמך חדש, למחוק מזהה עסקה או להחליף ספק כדי לעקוף את המצב.