A practical guide to the Hyp Pay API, formerly YaadPay: how APISign creates and verifies a payment page, how getToken and action=soft charge a saved card, and when to let Hyp run recurring billing with HK=True.
Key takeaways
- Every Hyp Pay call is a GET to https://pay.hyp.co.il/p/ with Masof, KEY and PassP in the query string, so it must run on your server.
- A payment page is signed with APISign What=SIGN and the success redirect is confirmed with APISign What=VERIFY, parameters in the same order.
- The card token is not in the redirect: getToken returns a 19-digit Token plus Tokef, and both are needed to charge with action=soft.
- HK=True lets Hyp run fixed-amount recurring charges and returns an HKId; variable amounts or custom intervals mean running the schedule yourself.
The Hyp Pay API, formerly YaadPay (Yaad Sarig), is a set of GET requests to https://pay.hyp.co.il/p/ that carry your terminal number (Masof), API key (KEY) and API password (PassP) in the query string. Your server signs a payment page, the customer pays on Hyp's page, and your server verifies the result, fetches a card token and charges it again later.
Hyp now publishes its developer documentation at developers.hyp.co.il, split into two products: Hyp Pay, the former YaadPay, and Hyp Enterprise, the former Hyp CreditGuard. When we wrote about Yaad Sarig and Pelecard, that documentation was not publicly reachable. It is now, and this guide covers the Hyp Pay side: the payment page, tokens, recurring charges and refunds.
How does a Hyp Pay payment page request work?
A Hyp Pay payment page is created by your backend, paid in the customer's browser and confirmed by your backend again. The documented flow has five steps:
- Your server sends
action=APISign&What=SIGN&Sign=TruewithMasof,KEY,PassPand the payment parameters. - Hyp answers with a query string: the same parameters,
actionchanged topay, and asignatureadded. You append it unchanged tohttps://pay.hyp.co.il/p/?, in the same order. - The customer is redirected there and enters the card on Hyp's page, so card data never reaches your server.
- Hyp redirects to the success URL set in the Hyp Pay portal, passing
Id,CCode,Amount,ACode,Order,Fild1toFild3andSign. - Your server sends
action=APISign&What=VERIFYwith every parameter from that redirect, in the same order.CCode=0means the transaction matches Hyp's records.
Hyp describes step five as optional and recommends it for every transaction. Treat it as mandatory: the redirect travels through the customer's browser, where it can be edited or never arrive. Verification also depends on Sign=True in step one and on the portal setting "אימות על ידי חתימה בעמודי התשלום" (verify by signature in the payment page), which Hyp says is usually on by default.
The Hyp Pay actions you will actually call
Every Hyp Pay operation goes to the same URL and is chosen by the action parameter. The ones a typical store or subscription business needs:
| action | What it does | Key parameters | Success response |
|---|---|---|---|
APISign + What=SIGN | Creates a signed payment page URL | Masof, KEY, PassP, Sign=True, Amount, Coin, Tash, Order | Query string with action=pay and signature |
APISign + What=VERIFY | Confirms a success redirect was not tampered with | Credentials plus every redirect parameter, in order | CCode=0 |
getToken | Returns the card token of a transaction | Masof, PassP, TransId, optional allowFalse | Token (19 digits) and Tokef (YYMM) |
soft | Server-to-server charge, for example of a saved token | CC, Token=True, Tmonth, Tyear, UserId, ClientName, Info, Amount | Id, CCode=0, ACode |
HKStatus | Stops or restores a Hyp-managed recurring agreement | HKId, NewStat (1 stops, 2 restores) | HKId, CCode=0 |
zikoyAPI | Full or partial refund of a settled transaction | TransId, Amount | A new Id, CCode=0 |
A few values worth knowing before the first request: Coin is 1 for ILS (the default), 2 for USD, 3 for EUR and 4 for GBP; PageLang is HEB or ENG; Tash is the maximum number of instalments the customer may choose. Test terminals always start with 00100, the documentation publishes one test card for success and one for failure, and production uses the same URL with production credentials.
How do recurring charges work in Hyp Pay?
Hyp Pay supports recurring charges in two ways, and the choice depends on whether the amount is fixed.
- Hyp-managed - you add
HK=Trueto the payment page request, withAmountas the fixed charge,freqas the cycle in months,Tash=999to continue indefinitely (or a number of charges), andOnlyOnApprove=Trueso the agreement starts only after the first payment is approved.TashFirstPaymentsets a different first amount. The success redirect adds anHKId, which you save to stop the agreement later withHKStatus. Hyp runs the schedule, so this suits subscriptions. - Merchant-managed - for open agreements where the amount changes each time (the documentation calls this Horaat Keva) or for intervals such as every two weeks. You keep the first transaction's
Id, fetch a token, run the schedule on your own server and charge each cycle withaction=soft.
Before committing to either, compare the requirements in choosing a provider for recurring charges in Israel: who owns the schedule decides who owns the failures.
Charging a saved card token with action=soft
A Hyp Pay token is a 19-digit number whose last four digits match the card, and it is unique per merchant. It represents the card number only, so the expiry date has to be stored alongside it. The token is not in the success redirect: you request it with action=getToken, passing the redirect's Id as TransId, and the response carries Token and Tokef.
The charge itself is an action=soft request with CC set to the token, Token=True, Tmonth and Tyear taken from Tokef, and UserId set to the Israeli ID from the first payment, or 000000000 if your terminal does not require one. Hyp's documentation flags the Israeli ID as sensitive personal data, so store it only when the terminal requires it. A token works on the terminal that created it; a second terminal under the same business ID can use it through tOwner.
The getToken errors to handle explicitly:
901- the terminal is not permitted to use tokenization.902- authentication failed, usually a wrongPassP.910- the transaction was not successful andallowFalse=Truewas not sent.
A declined soft charge returns a CCode other than 0. What to do with it on the next cycle is covered in the failed recurring charge recovery playbook.
Hyp Pay or Hyp Enterprise?
Hyp Pay and Hyp Enterprise are different APIs, so the first step is to confirm which one the business's terminal belongs to. Hyp Pay is the self-service product and supports the simplest PCI level, SAQ A. Hyp Enterprise, the former Hyp CreditGuard, has its own API reference with operations such as doDeal, refundDeal and inquireTransactions, a documented webhooks page, and supports SAQ A-EP and SAQ D. The Hyp Pay documentation index has no webhook page, so on Hyp Pay the success redirect plus VERIFY is the signal you build on.
Inherited code may call the older icom.yaad.net host rather than pay.hyp.co.il. Confirm with Hyp which host and which credentials apply to your terminal before changing it. For a comparison with another Israeli gateway's model, see the Cardcom API integration guide.
What goes wrong in a Hyp Pay integration
- Credentials in the browser.
KEYandPassPtravel in the URL, so Hyp requires the calls to come from your backend over TLS 1.2 or higher, and recommends masking both in logs. - Reordered parameters. Both the payment URL and the
VERIFYcall expect the parameters exactly as received. Rebuilding them from a parsed object can change the order. - Authorisations read as failures. If you configure an error URL, a two-phase authorisation (
700, J5) and a postponed transaction (800) are redirected there, and Hyp says to treat both as success. - A token without its expiry. Without
Tokefyou cannot fillTmonthandTyear, and the stored token is useless. - Checking the HTTP status instead of
CCode. The result is in the response body;999is a communication error,33a refund larger than allowed. - No internal order before
APISign. Create your own order record first and pass it asOrder, so a redirect that never arrives shows up as an unpaid order you can look up in the portal.
Sources
Frequently asked questions
Is Hyp the same as Yaad Sarig?
Yes, for the payment gateway. Hyp's developer documentation describes Hyp Pay as formerly known as YaadPay, the Yaad Sarig gateway. Hyp also offers Hyp Enterprise, the former Hyp CreditGuard, which is a different API. Confirm which of the two your terminal belongs to before you plan the integration work.
Does Hyp Pay have a test environment?
Yes. Hyp Pay test terminals always start with 00100, and the documentation publishes one test card that succeeds and one that fails. The URL is the same in test and production, https://pay.hyp.co.il/p/, so going live means switching Masof, KEY and PassP to the production values Hyp gives you.
How do I charge a saved card with Hyp Pay?
Save the Id from the first successful payment, call action=getToken with it as TransId, and store the returned Token and Tokef. To charge, send action=soft with CC set to the token, Token=True, Tmonth and Tyear from Tokef, UserId, ClientName, Info and Amount. CCode=0 in the response means the charge was approved.
How do I stop a Hyp recurring charge?
For an agreement Hyp manages, send action=HKStatus with your Masof, PassP, the HKId returned in the first success redirect, and NewStat=1. NewStat=2 restores a terminated agreement, and code 906 means the agreement does not exist. You can also stop it manually from the Hyp Pay account.
Can I refund part of a Hyp Pay transaction?
Yes. Send action=zikoyAPI with Masof, PassP, the original transaction's Id as TransId, and the Amount to refund, up to the original value. A refund creates a new transaction with its own Id. Code 33 means the requested amount is larger than the transaction allows.
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 developer
I'm Yehonatan Saadia, a senior developer 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. 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.