Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

  1. Hyp-managed — This is the preferred way for most businesses. Hyp takes care of the scheduling and charging for you.

  2. 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=True

In this request:

  • HK: Set this to True to 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 to 1.

  • Tash: If you want the charges to keep rolling indefinitely, set this to 999. Otherwise, enter the specific number of charges you want to make.

  • OnlyOnApprove: We recommend setting this to True so 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:

Payment page for recurring payments

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 to HKStatus.

  • HKId: The unique ID of the agreement you're stopping.

  • NewStat: Set this to 1 to terminate the agreement. If you ever need to turn a terminated agreement back on, you can set this to 2.

  • 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 to soft. This is our protocol for direct server-to-server transactions.

  • CC: The 19-digit token you saved earlier.

  • Tmonth and Tyear: The card's expiration month and year, which you'll get from the Tokef you saved.

  • Token: Set this to True so 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 use 000000000.

  • ClientName: The customer's first name.

  • Info: Any extra info you want to include with the transaction.

For more supported parameters, see Actions.

Normally, a token only works on the terminal where it was created. Sometimes, though, you might have a two-terminal setup. For example, Terminal A (with CVV checks) collects the card info, and Terminal B (no CVV checks) handles the later charges.

If you need to use a token from Terminal A on Terminal B, you can use the tOwner parameter. When you send your payment request to Terminal B, set tOwner to the terminal number of Terminal A.

Note that a two-terminal setup only works when both terminals use the same business ID.

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?