A developer's guide to the Cardcom LowProfile v11 API - the Create endpoint, why ResponseCode is the only success check, the string document enums that replaced legacy numeric codes, and why the webhook rather than the redirect is your source of truth.
Key takeaways
- Success in v11 is ResponseCode == 0. The old DealResponse field does not exist in v11 at all - code copied from a legacy example will read success as failure or worse.
- DocumentTypeToCreate is a string enum in v11 - "TaxInvoiceAndReceipt", "TaxInvoice", "Receipt" - not the numeric codes like 101 or 400 that belong to the older .aspx interfaces.
- Treat the WebHookUrl as the source of truth, not the browser redirect. A customer who closes the tab after paying never reaches your success URL, but the webhook still fires.
- Save the LowProfileId returned by Create. It is the handle that ties your order to the transaction, and without it reconciling a payment against your own records becomes manual work.
Cardcom is one of the long-established Israeli payment gateways, and its LowProfile interface is the common way to take a payment from a website or system: you create a payment page, send the customer to it (or embed it in an iframe), and the card processing happens on Cardcom's side - so card details never pass through your server at all.
This guide covers v11, and the differences between it and the older interfaces are exactly where integrations fall over.
Creating a payment page
The call is:
POST https://secure.cardcom.solutions/api/v11/LowProfile/CreateThe main body fields:
TerminalNumber- the terminal number. Must be sent as an integer, not a string.ApiName- the API usernameOperation- what to do: charge only, create a token, or bothAmountandISOCoinId- amount and currencyReturnValue- the most useful field in practice. A free field returned to you verbatim. Put your order id in it.SuccessRedirectUrlandFailedRedirectUrl- where the browser is sentWebHookUrl- where Cardcom notifies your serverLanguageDocument- an optional object for issuing a document automatically
The v11 schema marks six fields as required: TerminalNumber, ApiName, Amount, SuccessRedirectUrl, FailedRedirectUrl and WebHookUrl. An optional CancelRedirectUrl handles the cancel button. Operation defaults to ChargeOnly; the other values are ChargeAndCreateToken, CreateTokenOnly, SuspendedDeal and Do3DSAndSubmit.
The response returns LowProfileId - store it on the order - and Url, which you redirect to or embed in an iframe. If Bit or PayPal are enabled on the terminal, UrlToBit and UrlToPayPal come back too.
Three v11 traps behind most failures
1. ResponseCode, not DealResponse
This is the costly one. In v11 you check success with ResponseCode == 0. The DealResponse field, which appears in countless web examples and older libraries, does not exist in v11 at all.
Code checking a non-existent field receives undefined or null, and its comparison fails - so success reads as failure, or the reverse, depending on how the check was written. This is precisely the class of bug that passes testing and detonates in front of a customer.
Every endpoint also returns a Description string explaining the outcome. Log it always, including on success.
2. Document types are strings, not numbers
If you ask Cardcom to issue a document automatically, the DocumentTypeToCreate field in v11 is a string enum: "TaxInvoiceAndReceipt", "TaxInvoice", "Receipt" and so on.
The numeric codes you may find in examples - 101, 400 and friends - belong to the older .aspx interfaces, not v11. Sending a number where a string is expected will fail.
3. ApiPassword is not sent on a normal call
ApiPassword is not sent on a standard LowProfile/Create or a standard transaction charge. If you added it because you saw it somewhere, check the documentation for which operation actually requires it - sending superfluous fields is an easy route to a confusing validation error.
The architectural decision: webhook or redirect
There are two channels through which you learn a payment succeeded, and choosing between them determines how many orders quietly "vanish".
| Browser redirect | WebHookUrl | |
|---|---|---|
| Arrives via | The customer | Cardcom's server directly |
| Always happens? | No | Yes |
| Depends on | The customer not closing the tab | Nothing |
The redirect is not reliable. A customer who closes the browser the instant the payment clears, whose connection drops, or who simply does not wait, never reaches your SuccessRedirectUrl. If that is where you mark the order paid, the order stays "pending" while the money has been taken. This happens, and it looks like a random bug.
The rule: the webhook updates order state. The redirect shows the user a thank-you screen. Never the other way round.
And the webhook endpoint must be idempotent regardless - the same notification can arrive more than once, and that must not produce two paid orders.
The second decision: who issues the document
Cardcom can issue a document automatically through the Document object. That is convenient - but if your system also issues an invoice through your invoicing system, one transaction ends up with two tax documents.
This is the most common design mistake when payments and accounting land in the same project, and it surfaces at month end. Pick one side and write it down.
How do you verify a Cardcom webhook?
The safe way to verify a Cardcom webhook is not to trust its content but to ask Cardcom back. Call POST /api/v11/LowProfile/GetLpResult with TerminalNumber, ApiName and the LowProfileId you stored on the order, and compare what returns - ResponseCode, the amount and the ReturnValue - with what you asked for. A forged request to your webhook URL then changes nothing, because the state comes from Cardcom's answer. In the work-wear ordering site with logo printing the server recalculates price and stock before the Cardcom page opens, and stores the session id on the order so the callback is checked against that exact session.
What else is in the Cardcom API besides a payment page?
The v11 API publishes its full reference as Swagger at secure.cardcom.solutions/swagger, and every path starts with /api/v11/. The endpoints an integration usually reaches for after the payment page:
| Endpoint | What it does |
|---|---|
LowProfile/GetLpResult | The result of a payment-page deal, by LowProfileId |
Transactions/Transaction | Performs a transaction, for example a charge against a stored token |
Transactions/GetTransactionInfoById | Transaction details by id |
Transactions/RefundByTransactionId | A refund by transaction id |
Documents/CreateDocument | A document associated with a deal |
Documents/CancelDoc | Cancels a document and refunds the card |
RecuringPayments/GetRecurringPayment | Recurring payment details, with a separate history endpoint |
SuspendedDeals/Charge | Charges a suspended (J5) deal |
Refunds deserve a decision of their own. If Cardcom issued the document, Documents/CancelDoc cancels it and refunds the card in one call, while RefundByTransactionId refunds the transaction alone. Pick the one that leaves no document without a refund and no refund without a document.
Can you accept Bit through the Cardcom API?
Yes, when Bit is enabled on the terminal: LowProfile/Create then also returns UrlToBit. Cardcom is one of the nine companies the Bit for business site lists as a way to accept Bit, and Bit itself has no public developer API, so the Cardcom call is the integration. What can be automated around Bit and PayBox collection is covered in Bit and PayBox in a collection process.
Security and compliance
- Do not touch card details. The entire point of LowProfile is that they never pass through you. Do not send them, log them or store them - doing so pulls you into PCI DSS scope.
- Authenticate the webhook. A public endpoint that marks orders paid is an obvious target. Do not rely on the URL being secret - validate the request and cross-check the amount against the order.
- Cross-check amounts. Always confirm the returned amount matches what you asked for. Do not assume nobody tampered with the request.
- Server-side secrets only.
ApiNameand terminal details never appear in client code.
Before going live
- Confirm your terminal is actually on v11 and enabled for LowProfile.
- Test the webhook path end to end, not just the redirect.
- Explicitly test the case where the customer closes the tab right after paying.
- Decide whether
Documentapplies to you, and confirm there is no double issuance. - Test a real failure, not only success -
FailedRedirectUrland a non-zeroResponseCode.
For a comparison of the Israeli gateways, see Israeli payment gateways compared.
Sources
Frequently asked questions
How do you check if a Cardcom v11 transaction succeeded?
Check ResponseCode == 0. The DealResponse field used in many older examples and libraries does not exist in v11, so code checking it receives undefined and produces the wrong verdict. Every v11 endpoint also returns a Description string explaining the outcome, which is worth logging on success as well as failure.
Should I mark an order paid on the Cardcom redirect or the webhook?
The webhook. The browser redirect depends on the customer staying on the page - anyone who closes the tab after paying never reaches your success URL, leaving an order marked pending while the money was taken. Use WebHookUrl to update order state and the redirect only to show a thank-you screen, and make the webhook endpoint idempotent since notifications can repeat.
What document type codes does Cardcom v11 use?
String enums such as "TaxInvoiceAndReceipt", "TaxInvoice" and "Receipt" in the DocumentTypeToCreate field. The numeric codes like 101 or 400 that appear in many examples belong to the older .aspx interfaces and will not work against v11. Sending a number where the string enum is expected produces a validation failure.
How do I link a Cardcom payment back to my own order?
Use the ReturnValue field, which is a free-text field returned to you verbatim - put your order id in it. Also store the LowProfileId returned by the Create call on your order record. Between the two you can reconcile any payment against your own data without manual comparison.
Does using Cardcom LowProfile put me in PCI DSS scope?
The point of LowProfile is that card details are entered on Cardcom's page and never pass through your server, which keeps your scope minimal. That protection only holds if you never send, log or store card data yourself. The moment card details touch your system - even in a log line - the picture changes.
How do you refund or cancel a Cardcom transaction through the API?
Cardcom v11 has two routes. Transactions/RefundByTransactionId refunds a transaction by its id. Documents/CancelDoc cancels a document Cardcom issued and refunds the card in the same call. If Cardcom produces your invoices, use the route that keeps the document and the refund together, so neither is left behind.
Can I accept Bit through the Cardcom API?
Yes, if Bit is enabled on your terminal. LowProfile/Create then returns UrlToBit alongside the regular Url. Cardcom is one of the companies the Bit for business site lists for accepting Bit, and Bit has no public developer API of its own, so the payment is handled entirely through the Cardcom call and webhook.
Where is the Cardcom API documentation?
The v11 reference is published as Swagger on secure.cardcom.solutions/swagger, with every endpoint under /api/v11/ - LowProfile, Transactions, Documents, RecuringPayments, SuspendedDeals and more - including the request schemas and which fields are required. Work from that reference rather than from older aspx examples, which use different field names and numeric codes.
Keep reading
Related service
Integrations
Make the systems you already pay for talk to each other.
Have a project like this?
Tell me what you're trying to automate or build. I reply within 24 business hours with a few targeted questions, then we walk through it on a free 30-minute call, with no commitment. You come away with a scope, a timeline and a fixed price - or a straight answer that it isn't worth building.