# 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: {% code overflow="wrap" %} ```http 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 ``` {% endcode %} 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](/files/ck72M8qHO2YfphSGhgxL) Once the customer finishes their payment, they'll be sent back to your success URL. Along with the usual [payment completion parameters](/pay/getting-started/creating-a-payment-page.md#handle-the-redirect-back-to-your-website), 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: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?action=HKStatus&Masof=0010131918&PassP=your-api-password&HKId=64239&NewStat=1 ``` {% endcode %} 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: ``` HKId=64239&CCode=0 ``` 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](/pay/reference/response-status-codes.md) 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](/pay/getting-started/creating-a-payment-page.md#create-a-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](/pay/common-use-cases/tokenization.md). 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: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?action=soft&Masof=0010345518&PassP=your-api-password&Amount=10&CC=6920843946458103712&Tmonth=06&Tyear=26&Token=True&UserId=000000000&ClientName=Jenny&Info=recurring%20transaction ``` {% endcode %} 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](/pay/reference/actions.md#charge-a-saved-token). {% hint style="info" %} 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. {% endhint %} Here's a sample success response: {% code overflow="wrap" %} ``` Id=408671193&CCode=0&Amount=5&ACode=0502150&Fild1=&Fild2=&Fild3=&Hesh=EZ ``` {% endcode %} If `CCode` is `0`, the charge was successful! If it's anything else, refer to the [Status Codes](/pay/reference/response-status-codes.md) page to identify the issue. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.hyp.co.il/pay/advanced-features/recurring-payments.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.