> 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/clearing-payments/process-api-request-v2.md). # Process a Clearing Request (V2) The main clearing endpoint. Creates a hosted payment page, charges a saved token, or refunds a previous charge — and optionally creates the matching document. ## Endpoint | | | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Method** | `POST` | | **Path** | `/ProcessApiRequestV2` | | **Response** | The same `ApiClearingRequest` object, enriched with results (`ClearingRedirectUrl`, `PaymentId`, `DocumentNumber`, …) — check `Errors` first | ## Flow — standard charge ```mermaid flowchart LR classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333 classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333 classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333 classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333 classDef page fill:#F5F5F5,stroke:#999,color:#333 A[ProcessApiRequestV2]:::step --> B{Request body?}:::dec B -- ✗ --> E1[EmptyObjectInRequest 146]:::err B -- ✓ --> C{Invoice4UUserApiKey
valid GUID + recognized?}:::dec C -- "bad format" --> E2a[ApiKeyNotInCorrectFormat 303]:::err C -- "unknown key" --> E2[UnauthorizedUser 80]:::err C -- ✓ --> D{Clearing terminal
configured?}:::dec D -- ✗ --> E3[ClearingTerminalDoesntExists 96]:::err D -- ✓ --> F{Customer}:::dec F -- "name/email/phone unresolvable" --> E4[CustomerNotFound 136]:::err F -- "CustomerId ✓" --> H[Customer resolved]:::step F -- "IsAutoCreateCustomer" --> G[Find by phone → email
→ create if missing]:::step --> H F -- "neither" --> G2[General one-off
customer]:::step --> H H --> I{IsDocCreate +
manual items valid?}:::dec I -- ✗ --> E5[NumberOfItemsIsNotEqual 24]:::err I -- ✓ --> J[Clearing log
request row]:::step J --> K[🖥 Hosted payment page
ClearingRedirectUrl]:::page K --> L{Charge OK?}:::dec L -- ✓ --> M{IsDocCreate?}:::dec M -- ✓ --> M1[Document created + emailed to
customer and account owner]:::step M -- ✗ --> M2[Email notice only]:::step M1 --> O[CallBackUrl POST
+ ReturnUrl redirect]:::cb M2 --> O L -- ✗ --> N[ClearingError 32
posted to CallBackUrl]:::err ``` ## Request schema — `request` (ApiClearingRequest) ### Authentication | Field | Type | Required | Description | | --------------------- | ------------- | -------- | --------------------------------------------------------------------------- | | `Invoice4UUserApiKey` | string (GUID) | **Yes** | Your organization API key — the only supported authentication for clearing. | {% hint style="warning" %} Clearing requires an **active clearing account (terminal)** on your organization, and the customer identifiers below (`FullName`, `Phone`, `Email`) — they are used to authenticate the payer at the clearing terminal and for payment-page identification. {% endhint %} The clearing provider is the one configured on your terminal — one of the four supported companies (`ClearingCompanies`): **UPay (6)**, **Meshulam (7)**, **YaadSarig (12)** or **Cardcom (15)**. The request is identical for all of them; the API routes to your provider automatically. ### Charge details | Field | Type | Required | Description | | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Sum` | double | **Yes** | Amount to charge. | | `CreditCardCompanyType` | int | **Yes** | Your clearing company type (`ClearingCompanies`): `6` UPay, `7` Meshulam, `12` YaadSarig, `15` Cardcom — must match the provider configured on your terminal. | | `Currency` | string | No | `"NIS"` (default), `"USD"`, `"EUR"`. | | `Type` | int | No | `1` Regular (default), `2` Payments (installments), `3` CreditPayments, `4` Refund. | | `PaymentsNum` | int | No | Number of installments when `Type` is 2/3. | | `Description` | string | No | Charge description (shown on page/document). | | `IsQaMode` | boolean | No | `true` when testing against QA. | | `OrderIdClientUsage` | string | No | Your order reference, echoed back in callbacks. | | `Platform` | string | No | Free-text platform identifier for your integration; recorded with the charge. | Bit / Google Pay / Apple Pay charges use the `IsBitPayment` / `IsGooglePay` / `IsApplePay` flags — see [Bit, Google Pay & Apple Pay](/invoice4u-docs/clearing-payments/alternative-payment-methods.md) for enablement, limitations and errors. ### Customer | Field | Type | Required | Description | | ---------------------- | ------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CustomerId` | int | Conditional | Existing customer. Its name/email/phone are used for the page and notifications. | | `FullName` | string | **Yes** (without `CustomerId`) | Customer full name — used to authenticate the payer at the terminal. Not validated up front by the API; a missing value fails later at the clearing provider. | | `Phone` | string | **Yes** (without `CustomerId`) | Customer phone — payment-page SMS/identification. Not validated up front by the API; a missing value fails later at the clearing provider. | | `Email` | string | Recommended | Customer email — terminal identification and document delivery. | | `IsAutoCreateCustomer` | boolean | No | Find-or-create a real customer record by phone/email; otherwise the charge uses a general customer. | | `IsGeneralClient` | boolean | No (default `true`) | Document is issued to a general (one-off) customer. | ### Redirects & callbacks | Field | Type | Required | Description | | ------------- | ------ | ----------- | ----------------------------------------------- | | `ReturnUrl` | string | Hosted page | Where the customer is redirected after payment. | | `CallBackUrl` | string | Recommended | Server-to-server notification URL. | ### Document creation | Field | Type | Required | Description | | -------------------------------------------------- | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `IsDocCreate` | boolean | No | Create a document automatically after a successful charge. The document is emailed to both the customer and the account owner. | | `DocHeadline` | string | No | Document subject (defaults to `Description`). | | `IsManualDocCreationsWithParams` | boolean | No | Provide explicit line items via the pipe-separated `DocItem*` fields below. | | `DocItemName` / `DocItemQuantity` / `DocItemPrice` | string | With manual items | Pipe-separated lists, equal length, e.g. `"Item A\|Item B"`, `"1\|2"`, `"100\|50"`. | | `DocItemCode` / `DocItemTaxRate` | string | No | Optional pipe-separated code/VAT-rate lists. | | `IsItemsBase64Encoded` | boolean | No | `DocItem*` values are Base64-encoded (for special characters). | | `DocBranchId` | string | No | Branch for the document. | | `DocComments` | string | No | Document comments. | | `Language` / `DocLanguage` | string | No | Page / document language (`"he"` / `"en"`). | | `TaxPercentage` | double | No | VAT override for the document. | ### Tokens, standing orders, refunds See [Tokens & Standing Orders](/invoice4u-docs/clearing-payments/tokens-and-standing-orders.md) for `AddToken`, `AddTokenAndCharge`, `ChargeWithToken`, `IsStandingOrderClearance`, `StandingOrderDuration`, `StandingOrderFirstChargeAmount`, `StandingOrderCallBackUrl` — and [Refunds](#refunds) below for `Refund` + `PaymentId`. `IsStandingOrderRequest` is reserved for internal use. ### Response-only fields | Field | Type | Description | | ----------------------------------- | ----------- | ----------------------------------------------------- | | `ClearingRedirectUrl` | string | Hosted payment page URL — redirect the customer here. | | `PaymentId` | string | Provider payment reference — keep it for refunds. | | `DocumentId` / `DocumentNumber` | GUID / long | The auto-created document (when `IsDocCreate`). | | `CipherText` / `CipherTextOriginal` | string | Ciphers for the document view/print links. | ## Example request — hosted page + auto document ```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 } } ``` ## Example response ```json { "ProcessApiRequestV2Result": { "Sum": 117.0, "OrderIdClientUsage": "10045", "ClearingRedirectUrl": "https://pay.example-provider.co.il/page/abc123", "PaymentId": "ab12cd34", "Errors": [] } } ``` Redirect the customer to `ClearingRedirectUrl`. After payment you receive the callback and, when `IsDocCreate` is set, the document fields (`DocumentId`, `DocumentNumber`, `CipherText`) are populated. ## Callback payload After the customer completes the hosted page, Invoice4U POSTs the result to your `CallBackUrl` as a form field named `Data` containing a JSON object. All values are strings (`"True"`/`"False"` for booleans): ```json Data={ "Success": "True", "TokenCaptureOnly": "False", "TokenCaptureAndCharge": "False", "ErrorMessage": "", "OrderIdClientUsage": "b2f0c9d4-0000-4000-8000-000000000001", "DocCreated": "True", "CardSuffix": "1234", "CardExpirationDate": "0828", "CardBrandName": "Visa", "UniqueId": "012345678", "Amount": "117", "AllPaymentsNum": "1", "CustomerId": "1234567", "CustomerName": "Israel Israeli", "CustomerMail": "israel@example.com", "CustomerPhone": "", "Description": "Order #10045", "AuthNumber": "0123456", "PaymentId": "100200300", "ClearingTraceId": "a1b2c3d4-0000-4000-8000-000000000002", "standingOrderId": "", "DocumentNumber": "70001", "DocumentId": "d4c3b2a1-0000-4000-8000-000000000003", "CipherText": "", "CipherTextOriginal": "" } ``` | Field | Meaning | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `Success` | `"True"` when the charge succeeded. On failure, `ErrorMessage` is populated. | | `TokenCaptureOnly` / `TokenCaptureAndCharge` | Echo of the `AddToken` / `AddTokenAndCharge` flags. | | `OrderIdClientUsage` | Your order reference from the request. | | `DocCreated` | `"True"` when a document was auto-created (`IsDocCreate`). | | `CardSuffix` / `CardExpirationDate` / `CardBrandName` | Charged card details (last 4 digits, `MMYY`, brand). | | `UniqueId` | Payer identifier returned by the provider. | | `Amount` / `AllPaymentsNum` | Charged amount and number of installments. | | `CustomerId` / `CustomerName` / `CustomerMail` / `CustomerPhone` | Resolved customer. | | `AuthNumber` | Clearing company approval number (also stored as `ClearingConfirmationNumber` in the clearing log). | | `PaymentId` / `ClearingTraceId` | Provider payment ID and trace ID — use for refunds and log lookup. | | `standingOrderId` | Populated for standing-order registrations. | | `DocumentNumber` / `DocumentId` / `CipherText` / `CipherTextOriginal` | Created document identifiers and URL-encoded view ciphers (build view links per [Create Document](/invoice4u-docs/documents/create-document.md)). | {% hint style="info" %} Validate the callback by looking up `PaymentId` / `ClearingTraceId` in your [clearing logs](/invoice4u-docs/clearing-payments/clearing-logs.md) before fulfilling the order. If no callback arrives, treat the payment as not completed — the customer may have abandoned the page. {% endhint %} ## Refunds Set `Refund: true` and identify the original charge: | Field | Type | Required | Description | | ----------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Refund` | boolean | Yes | Refund mode. | | `PaymentId` | string | Yes | Provider payment reference of the original charge — used to locate the clearing log (`PaymentIDDoesntExists`, 60, when not found). For UPay, `OrderIdClientUsage` is used as a fallback when empty. | | `Sum` | double | Yes | Amount to refund. | Refund behavior per provider (from the live implementation): * **Cardcom** — the refund is validated against the remaining un-refunded balance: if `Sum` exceeds it, the refund is **clamped to the balance** (not rejected); if nothing is left to refund, `CreditAmountExceedsTotal` (155) is returned. * **UPay** — refunds are possible up to **5 months** after the charge (`ClearingErrorRefundTimeExceeded`, 158). ### Document creation on refunds After a successful refund, a **credit invoice (InvoiceCredit) is created automatically** — but only when the original charge's document can be located through the clearing log (the charge was made with `IsDocCreate` and produced a document). The credit invoice references the original invoice receipt for the refunded amount and is emailed to the customer on record. If no original document is found for the charge, **no document is created** — the refund itself still succeeds, and issuing a credit document is up to you (e.g. via [Create Document](/invoice4u-docs/documents/create-document.md)). Check the refunded document's state after the call to confirm. ```mermaid flowchart LR classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333 classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333 classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333 classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333 A[Refund: true
+ Sum + PaymentId]:::step --> B{Original charge
log found?}:::dec B -- ✗ --> E1[PaymentIDDoesntExists 60]:::err B -- ✓ --> C{Provider rules}:::dec C -- "Cardcom: Sum > balance" --> C2[Refund clamped to
remaining balance]:::step C2 --> D C -- "Cardcom: balance ≤ 0" --> E2[CreditAmountExceedsTotal 155]:::err C -- "UPay: > 5 months old" --> E3[ClearingErrorRefundTimeExceeded 158]:::err C -- ✓ --> D[Sync refund
at provider]:::step D --> F{Success?}:::dec F -- ✓ --> G[Original log marked credited
CreditAmount updated]:::step G --> I{Original document found
via clearing log?}:::dec I -- ✓ --> J[InvoiceCredit created automatically
referencing original doc]:::step I -- ✗ --> K[No document created
issue credit doc yourself]:::step J --> H[Result inline in response
no redirect]:::cb K --> H F -- ✗ --> E4[ClearingError 32
in Errors list]:::err ``` ## Common errors | Error (ID) | Meaning | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `EmptyObjectInRequest` (146) | Request body missing. | | `ApiKeyNotInCorrectFormat` (303) | `Invoice4UUserApiKey` is not a valid GUID. | | `UnauthorizedUser` (80) | API key not recognized. | | `ClearingTerminalDoesntExists` (96) | No clearing account, or the terminal for your provider is misconfigured (missing terminal/username/password). | | `CustomerNotFound` (136) | `CustomerId` sent but name/email/phone could not be resolved. | | `ApiBadRequestChargeMethodMustBeSelected` (319) | Conflicting flags (e.g. `AddTokenAndCharge` + `IsStandingOrderClearance`). | | `ApiTokenizationNotApprovedInClearingTerminal` (309) | Token features not enabled on the terminal. | | `ApiStandingOrderNotApprovedInClearingTerminal` (310) | Standing orders not enabled. | | `ApiGooglePayNotAllowedForUser` (316) / `ApiApplePayNotAllowedForUser` (317) | Wallet method not enabled. | | `NumberOfItemsIsNotEqual` (24) | `DocItem*` pipe-lists have different lengths. | | `PaymentIDDoesntExists` (60) | Refund: original charge log not found for `PaymentId`. | | `CreditAmountExceedsTotal` (155) | Refund: nothing left to refund on the original charge. | | `ClearingError` (32) | Charge declined / provider error — details in `Paramters`. | | `ClearingErrorRefundTimeExceeded` (158) | Refund window exceeded (UPay: 5 months). | ## Try it ## 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}}}}}} ```