A developer's guide to the Rivhit Online API and iCredit - the Document.New endpoint, why document type decides whether a payment object is mandatory, the retry problem with issued documents, and what to settle before you write code.
Key takeaways
- The document type decides the required fields. A receipt or a combined invoice-receipt demands a payment object, and each payment method has its own mandatory fields - a plain invoice does not.
- This is a WCF-style service, not a modern REST API. Operations are named endpoints like Document.New rather than resources with HTTP verbs, so REST habits will mislead you.
- An issued document cannot be edited or deleted. Design retries around that: a timed-out request may have succeeded, and a blind retry produces a duplicate tax document.
- Rivhit ships both a documents API and iCredit, its payment gateway. Decide early whether you are issuing documents, taking payments, or both - they are separate integrations with separate credentials.
Rivhit is one of the long-established accounting systems in Israel, and it exposes two separate interfaces: an API for issuing documents in Rivhit Online, and iCredit, its payment gateway. Untangling the two is the first thing worth settling, because they serve different purposes and use different credentials.
What this actually is: not modern REST
The base is https://api.rivhit.co.il/online/RivhitOnlineAPI.svc, and creating a document is the Document.New operation.
Note the shape: this is a WCF-style service - named operations, not resources with verbs. There is no POST /documents and no DELETE /documents/123. There is one endpoint per operation, and they all take POST. If you are coming from REST, that expectation will confuse you more than anything else in the interface.
Official documentation lives at rivhit-api.readme.io, and a live operations list is available at the service's /help path. That is the page to open before writing a line - it shows the operations that exist and the request shape of each, against the version actually running.
The decision that drives everything: document type
The document type field is not a technical detail - it determines both the legal meaning and which fields the request must contain.
The central rule: documents representing receipt of money require a payment object. A receipt, and a combined invoice-receipt (document type 2), will not be created without payment detail. Moreover, each payment method has its own mandatory fields - cash, cheque, credit card and bank transfer do not share a structure. Sending a generic payment object will fail.
By contrast, an invoice not accompanied by payment, a delivery note or an order does not need one.
The design consequence: do not build one generic function that takes a "document type" parameter and hopes for the best. For every document type your system issues, build an explicit path with its own validation. A document that fails on a missing field is far better than one created incorrectly.
The problem that catches every first integration: retries
An issued tax document cannot be edited and cannot be deleted. Cancellation is done with an offsetting document.
Hence the recurring scenario: you send a create request, the server issues the document, and the connection drops before the response arrives. Your code sees a timeout, reads it as failure, and retries - and now there are two tax documents with two sequential numbers, one of which needs a manual cancellation in the books.
Three rules:
- Do not retry automatically after a timeout. A timeout is not a failure - it is an absence of knowledge.
- Store your own unique reference on the order or transaction, and before any retry check whether a matching document already exists.
- A missing document beats a duplicate. The first is handled in a minute; the second needs a cancellation and a paper trail.
iCredit - the other side of Rivhit
iCredit is the payment gateway. It covers dynamic payment pages, tokenising payment methods, recurring charges, and automatic document production following a payment.
The decision to make early: who issues the document? If the gateway is configured to produce a document automatically on successful payment, and your system also issues its own, you get two documents for one transaction. This is not a rare glitch; it is the common design mistake when payments and accounting land in the same project.
Pick one side and document it.
What to persist
- The document id and its sequential number
- The document link, so you never regenerate it
- The document type and timestamp
- The full API response, including on success - it is the only evidence in a dispute or an accounting query
What to settle before writing code
- Document types. Which documents the system issues, and at what point in the process. That is the business accountant's decision, not the developer's, because it determines when revenue is recognised.
- VAT. Whether the amounts you send are inclusive or exclusive. Verify against a real document rather than assuming.
- Exempt dealers. An exempt dealer does not issue a tax invoice. If the system serves more than one dealer type, that changes the document type.
- Allocation numbers. Confirm the flow handles the Tax Authority requirement before go-live. See invoice allocation numbers for developers.
- Secrets. The credentials permit issuing tax documents on behalf of the business. Environment variables or a secrets manager only - not source control, not logs, not client-side code.
For a comparison of the Israeli systems by how easy they are to connect to, see comparing the Israeli invoicing APIs.
Frequently asked questions
Does Rivhit have an API?
Yes. Rivhit Online exposes a documents API at https://api.rivhit.co.il/online/RivhitOnlineAPI.svc, where creating a document is the Document.New operation. Rivhit also ships iCredit, a separate payment gateway with its own credentials. Documentation is published at rivhit-api.readme.io, and the live operation list is at the service's /help path.
Why does creating a receipt in Rivhit fail with missing fields?
Because documents that represent receipt of money require a payment object, and each payment method has its own mandatory fields. A receipt, and a combined invoice-receipt (type 2), will not be created without it, while a plain invoice or delivery note does not need one. Sending a generic payment structure across all methods will fail - build an explicit path per document type.
Is the Rivhit API a REST API?
Not in the modern sense. It is a WCF-style service built around named operations such as Document.New, all invoked by POST, rather than resources addressed with HTTP verbs. There is no DELETE on a document and no resource-per-entity URL structure, so REST assumptions will mislead you when reading the documentation.
How do you avoid duplicate invoices when a Rivhit call times out?
Do not retry automatically. A timeout means you do not know whether the document was issued, and an issued tax document cannot be deleted - only offset with a counter-document. Store your own unique reference on the order, and before any retry query whether a document already exists for it. A missing document takes a minute to fix; a duplicate needs a cancellation and a paper trail.
Should iCredit or my own system issue the invoice?
One of them, never both. iCredit can be configured to produce a document automatically on a successful payment; if your system also issues its own, a single transaction ends up with two tax documents. This is the most common design mistake when a project connects payments and accounting together. Decide which side owns document production and write it down.
Keep reading
Related service
Integrations
Make the systems you already pay for talk to each other.
About the author
Yehonatan Saadia
Freelance automation, web & MVP engineer
I'm Yehonatan Saadia, a senior engineer who builds business automation, custom websites, and MVPs for small and mid-sized companies across the US, Europe, and Israel. These guides come from real client work, not theory.
Work with meHave a project like this?
Tell me what you're trying to automate or build and I'll tell you the fastest reliable way to ship it.