Tap On Phone דרך אפליקציית צד ג' SDK

מדריך זה מסביר כיצד משלבים סליקת Tap On Phone באפליקציית Android של צד ג', ומה נדרש לבדוק בכל שלב. הוא מפרט את תפקידי נציגי התמיכה ומפתחי בית העסק: הפרקים הראשונים מסבירים את התהליך והבדיקות, והנספח הטכני מפרט את הקריאות, השדות וההכנות באפליקציה.

הלקוח מצמיד כרטיס אשראי או ארנק דיגיטלי למכשיר הנייד התומך ב-NFC. האפליקציה משתמשת ב-SDK כדי לבצע את פעולת ה-TAP, ומעבירה את נתוני הפעולה ל-API של קארדקום לצורך עיבוד העסקה במערכת.

העיקרון המרכזי: נדרשים גם ביצוע העסקה מול ה-SDK וגם העברת הבקשה והתשובה לקארדקום באמצעות ProcessSDKTransaction. יש לבדוק את התוצאה של שני השלבים. תשובת הצלחה מה-SDK לבדה אינה מאשרת שהעסקה נקלטה במערכת קארדקום.

1. מה תפקידו של כל רכיב?

חשוב להבין: הפעולות registerDevice ו-performTransaction הן פעולות SDK בתוך אפליקציית Android. הפעולות PrepareDevice ו-ProcessSDKTransaction הן קריאות API לקארדקום. אין להחליף ביניהן.

2. מה נדרש לפני תחילת העבודה?

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

3. סדר הפעולות - מה מבצעים ומתי?

שלבים 1 ו-2 הם הכנה ורישום של המכשיר. אין צורך להפעיל אותם מחדש לפני כל עסקה כאשר הרישום עדיין תקף. שלבים 3 ו-4 שייכים לכל עסקה בנפרד.

אם מתקבל onRegisterNeeded, נדרש לחדש את הרישום: לבצע שוב PrepareDevice, אחריו registerDevice, ולשמור את נתוני ה-session החדשים. המסמך אינו מגדיר מדיניות לניסיון חוזר אוטומטי של העסקה.

4. הכנת המכשיר ורישומו

הכנת המכשיר - PrepareDevice

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

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

רישום מול ה-SDK - registerDevice

לאחר קבלת נתוני ההכנה, המפתח מפעיל את registerDevice עם TPN ו-MerchantCode. הצלחת PrepareDevice אינה משלימה לבדה את רישום המכשיר ב-SDK.

מפתח הרישום ותוקפו

• session_key הוא המפתח שה-SDK מספק לאחר רישום מוצלח. מעבירים אותו כ-sessionKey בעת ביצוע עסקה.
• session_date הוא זמן יצירת המפתח, במילישניות לפי המסמך.
• session_expire_time הוא נתון התפוגה, במילישניות לפי המסמך.

המסמך אינו מבהיר אם session_expire_time הוא מועד מוחלט או משך תוקף. אין להסיק נוסחת תפוגה מהשם בלבד; המפתח נדרש לאמת את אופן הבדיקה מול תיעוד ה-SDK שסופק. לא מוגדר במסמך משך רישום קבוע של מספר שעות או ימים.

5. ביצוע חיוב או זיכוי

לאחר רישום מוצלח וקבלת session תקף, האפליקציה מפעילה את performTransaction עם שני רכיבים: נתוני העסקה (inputObject) ומפתח הרישום (sessionKey). ה-SDK מטפל בפעולת ה-TAP ומחזיר תוצאה לאפליקציה.

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

פרטי הכרטיס: מאחר שהמפרט כולל אפשרות להחזרת מספר כרטיס מלא, יש להעביר מידע לבירור בערוץ המורשה לכך ולהסתיר פרטי כרטיס וסודות בדוגמאות ובצילומי מסך. אין צורך להעביר לתמיכה סיסמת API או מפתח session גלוי.

6. הגדרת תשלומים

עסקה בתשלום אחד

מעבירים NumberOfPayments = 1, CreditType = 1, ושני השדות FirstPaymentSum ו-OtherPaymentsSum בערך 0. הסכום הכולל נשאר בשדה amount.

עסקה בכמה תשלומים

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

amount = FirstPaymentSum + (NumberOfPayments - 1) * OtherPaymentsSum

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

7. איך קוראים את תוצאת העסקה?

תשובת ה-SDK

התשובה עשויה לכלול גם status, transaction_id, ApprovalNumber, UID ו-ResultRecord. שומרים את התשובה המלאה לצורך ההעברה לקארדקום; אין לבנות תשובה חלופית מתוך מספר שדות שנבחרו ידנית.

העברת העסקה לקארדקום - ProcessSDKTransaction

לאחר קבלת תוצאת ה-SDK, שולחים לקארדקום את הבקשה המקורית ואת התשובה שהתקבלה, יחד עם פרטי הזיהוי:

בתשובת קארדקום בודקים ResponseCode, Description ו-DealNumber. האחרון הוא מספר העסקה במערכת קארדקום. אין להחליפו ב-transaction_id או ב-UID שהתקבלו מה-SDK.

שלוש תוצאות שונות:

• HTTP 200 הוא סטטוס של קריאת ה-API.
• response_code הוא שדה בתשובת ה-SDK.
• ResponseCode הוא שדה בתשובת קארדקום.

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

המלצת בירור לתמיכה - SDK הצליח, אך אין אישור קליטה בקארדקום

בודקים האם נשלחה ProcessSDKTransaction, מה הייתה תשובתה והאם התקבל DealNumber. אם התשובה אבדה או התקבל timeout, מחפשים את העסקה לפני שמבקשים לבצע חיוב חדש. המסמך אינו מתאר מנגנון idempotency או כלל מאושר לשליחה חוזרת; נדרש בירור טכני של המקרה.

8. שליפת עסקאות ומכשירים לצורך בירור

שליפת עסקאות - GetTransactions

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

השדות FromDate ו-ToDate נשלחים בפורמט ISO 8601, לדוגמה 2026-10-05T10:00:00. המסמך אינו מגדיר את אזור הזמן, ולכן בבירור עסקה יש לוודא התאמה בין זמן המכשיר, זמן הלוג וזמן החיפוש.

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

שליפת מכשירים - GetDevices

הקריאה מחזירה את מכשירי ה-TAP הרשומים לחברה המזוהה. הבקשה כוללת פרטי API ומספר מסוף. התשובה כוללת רשימת Devices עם UUID, יצרן, דגם, TPN, MerchantCode, IsActive, תאריך יצירה ותאריך פעילות אחרונה.

הופעת מכשיר ברשימה אינה מוכיחה שה-session הנוכחי שלו עדיין תקף. את תוקף הרישום ואת הודעות ה-SDK בודקים בנפרד.

9. בדיקות ראשוניות וטיפול בפנייה

הטבלה הבאה היא סדר בדיקות מוצע לתמיכה, המבוסס על שלבי האינטגרציה. היא אינה רשימת קודי שגיאה רשמית או נוהל הסלמה ארגוני.

מידע מומלץ לצרף לבירור טכני

• מספר המסוף והעסק הרלוונטיים, יצרן ודגם המכשיר, גרסת Android וגרסת האפליקציה.
• מזהה המכשיר DeviceUUID / UUID ותאריך ושעה מדויקים של המקרה, כולל אזור הזמן.
• השלב שבו התהליך נכשל: הכנה, רישום, ביצוע ב-SDK או עיבוד בקארדקום.
• שם ה-callback או ה-endpoint, סטטוס HTTP, קוד התוצאה והודעת השגיאה המלאה.
• סוג העסקה, הסכום ונתוני התשלומים; מזהים זמינים כגון transaction_id, UID, ApprovalNumber ו-DealNumber.
• בקשות ותשובות רלוונטיות בערוץ מתאים, לאחר הסתרת סיסמאות, מפתחות session, פרטי כרטיס מלאים ומידע אישי שאינו נחוץ.

10. דוגמאות להבנת התהליך

דוגמה - עסקה רגילה לאחר רישום תקין

1. המכשיר כבר הוכן ונרשם, והאפליקציה מחזיקה session תקף.
2. לביצוע חיוב של 20 ₪ בתשלום אחד, המפתח מעביר type = "SALE", amount = "20.00", CreditType = 1, NumberOfPayments = 1 ושני סכומי התשלומים בערך 0.
3. האפליקציה מפעילה performTransaction ומקבלת את תשובת ה-SDK.
4. האפליקציה מעבירה לקארדקום את הבקשה ואת התשובה באמצעות ProcessSDKTransaction.
5. נבדקת תוצאת העיבוד בקארדקום ונשמר DealNumber לצורך איתור העסקה.

דוגמה - הרישום דורש חידוש

ה-SDK מחזיר onRegisterNeeded. המפתח מפעיל מחדש את PrepareDevice ואת registerDevice ושומר את ה-session החדש. יש להפריד בין חידוש הרישום לבין קביעה אם מותר או צריך לבצע שוב את העסקה.

דוגמה - SDK הצליח, אך קריאת קארדקום הסתיימה ב-timeout

קוד "00" התקבל מה-SDK, אך אין תשובה סופית מ-ProcessSDKTransaction. זו תוצאה לא מאומתת של שלב הקליטה בקארדקום. בודקים לוגים ומחפשים את העסקה לפי פרטי המסוף, הזמן והסכום. מעבירים לבירור טכני אם לא ניתן לקבוע מה אירע; אין להסיק מה-timeout שהחיוב לא בוצע.

11. נספח למפתח - קריאות API ונתוני SDK

כל קריאות ה-API המפורטות כאן הן מסוג POST, כוללות ApiName ו-ApiPassword ונשלחות ב-application/json. המספרים, פרטי ההזדהות ומזהי המכשירים בדוגמאות הם להמחשה ויש להחליפם בערכים בפועל.

כתובות הקריאות

בקשת PrepareDevice

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456,
  "DeviceUUID": "DEVICE_UUID",
  "DeviceManufacturer": "DEVICE_MANUFACTURER",
  "DeviceModel": "DEVICE_MODEL"
}

התשובה כוללת ResponseCode, Description, TPN, MerchantCode, SapakMutavNumber ו-RavMutavTerminalNumber.

פעולות SDK מרכזיות

topService.registerDevice(tpn, merchantCode, registrationListener);
topService.performTransaction(inputObject, sessionKey, transactionListener);

אלה חתימות שימוש להמחשה. יש לממש את ה-listeners ואת הטיפול בתוצאות בהתאם לחבילת ה-SDK שסופקה. אין להעתיק את דוגמאות ה-callbacks במסמך כקוד מלא: הן אינן כוללות מימוש של שמירה, בקרת תוקף, טיפול בשגיאות או העברה לקארדקום.

בקשת performTransaction - חיוב אחד של 20 ₪

{
  "type": "SALE",
  "amount": "20.00",
  "lang": "iw",
  "CustomObject": {
    "CustomerName": "",
    "CustomerEmail": "",
    "PhoneNumber": "",
    "HolderID": "",
    "NumberOfPayments": 1,
    "FirstPaymentSum": 0,
    "OtherPaymentsSum": 0,
    "CreditType": 1,
    "SapakMutavNumber": "VALUE_FROM_PREPARE_DEVICE",
    "TransactionUniqueIdForQuery": "",
    "AllowFullCardNumberInResponse": true
  }
}

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

בקשת ProcessSDKTransaction - תבנית בלבד

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456,
  "RavMutavTerminalNumber": 654321,
  "DeviceUUID": "DEVICE_UUID",
  "SdkRequest": "THE_ORIGINAL_SDK_REQUEST",
  "SdkResponse": "THE_COMPLETE_SDK_RESPONSE"
}

בדוגמה זו SdkRequest ו-SdkResponse הם מצייני מקום בלבד. יש להעביר את נתוני ה-SDK האמיתיים. המסמך מציג את שני השדות כמחרוזות, אך אינו מפרט חד-משמעית את צורת הסריאליזציה. לפני מימוש יש לאמת בסכמת API v11 אם נדרשת מחרוזת JSON מסוריאליזת או מבנה אחר. אין לשלוח את מילות מצייני המקום.

בתשובת SDK מוזכרים גם transactionResult, customMessage ו-DE48, לצד שדות התוצאה האחרים. הטבלה במסמך אינה מגדירה בבירור את היררכיית הקינון. יש לשמר את התשובה המלאה ולוודא את המבנה מול חבילת ה-SDK; אין להמציא מבנה JSON שטוח על בסיס הטבלה.

בקשת GetTransactions

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456,
  "FromDate": "2026-10-01T00:00:00",
  "ToDate": "2026-10-05T23:59:59"
}

שדות הרשומה ב-Transactions

בתשובה נבדקים גם ResponseCode ו-Description. אין להניח שקוד סטטוס העסקה זהה לקוד ה-SDK; לא מצורפת במסמך טבלת ערכים מלאה לשדה Status.

בקשת GetDevices

{
  "ApiName": "YOUR_API_NAME",
  "ApiPassword": "YOUR_API_PASSWORD",
  "TerminalNumber": 123456
}

התשובה כוללת ResponseCode, Description ורשימת Devices. השדות בכל מכשיר הם UUID, Manufacturer, Model, TPN, MerchantCode, IsActive, CreationDate ו-LastActivityDate.

שגיאות API

המסמך מתאר תשובות 400 Bad Request ו-401 Unauthorized הכוללות ResponseCode ו-Description. יש לבדוק את שני השדות יחד עם סטטוס HTTP, ולא להסתפק בסטטוס התקשורת.

12. נספח למפתח - התקנת SDK והכנת APK

הרשאות בקובץ AndroidManifest.xml

<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />

הערך android:required="false" במניפסט אינו משנה את דרישת השימוש: לביצוע TAP נדרש מכשיר עם NFC. הצהרת הרשאות בקובץ אינה מחליפה בדיקה שהמשתמש העניק לאפליקציה את ההרשאות הנדרשות בפועל.

ספריות וקבצי הפרויקט

1. יוצרים תיקיית libs בשורש הפרויקט אם אינה קיימת.
2. מעתיקים אליה את Cardcom-[version]-Release_Prod.aar שסופק.
3. מגדירים ב-build.gradle את ספריית topliteapp-PROD ואת קובץ ה-AAR. שם הקובץ והגרסאות צריכים להתאים לחבילת ההטמעה בפועל.
4. מגדירים את מאגר ה-SDK בהתאם לחבילה שסופקה. המסמך המצורף מציין s3://denovo-android.s3.amazonaws.com/prod. פרטי הגישה למאגר נמסרים בנפרד בערוץ המורשה.
5. משתמשים בקובץ proguard-rules.pro שסופק, או מוסיפים את תוכנו לקובץ הקיים.
6. לאחר יצירת APK חדש מבצעים Finalization לפי השלבים הבאים.

במסמך המצורף מופיעה גרסת topliteapp-PROD:3.0.5.3. זהו מספר הגרסה שבמסמך, ואינו אישור שהיא הגרסה העדכנית או המתאימה לכל פרויקט. יש להשתמש בגרסאות ובתצורת הבנייה שאושרו לחבילת ההטמעה.

dependencies {
    implementation "com.denovo:topliteapp-PROD:[SDK_VERSION]"
    implementation files("../libs/Cardcom-[AAR_VERSION]-Release_Prod.aar")
}

APK Finalization

משתמשים בתוכן הקובץ AppFinalizationFolder.zip שסופק. מכניסים לתיקיית AppFinalizationFolder את קובץ ה-APK שנבנה, את keystore.jks ואת release.fin. פותחים CMD מתוך התיקייה ומריצים את השלבים לפי הסדר:

שלב א - Finalizer

finalizer -i APKFILE.apk -f release.fin -o finalizedApkFolder

שלב ב - Zip Align

zipalign -p -v 4 finalizedApkFolder\APKFILE-unaligned-unsigned-protected.apk finalizedApkFolder\APKFILE_aligned_unsigned.apk

שלב ג - חתימה

apksigner sign --ks keystore.jks --ks-pass "pass:KEYSTOREPASSWORD" --out finalizedApkFolder\APKFILE_aligned_signed.apk finalizedApkFolder\APKFILE_aligned_unsigned.apk

מחליפים את APKFILE בשם הקובץ בפועל ואת KEYSTOREPASSWORD בסיסמת ה-keystore. הסיסמה בדוגמה היא מציין מקום. הקובץ הסופי לשימוש הוא:

finalizedApkFolder\APKFILE_aligned_signed.apk

יש לבצע את התהליך לכל APK חדש. אין להפיץ לביצוע TAP את הקובץ המקורי או את קובצי הביניים שאינם הקובץ הסופי המיושר והחתום.

יצירת JKS מתוך keystore, אם נדרש

כאשר קיים keystore אך אין קובץ JKS, משתמשים בכלי keytool של Java, מספקים את סיסמת המקור ואת סיסמת היעד ושומרים את קובץ ה-JKS לצורך החתימה:

keytool -importkeystore -srckeystore [file-name].keystore -destkeystore [file-name].jks -deststoretype jks

הפקת SHA256 בהפצה ידנית

keytool -alias [keystore-file-alias] -keystore [file-name].keystore -list -v

מחליפים את שם הקובץ ואת alias בערכים בפועל. בתוצאה מאתרים Certificate fingerprints ומעבירים לקארדקום את ערך SHA256. בהפצה דרך Google Play מקבלים את הנתון מ-Google Play Console, בהתאם להנחיית המסמך.

13. מידע שיש להשלים מול הגורם הטכני

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

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

מצורפת דוקומנטציה עדכנית למתכנת:

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

קבצים מצורפים

• TAP Transaction Process via Cardcom Ltd (2).pdf