הוראת קבע ב API - יצירת הוראת קבע במערכת קארדקום - Direct Debit Api
ממשק API להוראת קבע מאפשר אוטומיזציה והשלמה למערכת הידנית.
יש להשתמש בממשקים רק אם יש צורך עסקי במערכת הוראת הקבע של קארדקום,
אפשרות יותר פשוטה ויותר גמישה היא שימוש באסימון ולבצע חיוב מחזורי ע"י פנייה של השרת שלכם למערכת אישורית זהב לחיוב.
על המתכנת יש לקרוא את 2 האפשרויות ולראות איזה ממשק כדאי לפתוח לפי דרישות בית העסק .
יש לבחור מערכת אחת לניהול הוראת קבע של הלקוח.
מתי כדאי להשתמש בממשקים במערכת הוראת קבע ב API :
גיוס הלקוחות מתבצע גם באופן ידני ע"י אנשים.
מוצרים רבים : ומחיר שונה לכול מוצר.
הנחות : ניתן מבחינה עסקית לתת הנחות ללקוחות.
גמישות מרבית בניהול הגביה וחייבים - כול לקוח חשוב ישי לטפל בו ידני במידה ויש חוב.
מערכת פחות גמישה לשינוים -> מנוהל ומתוחזק ע"י קארדקום בע"מ רק שינויים שמתאימים לכלל המשתמשים יכנסו למערכת.
ראו מאמר שמסביר כיצד לעבוד ידני עם מערכת הוראת הקבע, כל מה שרואים בידני ניתן להעביר בממשק.
יש ללמוד את המערכת הידנית (בכללי ) לפני התחלת פיתוח הממשקים : הוראת קבע ידני : הקמת הוראת קבע באשראי
מתי כדאי להשתמש ב אסימונים + פרופיל נמוך : (נפוץ)
גיוס הלקוחות מתבצע באופן אוטומטי.
שליטה מלאה מהמערכות שלך לעלות כול מוצר
אין התערבות אנושית בלקוחות חייבים - לא שילם נסגר המוצר הנמכר אוטומטי.
מערכת גמישה מאוד לשינוים -> מנוהל ומתוחזק על-ידי המפתח שלכם , המתכנת יוצר אסימון ומחליט בצד שלו מתי לחייב ומה לעשות דברים נוספים בהתאם .
ממשקים API קוד פתוח לפתיחת דף תשלום (פרופיל נמוך)
אם הוחלט לעבוד עם הוראת קבע ב API של קארדקום ראה שלבים אלה :
שלב 1 :
יש לבצע עסקת פרופיל נמוך(redirect / iframe ) של יצירת אסימון בלבד או חיוב ויצירת אסימון בכדי שפרטי האשראי ישמרו במערכת לפי מאמר : (Operation: ChargeAndCreateToken / CreateTokenOnly)
שלב 2:
יש לשלוח בקשה לביצוע חיוב מחזורי לעסקה שבוצעה. שם לב !
שדות החובה הם בהוספה בלבד! בעדכון יש לשלוח רק את השדות שרוצים לעדכן.
כתובת Name to Value לביצוע POST
https://secure.cardcom.solutions/interface/RecurringPayment.aspx
* התשובה המתקבלת היא במבנה :Name=Value&Name2=Value2&Name3=Value3.
* לצורך בדיקות בלבד אפשר לפנות ב GET.
*בפרודקשיין יש לפנות במתודת POST .
(יותר מאובטח , ניתן לחפש יותר טוב בלוגים קריאות , ניתן לשלוח סטרינג ארוך לעומת GET שיכול להישבר באמצע)
מקרא:
פרמטר אדום - חובה
פרמטר מודגש - מומלץ
פרמטר לא אדום ולא מודגש - אופציונלי
טבלת פרמטרים :
מס | פרמטר | ערכים אפשריים לדוגמא | תיאור |
1 | TerminalNumber | 1000 | מספר הטרמינל הפנימי (לא שבא) שבו נוצר האסימון או מסוף שעליו נוצר הקוד פרופיל נמוך של עסקה ראשונית |
2 | RecurringPayments.ChargeInTerminal | 1001 | מספר מסוף המחייב בהוראת קבע (ללא CVV) כאשר לא מועבר פרמטר זה, המסוף המחייב להו"ק יקבע לפי הגדרה בתפריט המערכת: [ הגדרות > 6. הוראת קבע > 1. הגדרות כלליות ]. |
3 | UserName | test2025 | שם משתמש ממשקים API user name |
4 | codepage (חובה) | 65001 | קידוד עברית - unicode |
5 | Operation | NewAndUpdate - הוסף חדש אם קיים עדכן. | NewAndUpdate - הוסף לקוח ואו/ הוראה לחיוב חדשה. אם לקוח לא נמצא ייוצר לקוח חדש. למשתמש גם להוספה של הוראה חדשה ללקוח קיים על ידי העברה מזהה יחודי לקוח AccountId Update - עדכון בלבד. אם לקוח / הוראה לחיוב לא נמצא תוחזר שגיאה.
**בעדכון הוראה ללקוח קיים יש להעביר את פרמטר מס' 27 בטבלה כאשר ה VALUE הוא מס' ההוראה שרוצים לעדכן |
6 | LowProfileDealGuid | 72183f28-75fa-404e-b5de-5a1a5287f094 | קוד הפרופיל נמוך של עסקת החיוב הראשונה של הלקוח החדש שחוייב בפרופיל נמוך (דרך פרמטר זה נלקח הפרטי אשראי של הלקוח) *במקרה של יצירת הו"ק מ-0 צריך להעביר פרמטר CreditCard.Token או CreditCard.Number במקום הפרמטר הזה. פרטים מופיעים בהמשך המדריך בטבלה של "פרטי כרטיס אשראי"* |
7 | Account.AccountId | 1000 | מזהה יחודי של הלקוח בקארדקום- יש להעביר בעדכון או בהוספת הו"ק ללקוח קיים. |
8 | Account.CompanyName | test company | שם הלקוח / שם החברה שעליה תצא החשבונית |
9 | Account.RegisteredBusinessNumber | 040617649 | מספר ח.פ / עוסק מורשה / ת.ז לקוח (מומלץ להעביר) 1 - Account.AccountId
|
10 | Account.SiteUniqueId | 120 | מספר לקוח ייחודי במערכת שלכם. |
11 | Account.ForeignAccountNumber | 12avx11 | מספר לקוח למערכת הנהלת חשבונית חיצונית |
12 | Account.FirstName | eli | שם פרטי. |
13 | Account.City | holon | מקום / עיר |
14 | Account.Street1 | street | כתובת שורה 1 (רחוב) |
15 | Account.Street2 | street 2 | כתובת שורה 2 (רחוב) |
16 | Account.ZipCode | 1234567 | מיקוד |
17 | Account.PhLine | 034723456 | טלפון נייח |
18 | Account.PhMobile | 0521122334 | טלפון נייד |
19 | Account.Email | כתובת דואר אלקטרוני - Email | |
20 | Account.VatFree | true/false | הקמת לקוח ללא מע"מ (ללקוחות חו"ל/ אילת) |
21 | Account.IsDocumentLangEnglish | true/false | שפת מסמך שיופק ללקוח באנגלית (ללקוחות חו"ל) |
22 | Account.Comments | "לקוח שילם במזומן בסוף" | הערות לחשבון הלקוח |
23 | Account.ContactName | avi | שם איש קשר |
24 | Account.DontCheckForDuplicate | true/fasle - במידה ב "true" תמיד יתוסף לקוח חדש ולא יבוצע בדיקת כפילויות | האם לא לבצע בדיקה של כפילויות לקוח ותמיד לפתוח כרטיס לקוח חדש בעת הוספת הוראת קבע. |
25 | RecurringPayments.DepartmentId | 1 | מספר מחלקה להוראת קבע https://secure.cardcom.solutions/Accounts/Tables/DepartmentsList.aspx הגדרות > 6 >1 |
26 | RecurringPayments.TimeIntervalId | 1 | מספר מחזור החיוב : |
27 | RecurringPayments.RecurringId | 2000 | מספר ההוראה לחיוב שרוצים לעדכן (במצב עידכון בלבד) |
28 | RecurringPayments.InternalDecription | ׳׳קורס השתלמות׳׳ | תאור שם ההוראה לחיוב |
29 | RecurringPayments.NextDateToBill | פורמט : dd/MM/yyyy לדוגמא : 01/12/2019 | תאריך הבא לתחילת החיוב בהוראת קבע |
30 | RecurringPayments.TotalNumOfBills | 999999 > ללא סוף (מנוי) | מספר החיובים בהוראת הקבע, כמה חודשים המערכת תחייב . קריטי: שימו לב שבמצב עדכון הו"ק הפרמטר הזה יאפס את כמות החיובים שחוייבו!!! |
31 | RecurringPayments.FinalDebitCoinId | 1 - שקל | מטבע לחיוב בהוראת קבע |
32 | RecurringPayments.ReturnValue | 1234 | ערך החזרה שנשלח (מתאים למס' הזמנה במערכת צד ג' ) |
33 | RecurringPayments.IsActive | false - לא יבוצע חיוב | במצב עידכון בלבד : להפוך את ההוראת למצב לא פעיל |
34 | RecurringPayments.DocTypeToCreate | 1 - חשבונית מס קבלה | סוג המסמך להפקה. - אם לא מעבירים סוג המסמך נקבע ע"י הגדרות המסוף בבריית מחדל. |
35 | RecurringPayments.FlexItem.InvoiceDescription | "קורס א תשלומים בהוראת קבע " | תאור לחשבונית שתופק |
36 | RecurringPayments.FlexItem.Price | 100 | המחיר לחיוב בהוראת הקבע *חודשי* (כמה הלקוח ישלם כל חודש) |
37 | RecurringPayments.FlexItem.IsPriceIncludeVat | true / false | מחיר פריט עם/בלי מע"מ true - הלקוח יחויב את הסכום המעובר והמע"מ יחולץ מהמסכם.( 100 יהיה 100 כולל מע"מ) |
38 | RecurringPayments.FlexItem.ProductId |
| מקט לפריט |
39 | RecurringPayments.FlexItem.LinkToId | 5 | קוד מט"ח / הצמדה לפי מה שמוגדר במערכת. בשימוש בהצמדה למדד מותאם אישית יש להעביר את קוד המדד שיצרתם במערכת. (הטבלה אשר מכילה את הקוד נמצא במערכת קארדקום - הגדרות -> 6. הוראות קבע -> 7. מדד / מט"ח ) **לאחר ההגדרה, על בית העסק לתחזק את המדד ידנית מהמערכת, שינוי המדד ישפיע אוטו' באופן ישיר על הוראות הקבע שמוצמדות לאותו מדד. |
40 | RecurringPayments.FlexItem.IsLinkTo | true / false | האם ההו"ק מוצמד למדד או לא. |
41 | RecurringPayments.FlexItem.OpenRateForLinkTo | 30 | שער מדד פתיחה, אם לא מועבר (מוגדר) המערכת תשתמש במדד בסיס ברירת מחדל |
42 | RecurringPayments.IsPrintNumOfPayments | true / false | האם להדפיס את מספר התשלומים בחשבונית - כמו בסמך ידני. |
43 | RecurringPayments.IsPrintBillMonth | true / false | האם להדפיס את חודש החיוב - כמו במסך ידני. |
44 | RecurringPayments.IsInvoiceCreate | true / false | מומלץ לא להעביר , יקבע ידני על ידי המערכת והגדרות משתמש האם ליצור מסמך לחיוב זה. |
בקשה לדוגמא ב GET לבדיקות:
https://secure.cardcom.solutions/interface/RecurringPayment.aspx?TerminalNumber=1000&RecurringPayments.ChargeInTerminal=1000&UserName=test9611&codepage=65001&Operation=NewAndUpdate&LowProfileDealGuid=6cc64545-5534-46ac-9476-9455cdcbd68f&Account.CompanyName=testName&Account.RegisteredBusinessNumber=012345678&RecurringPayments.InternalDecription=קורס&RecurringPayments.NextDateToBill=25/02/2024&RecurringPayments.TotalNumOfBills=99999& RecurringPayments.FinalDebitCoinId=1&RecurringPayments.ReturnValue=order1234&RecurringPayments.
FlexItem.InvoiceDescription=קורס&RecurringPayments.FlexItem.Price=100
תשובה לדוגמא:
ResponseCode=0&Description=OK&TotalRecurring=1&IsNewAccount=True&AccountId=9917&Recurring0.RecurringId=33244&Recurring0.ReturnValue=order1234&Recurring0.IsNewRecurring=true
דוגמא לפנייה ב POST דרך Postman
ביצירת הוראת קבע בAPI - חשוב להעביר פרמטרים של אמצעי תשלום כרטיס אשראי\פרטי חשבון בנק
פרטי כרטיס אשראי:
מס | פרמטר | ערכים אפשריים לדוגמא | תיאור |
1 | CreditCard.CardOwnerName | אלי כהן | שם בעל הכרטיס |
2 | CreditCard.CardOwnerId | 123456789 | ת''ז בעל הכרטיס |
3 | CreditCard.Year | 26 | שנה YY |
4 | CreditCard.Month | 11 | חודש MM |
5 | CreditCard.Token Or CreditCard.Number | 4cf8e168-261e-4613-8d20-000/5326-XXXX-XXXX-XXXX | טוקן כרטיס או מספר כרטיס אשראי |
הוראת קבע בנקאית - מס''ב
מס | פרמטר | ערכים אפשריים לדוגמא | תיאור |
1 | BankInfo.Bank | 1 ( INT ) | מספר בנק |
2 | BankInfo.Branch | 123 (INT ) | מספר סניף |
3 | BankInfo.AccountNumber | 1233456 ( LONG) | מספר חשבון בנק |
4 | BankInfo.Description | מחרוזה 50 . | הערות כלליות |
לאחר היצירה של ההוראת קבע - מומלץ להיכנס למערכת של בית העסק ולבדוק שאכן נוצר לקוח + הוראה לחיוב, מצורף מדריך : הקמת הוראת קבע באשראי.
שלב 3:
מצורף מדריך נוסף להגדרת קבלת דיווח ל Webhook על סטטוס ההוראות במקרה של שינויים ->
הוראת קבע בנקאית :
אין העביר את פרמטר LowProfileDealGuid ואין צורך לקבל את פרטי כרטיס האשראי מהלקוח. יש להעביר את פרטי חשבון הבנק ופרטי הלקוח ופרטי החיוב בפנייה אחת.
שם לב ! לחיוב הלקוח דרך חשבון בנק יש לקבל את אישור הלקוח ואת אישור הבנק במסמך חתום. (הלקוח הולך אל הבנק והבנק חותם על אישור לגביה מהחשבון רק לחברה שלכם)
מספר | פרמטר | ערכים אפשריים לדוגמא | תיאור |
1 | BankInfo.Bank | 1 | מספר בנק - int |
2 | BankInfo.Branch | 123 | מספר סניף - int |
3 | BankInfo.AccountNumber | 332255 | מספר חשבון בנק - long |
4 | BankInfo.Description | הערות לחשבון בנק | הערות כלליות - 50 תווים |
פרטי התשובה המתקבלת
מספר | פרמטר | ערכים אפשריים לדוגמא | תיאור |
1 | ResponseCode | 0 | 0 הפעולה הצליחה |
2 | Description | OK | תיאור התשובה |
3 | TotalRecurring | 1 | מספר הוראות שנוצרו |
4 | IsNewAccount | True | האם נוצר הוראה חדשה |
5 | AccountId | 1001 | מספר הלקוח שנוצר ב קארדקום |
6 | Recurring0.RecurringId | 9460 | מספר ההוראה |
7 | Recurring0.ReturnValue | 1234 | ערך משתמש להחזרה |
8 | Recurring0.IsNewRecurring | true | האם מנוצר הוראה חדשה |
בנוסף מצורפים קודי דוגמא בתחתית המאמר :
הוספת הו׳׳ק חדשה/ AddRecurringPayment | AddRecurringPayment.php.txt |
ביטול הו׳׳ק קיימת / DisableRecurringPayment | DisableRecurringPayment.php.txt |
עדכון הו׳׳ק קיימת / UpdateRecurringPayment | UpdateRecurringPayment.php.txt |
יש ליצור קשר עם התמיכה לקבלת שם משתמש לבדיקות.
לאחר האינטגרציה - חובה על המתכנת לעשות טסט אמיתי לבית העסק כולל פתיחה של הוראה ובדיקה שהוקמה במערכת קארדקום כמו שצריך +מעקב שזה אכן מחויב תקין לאחר חודש .