Managing Recurring Payments
A recurring payment is a great way to reuse a customer's card more than once. You'll usually run into two main types of recurring payments:
Subscriptions — where the amount is fixed for every billing cycle. Think of things like a monthly streaming service.
Open agreements — where you have an agreement to charge a customer, but the amount might change each time. This is common for things like monthly utility bills. In Israel, this is often called Horaat Keva (HK).
Hyp Pay supports two ways to create and manage recurring payments:
Hyp-managed — This is the preferred way for most businesses. Hyp takes care of the scheduling and charging for you.
Merchant-managed — This is suitable for businesses that want full control over when and how much to charge. You manage the token creation and trigger the subsequent charges yourself.
Setting up Hyp-managed recurring payments
When you go with Hyp-managed payments, we handle all the recurring logic for you. This means you don't have to worry about setting up cron jobs or managing a database of tokens just to charge your customers regularly. Just keep in mind that this method only works for fixed amounts, which makes it perfect for subscriptions.
Setting up the initial payment
To kick off a recurring payment plan, add a few extra parameters when you create your initial payment page request. It's the same request you'd use for a standard payment page, just with the recurring details added in.
Here's an example of an API request to start a monthly subscription:
https://pay.hyp.co.il/p/?action=APISign&What=SIGN&Masof=0010131918&PassP=your-api-password&KEY=your-api-key&Amount=100&HK=True&freq=1&Tash=999&OnlyOnApprove=TrueIn this request:
HK: Set this toTrueto turn on the recurring payment module.Amount: The fixed amount you want to charge every cycle.freq: The billing cycle in months. For a monthly subscription, set this to1.Tash: If you want the charges to keep rolling indefinitely, set this to999. Otherwise, enter the specific number of charges you want to make.OnlyOnApprove: We recommend setting this toTrueso that the recurring agreement only kicks in after that first payment is officially approved.
You can also tweak the first payment with these parameters:
TashFirstPayment: Use this to set a unique amount for the very first charge if it's different from the usual recurring price.FirstPaymentTash: If you want to let the customer split that first payment into installments, set the number of installments here.
When your customer opens the payment page, they'll clearly see that they're signing up for a recurring charge:

Once the customer finishes their payment, they'll be sent back to your success URL. Along with the usual payment completion parameters, you'll also see an HKId in the URL.
The HKId is a unique ID for the recurring agreement, and you definitely want to save it. You'll need this ID whenever you want to check on the agreement or stop the recurring charges later on.
Automatic charges
After that first payment is done, Hyp will automatically charge the card at the frequency you picked. You can always view and manage these agreements in your Hyp Pay account.
Terminating recurring payments
If you ever need to stop a recurring payment agreement, you can do it manually in your Hyp Pay account or via an API call. To do it through the API, you'll need that HKId you saved earlier.
Here's an example of how to terminate an agreement:
In this request:
action: Set this toHKStatus.HKId: The unique ID of the agreement you're stopping.NewStat: Set this to1to terminate the agreement. If you ever need to turn a terminated agreement back on, you can set this to2.PassP: Your API password.
A successful response will look something like this:
If CCode is 0, everything went through and the agreement is updated. Any other value means there was a problem. For example, code 906 means the agreement you're trying to stop doesn't exist. You can find more details in our Status Codes reference.
Setting up recurring payments that you control
If you need more flexibility, you can take the wheel and manage the recurring logic yourself. This is usually the way to go if:
You're using open agreements where the amount might change every time you charge.
You need to charge customers at custom intervals — like every two weeks instead of once a month.
Step 1: Create a payment page
First, you'll need to create a standard payment page request to handle the initial payment and verify the card.
Once the customer is done, they'll head back to your success URL with an Id parameter. Make sure to save this transaction ID in your database. You'll need it later to get a token for the recurring charges. If you're collecting Israeli IDs, save the customer's ID too, as you'll need it when you make recurring charges later.
Step 2: Obtain a token
When it's time for a recurring charge, you'll need a secure token that represents the card from the first transaction.
To get the token, make a getToken request as described in Saving a Card Token. You'll use the original transaction ID (Id) you saved earlier. Hyp will send back a 19-digit Token and its expiration date (Tokef).
Step 3: Set up a recurring schedule on your end
Since you're managing the payments yourself, you're responsible for timing the charges. You'll need a way for your server to track billing dates and trigger the payment process when it's time.
Lots of developers use a cron job or a task scheduler to check their database for payments due each day. If you're working at a larger scale, a task queue (like BullMQ or Celery) is a great option. Instead of one big script, your scheduler can create a background task for each customer that needs to be charged.
Step 4: Charge the token via direct API
Now that you've got the token and the expiration date, you can make a direct API call to our server to handle the charge. This all happens in the background without the customer needing to do anything.
Here's an example of an API request to charge a saved token:
In this request:
action: Set this tosoft. This is our protocol for direct server-to-server transactions.CC: The 19-digit token you saved earlier.TmonthandTyear: The card's expiration month and year, which you'll get from theTokefyou saved.Token: Set this toTrueso the system knows you're using a token and not a raw card number.UserId: The Israeli ID you saved from Step 1. If your customer didn't enter an ID or you don't want to save it, just use000000000.ClientName: The customer's first name.Info: Any extra info you want to include with the transaction.
For more supported parameters, see Actions.
Here's a sample success response:
If CCode is 0, the charge was successful! If it's anything else, refer to the Status Codes page to identify the issue.
Last updated
Was this helpful?