Hyp Pay API (Formerly Yaad Sarig): Payment Pages, Card Tokens and Recurring Charges

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.

Hyp API quick start: credentials, test terminal and documentation

The first Hyp API call needs three values from Hyp and one setting in the Hyp Portal. Hyp's onboarding team (ipos@hyp.co.il) emails the terminal numbers and the portal login, one terminal and one portal account per environment. The API key and the API password are then in the portal, not in the email.

Hyp recommends setting only the success URL and leaving errors on its own payment page: with an error URL configured, every transaction that is not a standard immediate charge is redirected to your site. Test with low amounts, around 10 ILS is what Hyp suggests. The documentation publishes one test card that succeeds and one that fails, and when you move to production only the terminal number, KEY and PassP change; the test card then stops working.

The documentation lives at developers.hyp.co.il. Hyp Pay pages sit under /pay/, Hyp Enterprise under /enterprise/, and the two Hyp Pay reference pages you will open most are API Actions (every action value) and Status Codes (what each CCode means).

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:

1. Your server sends action=APISign&What=SIGN&Sign=True with Masof, KEY, PassP and the payment parameters.
2. Hyp answers with a query string: the same parameters, action changed to pay, and a signature added. You append it unchanged to https://pay.hyp.co.il/p/?, in the same order.
3. The customer is redirected there and enters the card on Hyp's page, so card data never reaches your server.
4. Hyp redirects to the success URL set in the Hyp Pay portal, passing Id, CCode, Amount, ACode, Order, Fild1 to Fild3 and Sign.
5. Your server sends action=APISign&What=VERIFY with every parameter from that redirect, in the same order. CCode=0 means 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:

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.

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=True to the payment page request, with Amount as the fixed charge, freq as the cycle in months, Tash=999 to continue indefinitely (or a number of charges), and OnlyOnApprove=True so the agreement starts only after the first payment is approved. TashFirstPayment sets a different first amount. The success redirect adds an HKId, which you save to stop the agreement later with HKStatus. 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 with action=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 wrong PassP.
• 910 - the transaction was not successful and allowFalse=True was 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.

Issuing an invoice with the Hyp Pay charge

Hyp Pay can issue the invoice itself, so an integration that only needs one document per payment does not need a separate invoicing system. Invoicing is on by default on the terminal, and Hyp issues a document automatically for every successful transaction, including refunds, cancellations and payouts. The default document is a tax invoice receipt (חשבונית מס קבלה); the terminal can be set to issue a receipt instead, and a non-profit can default to a donation receipt. The document is controlled by parameters on the same payment request:

• SendHesh=True emails the document to the customer, at the address in email.
• sendHeshSMS=True sends a link to the document by SMS, to the number in cell.
• heshDesc is the general description printed in the Details cell.
• Pritim=True tells Hyp you are sending a list of items; Hyp multiplies quantity by price for each item and sums them.
• EZ.customer_crn is the customer's business number, which Hyp's documentation says Israeli law requires on documents worth more than 5,000 ILS.

If the business already issues its documents in another system, decide which one issues for each transaction. Two systems issuing for the same payment leave two numbered documents to reconcile. The full pattern is in payment-to-invoice automation in Israel.

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. KEY and PassP travel 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 VERIFY call 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 Tokef you cannot fill Tmonth and Tyear, and the stored token is useless.
• Checking the HTTP status instead of CCode. The result is in the response body; 999 is a communication error, 33 a refund larger than allowed.
• No internal order before APISign. Create your own order record first and pass it as Order, so a redirect that never arrives shows up as an unpaid order you can look up in the portal.

Sources

• Hyp Pay - Creating a Payment Page
• Hyp Pay - Managing Recurring Payments
• Hyp Pay - Saving Card Tokens
• Hyp Pay - Prerequisites and Initial Setup
• Hyp Pay - Safe Testing and Environments
• Hyp Pay - Basic Invoicing