The SUMIT API: Documents and Card Payments From One System

SUMIT exposes a REST API covering two areas that usually live in separate systems: document issuance and card clearing. That makes it unusual in the Israeli market and changes the shape of the integration - for the better, if you plan it right.

Official documentation lives in the developers portal at app.sumit.co.il/developers/api/, where each method documents its exact request structure. That is the binding source - this article is about the decisions, not the field layout.

What the API covers

• Documents - tax invoice, receipt, payment demand, transaction account and other document types.
• Clearing and standing orders - creating a card transaction, setting up a standing order, and a Redirect flow for secure clearing from a website.

That combination is the interesting part. In most Israeli projects the payment gateway and the invoicing system are separate vendors, and the seam between them has to be built and maintained.

The real advantage: one seam fewer

The most common design mistake when connecting payments and accounting is double issuance: the gateway is configured to issue a document automatically on payment, and your system issues one too - producing two tax documents for one transaction. It surfaces at month end, at the accountant's desk.

When clearing and documents live in the same system, that seam simply does not exist. It is a genuine advantage, particularly for businesses collecting on a website and issuing a document immediately.

But it does not remove the decision - it moves it. You still have to decide explicitly: is the document created as part of the clearing flow, or in a separate call from your system after the payment is approved? Both are legitimate. What is not legitimate is failing to decide and then discovering there are two.

Modules - establish before pricing

Integration capability in SUMIT depends on which modules are installed on the account and on configuring API keys. Setup includes installing the relevant module before the interface is available.

The practical consequence: if the client's account does not include the module your design depends on, that is a purchasing decision rather than a technical problem. Raise it with whoever controls budget immediately rather than routing around it in code.

Establish before pricing, in writing: which modules are active, and what is required for the specific scenario.

The decisions that remain - identical to every invoicing system

The retry problem

You send a request, the server issues the document, the connection drops before the response returns. Your code sees a timeout, reads it as failure, retries - and now there are two tax documents with two sequential numbers. A tax document cannot be deleted; cancellation is an offsetting document.

• A timeout is not a failure - it is an absence of knowledge. Do not retry automatically.
• Store your own unique reference on the order, and before any retry check whether a matching document already exists.
• A missing document beats a duplicate.

Which document, and when

Tax invoice, receipt, payment demand and transaction account are not interchangeable - the choice determines when revenue is recognised. That is the business accountant's decision, and if your system selects automatically, the logic needs written sign-off.

VAT and exempt dealers

Verify against a real document how the system expects amounts - inclusive or exclusive of VAT. And an exempt dealer does not issue a tax invoice at all; if the system serves more than one dealer type, that changes the document type.

Allocation numbers

The Tax Authority requirement applies regardless of system. See invoice allocation numbers for developers.

Clearing: what holds with any gateway

If you use the Redirect flow for clearing from a website, these three rules apply exactly as they do with Cardcom or PayPlus:

1. The browser redirect is not a source of truth. A customer who closes the tab the moment payment clears never reaches the thank-you page, and the order stays "pending" while the money has been taken. State updates come from a server-to-server notification.
2. Idempotency. The same notification can arrive twice.
3. Cross-check the amount against the order, server-side, always.

And do not touch card details. That is the whole benefit of Redirect, and it holds only if you do not send, log or store them.

Security

The API keys authorise issuing tax documents and collecting money in the business's name. Environment variables or a secrets manager only - not source control, not logs, and not any code running in a browser.

And persist the full API response even on success: the document id, its number and its link. That is the only evidence when an accounting question arrives six months later.

Checklist

1. Open the developers portal documentation and work from it - not from an example you found.
2. Establish in writing which modules are active on the account.
3. Decide explicitly who issues the document: the clearing flow or your system.
4. Get written confirmation from the accountant on which documents are issued and when.
5. Verify VAT handling against a real document.
6. Build duplicate protection before issuing the first production document.