> For the complete documentation index, see [llms.txt](https://invoice4u.gitbook.io/invoice4u-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://invoice4u.gitbook.io/invoice4u-docs/he/clearing-payments/process-api-request-v2.md).

# ביצוע בקשת סליקה (גרסה 2)

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

## ‫מתודה‬

|             |                                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| ‫**מתודה**‬ | `POST`                                                                                                                                |
| ‫**נתיב**‬  | `/ProcessApiRequestV2`                                                                                                                |
| ‫**תשובה**‬ | ‫אותו אובייקט `ApiClearingRequest`, מועשר בתוצאות (`ClearingRedirectUrl`, `PaymentId`, `DocumentNumber`, …) — בדקו את `Errors` תחילה‬ |

## ‫סכימת הבקשה — `request` (ApiClearingRequest)‬

### ‫אימות (אחד נדרש)‬

| ‫שדה‬                 | ‫טיפוס‬       | ‫חובה‬   | ‫תיאור‬                                                        |
| --------------------- | ------------- | -------- | -------------------------------------------------------------- |
| `Invoice4UUserApiKey` | string (GUID) | ‫**כן**‬ | ‫מפתח ה-API של הארגון שלכם — אמצעי האימות היחיד הנתמך לסליקה.‬ |

### ‫פרטי החיוב‬

| ‫שדה‬                | ‫טיפוס‬ | ‫חובה‬   | ‫תיאור‬                                                          |
| -------------------- | ------- | -------- | ---------------------------------------------------------------- |
| `Sum`                | double  | ‫**כן**‬ | ‫הסכום לחיוב.‬                                                   |
| `Currency`           | string  | ‫לא‬     | `"NIS"` (ברירת מחדל), `"USD"`, `"EUR"`.                          |
| `Type`               | int     | ‫לא‬     | `1` רגיל (ברירת מחדל), `2` תשלומים, `3` תשלומי קרדיט, `4` זיכוי. |
| `PaymentsNum`        | int     | ‫לא‬     | ‫מספר תשלומים כאשר `Type` הוא 2/3.‬                              |
| `Description`        | string  | ‫לא‬     | ‫תיאור החיוב (מוצג בדף/במסמך).‬                                  |
| `IsQaMode`           | boolean | ‫לא‬     | `true` בבדיקות מול QA.                                           |
| `OrderIdClientUsage` | string  | ‫לא‬     | ‫מזהה ההזמנה שלכם, מוחזר בקולבקים.‬                              |

‫חיובי ביט / Google Pay / Apple Pay משתמשים בדגלים `IsBitPayment` / `IsGooglePay` / `IsApplePay` — ראו [ביט, Google Pay ו-Apple Pay](/invoice4u-docs/he/clearing-payments/alternative-payment-methods.md) להפעלה, מגבלות ושגיאות.‬

### ‫לקוח‬

| ‫שדה‬                  | ‫טיפוס‬ | ‫חובה‬                   | ‫תיאור‬                                                                                                     |
| ---------------------- | ------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `CustomerId`           | int     | ‫מותנה‬                  | ‫לקוח קיים. השם/אימייל/טלפון שלו משמשים לדף ולהתראות.‬                                                      |
| `FullName`             | string  | ‫מותנה‬                  | ‫שם מלא של הלקוח (חובה כשאין `CustomerId`). לא נבדק מראש על ידי ה-API; ערך חסר ייכשל בהמשך אצל ספק הסליקה.‬ |
| `Phone`                | string  | ‫מותנה‬                  | ‫טלפון הלקוח (משמש ל-SMS/זיהוי בדף התשלום). לא נבדק מראש על ידי ה-API; ערך חסר ייכשל בהמשך אצל ספק הסליקה.‬ |
| `Email`                | string  | ‫לא‬                     | ‫אימייל הלקוח — מקבל את המסמך.‬                                                                             |
| `IsAutoCreateCustomer` | boolean | ‫לא‬                     | ‫איתור-או-יצירה של רשומת לקוח אמיתית לפי טלפון/אימייל; אחרת החיוב משתמש בלקוח מזדמן.‬                       |
| `IsGeneralClient`      | boolean | ‫לא (ברירת מחדל `true`)‬ | ‫המסמך מופק ללקוח מזדמן.‬                                                                                   |

### ‫הפניות וקולבקים‬

| ‫שדה‬         | ‫טיפוס‬ | ‫חובה‬     | ‫תיאור‬                        |
| ------------- | ------- | ---------- | ------------------------------ |
| `ReturnUrl`   | string  | ‫דף מתארח‬ | ‫לאן הלקוח מופנה לאחר התשלום.‬ |
| `CallBackUrl` | string  | ‫מומלץ‬    | ‫כתובת התראה שרת-לשרת.‬        |

### ‫יצירת מסמך‬

| ‫שדה‬                                              | ‫טיפוס‬ | ‫חובה‬             | ‫תיאור‬                                                                              |
| -------------------------------------------------- | ------- | ------------------ | ------------------------------------------------------------------------------------ |
| `IsDocCreate`                                      | boolean | ‫לא‬               | ‫יצירת מסמך אוטומטית לאחר חיוב מוצלח.‬                                               |
| `DocHeadline`                                      | string  | ‫לא‬               | ‫נושא המסמך (ברירת מחדל: `Description`).‬                                            |
| `IsManualDocCreationsWithParams`                   | boolean | ‫לא‬               | ‫שליחת שורות פריטים מפורשות דרך שדות ה-`DocItem*` המופרדים ב-pipe שלהלן.‬            |
| `DocItemName` / `DocItemQuantity` / `DocItemPrice` | string  | ‫עם פריטים ידניים‬ | ‫רשימות מופרדות ב-pipe, באורך שווה, למשל `"Item A\|Item B"`, `"1\|2"`, `"100\|50"`.‬ |
| `DocItemCode` / `DocItemTaxRate`                   | string  | ‫לא‬               | ‫רשימות אופציונליות של קוד/שיעור מע"מ.‬                                              |
| `IsItemsBase64Encoded`                             | boolean | ‫לא‬               | ‫ערכי `DocItem*` מקודדים ב-Base64 (לתווים מיוחדים).‬                                 |
| `DocBranchId`                                      | string  | ‫לא‬               | ‫סניף עבור המסמך.‬                                                                   |
| `DocComments`                                      | string  | ‫לא‬               | ‫הערות המסמך.‬                                                                       |
| `Language` / `DocLanguage`                         | string  | ‫לא‬               | ‫שפת הדף / המסמך (`"he"` / `"en"`).‬                                                 |
| `TaxPercentage`                                    | double  | ‫לא‬               | ‫דריסת מע"מ למסמך.‬                                                                  |

### ‫טוקנים, הוראות קבע, זיכויים‬

‫ראו [טוקנים והוראות קבע](/invoice4u-docs/he/clearing-payments/tokens-and-standing-orders.md) עבור `AddToken`, `AddTokenAndCharge`, `ChargeWithToken`, `IsStandingOrderClearance`, `StandingOrderDuration`, `StandingOrderFirstChargeAmount`, `StandingOrderCallBackUrl` — ו[זיכויים](#refunds) להלן עבור `Refund` + `PaymentId`.‬

## ‫דוגמת בקשה — דף מתארח + מסמך אוטומטי‬

```http
POST /Services/ApiService.svc/ProcessApiRequestV2 HTTP/1.1
Host: apiqa.invoice4u.co.il
Content-Type: application/json

{
  "request": {
    "Invoice4UUserApiKey": "d2f1a6b3-1234-4c9a-9f00-1a2b3c4d5e6f",
    "Sum": 117.0,
    "Currency": "NIS",
    "Type": 1,
    "FullName": "Israel Israeli",
    "Phone": "0501234567",
    "Email": "israel@example.com",
    "Description": "Order #10045",
    "OrderIdClientUsage": "10045",
    "IsDocCreate": true,
    "DocHeadline": "Order #10045",
    "ReturnUrl": "https://shop.example/thanks",
    "CallBackUrl": "https://shop.example/api/i4u-callback",
    "IsQaMode": true
  }
}
```

## ‫דוגמת תשובה‬

```json
{
  "ProcessApiRequestV2Result": {
    "Sum": 117.0,
    "OrderIdClientUsage": "10045",
    "ClearingRedirectUrl": "https://pay.example-provider.co.il/page/abc123",
    "PaymentId": "ab12cd34",
    "Errors": []
  }
}
```

‫הפנו את הלקוח ל-`ClearingRedirectUrl`. לאחר התשלום תקבלו את הקולבק, וכאשר `IsDocCreate` מוגדר, שדות המסמך (`DocumentId`, `DocumentNumber`, `CipherText`) מאוכלסים.‬

## ‫זיכויים‬ <a href="#refunds" id="refunds"></a>

‫קבעו `Refund: true` וזהו את החיוב המקורי:‬

| ‫שדה‬       | ‫טיפוס‬ | ‫חובה‬     | ‫תיאור‬                                       |
| ----------- | ------- | ---------- | --------------------------------------------- |
| `Refund`    | boolean | ‫כן‬       | ‫מצב זיכוי.‬                                  |
| `PaymentId` | string  | ‫תלוי-ספק‬ | ‫אסמכתת התשלום/העסקה המקורית (חובה ב-UPay).‬  |
| `Sum`       | double  | ‫כן‬       | ‫הסכום לזיכוי — לא יעלה על היתרה שטרם זוכתה.‬ |

‫מגבלות זיכוי: זיכויי קארדקום נבדקים מול היתרה שנותרה; זיכויי UPay אפשריים עד 5 חודשים מהחיוב (`ClearingErrorRefundTimeExceeded`, 158).‬

## ‫שגיאות נפוצות‬

| ‫שגיאה (ID)‬                                                                 | ‫משמעות‬                                                                |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `EmptyObjectInRequest` (146)                                                 | ‫גוף הבקשה חסר.‬                                                        |
| `UnauthorizedUser` (80)                                                      | ‫מפתח API / פרטי גישה שגויים.‬                                          |
| `ClearingCompanyUndefined` (8)                                               | ‫אין חשבון סליקה פעיל, או שהחשבון מוגדר שגוי.‬                          |
| `ApiBadRequestChargeMethodMustBeSelected` (319)                              | ‫דגלים סותרים (למשל `AddTokenAndCharge` + `IsStandingOrderClearance`).‬ |
| `ApiTokenizationNotApprovedInClearingTerminal` (309)                         | ‫פיצ'רי טוקן לא מופעלים על המסוף.‬                                      |
| `ApiStandingOrderNotApprovedInClearingTerminal` (310)                        | ‫הוראות קבע לא מופעלות.‬                                                |
| `ApiGooglePayNotAllowedForUser` (316) / `ApiApplePayNotAllowedForUser` (317) | ‫אמצעי הארנק לא מופעל.‬                                                 |
| `NumberOfItemsIsNotEqual` (24)                                               | ‫רשימות ה-`DocItem*` באורכים שונים.‬                                    |
| `ClearingError` (32)                                                         | ‫החיוב נדחה / שגיאת ספק — פרטים ב-`Paramters`.‬                         |
| `ClearingErrorRefundTimeExceeded` (158)                                      | ‫חלון הזיכוי חלף.‬                                                      |

## ‫נסו את זה‬

## Process a clearing request

> Creates a hosted payment page, charges a saved token, or refunds a previous charge — and optionally creates the matching document. The response is the same object enriched with results (ClearingRedirectUrl, PaymentId, DocumentNumber...).

```json
{"openapi":"3.0.3","info":{"title":"Invoice4U API","version":"1.0.0"},"tags":[{"name":"Clearing","description":"Credit-card charges, tokens, standing orders and clearing logs."}],"servers":[{"url":"https://api.invoice4u.co.il/Services/ApiService.svc","description":"Production"},{"url":"https://apiqa.invoice4u.co.il/Services/ApiService.svc","description":"QA (staging)"}],"paths":{"/ProcessApiRequestV2":{"post":{"tags":["Clearing"],"operationId":"ProcessApiRequestV2","summary":"Process a clearing request","description":"Creates a hosted payment page, charges a saved token, or refunds a previous charge — and optionally creates the matching document. The response is the same object enriched with results (ClearingRedirectUrl, PaymentId, DocumentNumber...).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request"],"properties":{"request":{"$ref":"#/components/schemas/ApiClearingRequest"}}}}}},"responses":{"200":{"description":"The enriched clearing request.","content":{"application/json":{"schema":{"type":"object","properties":{"ProcessApiRequestV2Result":{"$ref":"#/components/schemas/ApiClearingRequest"}}}}}}}}}},"components":{"schemas":{"ApiClearingRequest":{"allOf":[{"$ref":"#/components/schemas/CommonObject"},{"type":"object","required":["Sum","CreditCardCompanyType"],"properties":{"Invoice4UUserApiKey":{"type":"string","format":"uuid","nullable":true,"description":"Your organization API key — the only supported authentication for clearing. Malformed GUID = ApiKeyNotInCorrectFormat (303); unknown key = UnauthorizedUser (80)."},"Sum":{"type":"number","format":"double","description":"Amount to charge/refund."},"CreditCardCompanyType":{"type":"integer","description":"Clearing company type (ClearingCompanies): 6 UPay, 7 Meshulam, 12 YaadSarig, 15 Cardcom — must match the provider configured on your terminal.","enum":[6,7,12,15]},"Currency":{"type":"string","description":"NIS (default), USD, EUR."},"Type":{"type":"integer","description":"1 Regular (default), 2 Payments, 3 CreditPayments, 4 Refund.","enum":[1,2,3,4]},"PaymentsNum":{"type":"integer","description":"Installments when Type is 2/3."},"Description":{"type":"string","nullable":true},"IsQaMode":{"type":"boolean","description":"true when testing against QA."},"OrderIdClientUsage":{"type":"string","nullable":true,"description":"Your order reference, echoed in callbacks."},"Platform":{"type":"string","nullable":true,"description":"Free-text identifier of the originating platform/system."},"FullName":{"type":"string","nullable":true,"description":"Customer name (required without CustomerId)."},"Phone":{"type":"string","nullable":true},"Email":{"type":"string","nullable":true},"CustomerId":{"type":"integer","nullable":true,"description":"Existing customer ID."},"IsAutoCreateCustomer":{"type":"boolean","description":"Find-or-create a customer record by phone/email."},"IsGeneralClient":{"type":"boolean","description":"Issue the document to a general customer. Default true."},"ReturnUrl":{"type":"string","nullable":true,"description":"Customer redirect after payment."},"CallBackUrl":{"type":"string","nullable":true,"description":"Server-to-server notification URL."},"IsDocCreate":{"type":"boolean","description":"Create a document after a successful charge."},"DocHeadline":{"type":"string","nullable":true},"IsManualDocCreationsWithParams":{"type":"boolean","description":"Provide explicit items via pipe-separated DocItem* fields."},"DocItemName":{"type":"string","nullable":true,"description":"Pipe-separated item names, e.g. \"Item A|Item B\"."},"DocItemQuantity":{"type":"string","nullable":true},"DocItemPrice":{"type":"string","nullable":true},"DocItemCode":{"type":"string","nullable":true},"DocItemTaxRate":{"type":"string","nullable":true},"IsItemsBase64Encoded":{"type":"boolean","nullable":true},"DocBranchId":{"type":"string","nullable":true},"DocComments":{"type":"string","nullable":true},"Language":{"type":"string","nullable":true,"description":"Page language: he / en."},"DocLanguage":{"type":"string","nullable":true,"description":"Document language: he / en."},"TaxPercentage":{"type":"number","format":"double","nullable":true},"AddToken":{"type":"boolean","description":"Save a card token without charging."},"AddTokenAndCharge":{"type":"boolean","description":"Save a token and charge Sum."},"ChargeWithToken":{"type":"boolean","description":"Charge the customer's stored token (server-to-server)."},"Refund":{"type":"boolean","description":"Refund a previous charge (with PaymentId)."},"PaymentId":{"type":"string","nullable":true,"description":"Provider payment reference; response field for hosted pages, request field for refunds."},"IsStandingOrderClearance":{"type":"boolean","description":"Set up a recurring monthly charge."},"StandingOrderDuration":{"type":"integer","nullable":true,"description":"Number of monthly charges. Required for standing orders."},"StandingOrderFirstChargeAmount":{"type":"number","format":"double","nullable":true},"StandingOrderCallBackUrl":{"type":"string","nullable":true},"IsBitPayment":{"type":"boolean","nullable":true},"IsGooglePay":{"type":"boolean","nullable":true},"IsApplePay":{"type":"boolean","nullable":true},"ClearingRedirectUrl":{"type":"string","nullable":true,"readOnly":true,"description":"Hosted payment page URL — redirect the customer here."},"DocumentId":{"type":"string","format":"uuid","nullable":true,"readOnly":true},"DocumentNumber":{"type":"integer","format":"int64","readOnly":true},"CipherText":{"type":"string","nullable":true,"readOnly":true}}}]},"CommonObject":{"type":"object","description":"Response envelope inherited by most objects. Server-generated — never send these fields in requests. Always check Errors before using the payload.","properties":{"Errors":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonError"}},"Info":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonInfo"}},"OpenInfo":{"type":"object","readOnly":true,"additionalProperties":{"type":"string"},"nullable":true}}},"CommonError":{"type":"object","properties":{"ID":{"type":"integer","description":"Numeric error code, e.g. 80 = UnauthorizedUser, 134 = DocumentAlreadyCreated."},"Error":{"type":"string","description":"Error name."},"Paramters":{"type":"string","nullable":true,"description":"Optional context, e.g. \"Row Number - 0\"."}}},"CommonInfo":{"type":"object","properties":{"ID":{"type":"integer"},"Info":{"type":"string"},"Paramters":{"type":"string","nullable":true}}}}}}
```