נתוני הזמנות של Shop Cash ואינטגרציות של צד שלישי

כאשר לקוח משתמש ב-Shop Cash בהזמנה, Shop Cash נחשב לאמצעי תשלום. אין מדובר בהנחה, בכרטיס מתנה או באשראי בחנות. כל יתרה שנותרה בהזמנה תשולם באמצעות Shop Pay או Shop Pay תשלומי.

לדוגמה, אם לקוח משתמש ב-$25 USD ב-Shop Cash בהזמנה של $100 USD, אז ההזמנה תכלול תשלום Shop Cash בסך $25 USD ותשלום Shop Pay בסך $75 USD. נתוני ההזמנה שלך יכולים לכלול יותר מאמצעי תשלום אחד לאותה הזמנה.

Shop Cash מופיע כעסקת הזמנה עם ערך הספק (gateway) shop_cash במקומות שבהם ערכי ספק זמינים. עסקת ה-Shop Cash פועלת לפי מחזור החיים הרגיל של עסקה, כמו הרשאה, לכידה, ביטול והחזר כספי. Shop Cash אינו משתמש בסוג עסקה של מכירה משולבת.

אם הלקוח משתמש גם בהצעת Shop מתוך Shop Campaign, אז הערך במימון הקמפיין נכלל באותו סכום של עסקת ההזמנה shop_cash. חלקי יתרת הקונה והמימון של הקמפיין אינם מיוצגים כעסקאות הזמנה נפרדות. החל מינואר 2026, עלויות הקמפיין יחויבו בחשבון ה-Shopify שלך במקום להיות מנוכות מהתשלומים שלך, ולכן עסקאות של חיובי קמפיינים בפעילות התשלום חלות רק על קמפיינים שפעלו לפני תאריך זה. למידע נוסף, עיין ב-עמלות, Shop Campaigns ו-Shop Cash.

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

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

• המערכת מסוגלת לתמוך ביותר מאמצעי תשלום אחד בהזמנה אחת.
• המערכת מסוגלת למפות את shop_cash כאמצעי תשלום.
• המערכת אינה מתייחסת ל-Shop Cash כאל הנחה, כרטיס מתנה או אשראי בחנות.
• המערכת שומרת את מזהה עסקת ההזמנה (ID) עבור כל הרשאה, לכידה, ביטול והחזר כספי של Shop Cash.
• המערכת שומרת את ערך ההרשאה המלא של Shop Cash מבלי לקטוע אותו, אם הערך נכלל בנתונים שהמערכת מייבאת.
• המערכת מתייחסת לערכי הרשאה כמחרוזות אטומות (opaque) ואינה מנתחת (parse), מפענחת (decode), מנרמלת, מצפינה בגיבוב (hash) או מסיקה מהם משמעות.
• המערכת מסוגלת לעבד החזרים כספיים שמשיבים כספים גם ל-Shop Pay וגם ל-Shop Cash.
• המערכת יכולה לבצע התאמה פיננסית לעסקאות תשלום של Shop Cash בנפרד מעסקאות תשלום בכרטיס.
• המערכת אינה מניחה שהעסקאות יוחזרו בסדר מסוים.

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

ערך ההרשאה בעסקת Shop Cash הוא מחרוזת אטומה (opaque) באורך משתנה. אין מדובר בקוד הרשאת כרטיס קצר והוא אינו קריא לבני אדם.

אם ה-ERP, ה-OMS או מערכת צד שלישי אחרת שברשותך מייבאת ערכי הרשאה של Shop Cash, יש לשמור את הערך המלא בדיוק כפי שסופק. יש להשתמש בשדה טקסט באורך משתנה או ללא הגבלת אורך במידת האפשר.

כאשר המערכת שומרת ערכי הרשאה של Shop Cash, יש לפעול לפי ההנחיות הבאות:

• אין לקטוע את הערך לאורך קצר קבוע מראש, כמו 50 או 100 תווים.
• אין לנתח (parse) או להסיק משמעות מכל חלק שהוא בערך זה.
• אין להשתמש בערך ההרשאה לזיהוי עסקאות עבור פעולות API של לכידה, ביטול או החזר כספי.

ערכי הרשאה קטועים עלולים לגרום לכישלון של ייבוא מצד שלישי או של עיבוד עוקב ב-ERP או ב-OMS.

כדי לתמוך בלכידות, בביטולים ובהחזרים כספיים דרך Admin API, יש לשמור מזהי עסקאות (IDs) של הזמנות וכן יחסי עסקאות-אב. פעולות לכידה וביטול של Admin API מזהות את עסקת ההרשאה באמצעות parentTransactionId. פעולות של החזר כספי מזהות את עסקת הלכידה שניתן לקבל עבורה החזר כספי (refundable) באמצעות parentId.

כאשר יישום (app) או אינטגרציה מפיקים החזר כספי של Shop Cash דרך ה-API, ההחזר הכספי חייב להיות מוגדר תחת עסקת הלכידה של Shop Cash, ולא תחת עסקת ההרשאה של Shop Cash. החזרים כספיים שמבוצעים מול עסקת ההרשאה יידחו.

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

כאשר משתמשים ב-Admin API, בייצוא הזמנות, בייצוא תשלומים או בייצוא של יישומי צד שלישי, יש להתייחס ל-Shop Cash כאל נתוני תשלום. בהתאם לייצוא או למשאב ה-API שבהם משתמשים, מידע על Shop Cash עשוי להיות מיוצג באמצעות אמצעי תשלום, שער תשלומים (gateway), עסקת הזמנה, עסקת תשלום ונתוני החזר כספי.

בעת בנייה או עדכון של אינטגרציה, יש לשמור את המידע הבא עבור הזמנות שכוללות Shop Cash:

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

לפרטים על שדות Admin API זמינים, יש לעיין ב-dev docs בנושא עסקת הזמנה של Admin API. הימנע מהסתמכות על שדות שיצאו משימוש, כגון OrderTransaction.authorizationCode, עבור אינטגרציות חדשות.

הדוגמה המפושטת הבאה מציגה הזמנה בסך 100 USD ששולמה עם 75 USD דרך Shopify Payments ו-25 USD דרך Shop Cash. הערכים הם להמחשה בלבד.

{
  "transactions": [
    {
      "kind": "authorization",
      "gateway": "shopify_payments",
      "status": "success",
      "amount": "75.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "ch_3OabcXYZ..."
    },
    {
      "kind": "authorization",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "<long-opaque-variable-length-string>"
    },
    {
      "kind": "capture",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": "<shop-cash-authorization-transaction-id>",
      "authorization": null
    }
  ]
}

Shop Cash עשוי להיראות דומה לערכי תשלום או קידום מכירות אחרים, אך על המערכות להתייחס לכל ערך בנפרד:

לפני הסתמכות על מערכת צד שלישי עבור הזמנות שכוללות Shop Cash, יש לאמת את הדרישות הבאות:

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

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