Skip to content

Guide: Working with the Tranzila Integration for Lovable

For Recurring Charges (Subscriptions) Only

The Lovable integration connects your application or website to your terminal's payment page (iFrame), enabling you to accept recurring charges (subscriptions) by credit card.

My Billing required

Recurring charges require Tranzila's My Billing module (recurring charges service), a paid add-on that must be active on the terminal.

Updated: DirectNG payment page

This guide was updated for the new DirectNG payment page. The iFrame base URL is now https://directng.tranzila.com/[terminalname]/iframenew.php (previously https://direct.tranzila.com/...). Already connected using the previous Prompt? Run the full Prompt below again so that your application is updated to the new address.


What Does the Integration Support?

  • Recurring charges (subscriptions) (requires an active My Billing module — recurring charges service — on the terminal).
  • Recurring charges via credit card only.

What Does the Integration NOT Support?

Note: The integration does not set up a Notify page. A Notify page is used to receive the transaction details as processed (including whether it passed or failed), and allows closing a successful transaction in the application/website Back Order. To set up a Notify page, refer to the document "Closing an Order in Lovable Using a Notify Page".

Additionally, refunds cannot be processed directly from the application/website through the integration. Refunds are performed through the terminal's system (My Tranzila).

Furthermore, the recurring charges integration does not support payment via digital wallets.


Requirements for Working with the Integration

  • An active Tranzila terminal.
  • A Supabase account (third-party AI service required by Lovable to build the Backend).
  • An active My Billing module (recurring charges service).
  • Terminal name and PW password.
  • Handshake enabled on the payment page.

Connecting the Application or Website to the iFrame Payment Page

Before starting, make sure your application or website is connected to a Supabase project. To check this, follow these steps:

  • If your application is connected to a Supabase project, a cloud icon with the word Cloud appears in the top toolbar:

Cloud icon – connected

  • If your application is not connected, only a cloud icon appears. Click the cloud icon:

Cloud icon – not connected

  • Now click Enable Cloud:

Enable Cloud

Note: If you already have a Supabase project and want to connect it, click Connect it here below the Enable Cloud button:

Connect it here


Running the Integration Prompt

Finally, copy the long Prompt below, paste it into your application's query window, and click the white arrow:


Text
Connect Tranzila integration:

Tranzila iFrame Recurring Payments Integration Guide for Lovable
Prerequisites
Required parameters:
• supplier - Terminal name
• TranzilaPW - Terminal token password
CRITICAL: Never generate code or UI without these required parameters

Overview – Tranzila Recurring Payments:
The Tranzila recurring payments integration lets your Lovable app embed secure credit-card subscriptions and auto-pay right on your site via an <iframe>. Customers stay on your domain throughout checkout while Tranzila ensures full PCI-DSS compliance. You can bill automatically on a schedule you choose—monthly, quarterly, or annually—based on configurable terms. It's ideal for memberships, subscriptions, and ongoing services, delivering a seamless, branded, and secure payment experience.
Integration Steps:

Step 1: Handshake
In the fraud prevention solution through the execution of HandShake, there is a request to Tranzila, before directing the paying customer to the checkout page, where a unique identifier is created for the amount and transaction details.

The unique identifier will be passed to the payment page after its receipt, along with the rest of the transaction data, but only there will the paying customer enter the card details for the charge.

The URL to perform the handshake is:
https://api.tranzila.com/v1/handshake/create

Parameter - Supplier
Description - Terminal Name

Parameter - TranzilaPW
Description - Terminal Token Password

Parameter - Sum
Description - Transaction amount

The Request must be sent in GET

example:
https://api.tranzila.com/v1/handshake/create?supplier=yourteminalname&sum=1&TranzilaPW=YourTerminalPassword

* The request returns a thtk parameter with a transaction identification string. This parameter, along with the value received, must be sent to the checkout page along with the regular parameters that control the page display (like amount, currency, etc.).

* After submitting the form and before executing a transaction, a comparison of the amount will be made between what you sent at the handshake and what was sent from the checkout page. If the amount is not identical, "Illegal Operation 912791" will be printed without conducting any transaction. If the amount is the same, the transaction will proceed with the parameters sent at the handshake, which are also the ones that will return at the end of the transaction execution.

Step 2: Recurring Payments iFrame Configuration

Base URL: https://directng.tranzila.com/[terminalname]/iframenew.php

Method: POST

Core Parameters for Recurring Transactions:

Parameter – sum
Values – Positive decimal
Description – Transaction amount

Parameter – cred_type
Values – 1
Description – Payment type

Parameter – currency
Values – 1 = NIS, 2 = USD, 978 = EUR, 826 = GBP
Description – Currency type

Parameter – tranmode
Values – A = Standard, V = Verification (J5), K = Create token, N =Verification (J2)
Description – Transaction type

Parameter – thtk
Values – String from handshake
Description – Transaction identifier

Parameter – recur_sum
Values – Positive decimal
Description – The recurring amount charged on each billing cycle. Use together with sum when the first charge differs from the recurring amount (e.g., a joining fee).

Parameter – recur_payments
Values – Integer
Description – The number of recurring charges that will be made - If this field is not passed, the recurring charge will not be limited and will run every month/quarter/year until manually turned off from the terminal.

Parameter – recur_start_date
Values – yyyy-mm-dd (recur_start_date=2023-08-28)
Description – The start date of the recurring charges

Parameter – recur_transaction
Values – 4 = Monthly, 5 = Quarterly, 7 = Yearly (the customer can change the frequency on the payment page)
Values – 4_approved = Monthly, 5_approved = Quarterly, 7_approved = Yearly (the frequency is locked by the merchant; the customer cannot change it)
Description – Recurring charge frequency

Example: Let's assume we want the user to pay 100 NIS for joining our service and 20 NIS each month afterwards for 12 months, without allowing the user to change the frequency:
sum=100
recur_sum=20
recur_transaction=4_approved
recur_payments=12

Customer Information Fields:

Parameter – company
Description – Company name

Parameter – contact
Description – Contact name

Parameter – email
Description – Email address

Parameter – address
Description – Street address

Parameter – phone
Description – Phone number

Parameter – city
Description – City

Parameter – pdesc
Description – Product description for invoice

Parameter – remarks
Description – Additional remarks

Display Customization:

Parameter – trBgColor
Values – Hexadecimal
Description – Background color

Parameter – trTextColor
Values – Hexadecimal
Description – Text color

Parameter – trButtonColor
Values – Hexadecimal
Description – Payment button color

Parameter – buttonLabel
Values – String
Description – Payment button text

Parameter – hidesum
Values – 1
Description – Hide payment sum (only with VK/K/NK tranmode)

Parameter – nologo
Values – 1
Description – Remove Tranzila logo

Parameter – hide_cc
Values – 1
Description – Hide credit card option

Parameter – accessibility
Values – 2
Description – Show accessibility button

Language Support:
Parameter – lang
Values – il
Description – Hebrew

Parameter – lang
Values – us
Description – English

Parameter – lang
Values – ar
Description – Arabic

Parameter – lang
Values – ru
Description – Russian

Parameter – lang
Values – es
Description – Spanish

Parameter – lang
Values – de
Description – German

Parameter – lang
Values – fr
Description – French

Parameter – lang
Values – jp
Description – Japanese

Important! Product Details for Invoice:
To include itemized products on the invoice:
1. Enable product details: Add u71=1 parameter
2. Create product array:

json
[
{
"product_name": "Product 1",
"product_quantity": 2,
"product_price": 50.00
},
{
"product_name": "Product 2",
"product_quantity": 1,
"product_price": 100.00
}
]

3. Stringify without spaces:

json
[{"product_name":"Product 1","product_quantity":2,"product_price":50.00},{"product_name":"Product 2","product_quantity":1,"product_price":100.00}]

4. URL encode (use rawurlencode, not urlencode):
• Spaces must be encoded as %20, not +
• Send as json_purchase_data parameter
Invoice Limitations:
• Maximum 6 products with logo and signature
• Maximum 10 products without lower logo/signature
• Product description: max 118 characters
• Total must equal sum of (quantity × price) for all products

Implementation Examples:
Recurring Payments Form:

<main class="min-h750">
  <div class="container">
    <section id="main-content">
      <div class="row text-center mt-5">
        <div class="col">
          <h1 class="display-3 text-primary">Pay Amount</h1>
        </div>
      </div>
      <div class="row mt-5">
        <div class="col-md-6">
          <form action="https://directng.tranzila.com/[terminalname]/iframenew.php" target="tranzila" method="POST" novalidate="novalidate" autocomplete="off">
            <div class="form-group">
              <input name="sum" type="hidden" value="100" id="sum" />
              <span class="text-danger"></span>
            </div>
            <input type="hidden" name="buttonLabel" value="Pay" />
            <input type="hidden" name="lang" value="il" />
            <input type="hidden" name="recur_sum" value="20" />
            <input type="hidden" name="recur_transaction" value="4_approved" />
            <input type="hidden" name="recur_payments" value="12" />
            <input type="hidden" name="currency" value="1" />
            <input type="hidden" name="thtk" value="[from_handshake]" />
            <button type="submit" name="submit" class="btn btn-primary mt-3" value="pay">pay</button>
          </form>
        </div>
      </div>
      <div class="row mt-5">
        <div class="col-md-6">
          <div class="" style="width: 800px; height: 800px;">
            <iframe id="tranzila-frame" allowpaymentrequest='true' name="tranzila" src="" style="width: 100%; height: 100%;"></iframe>
          </div>
        </div>
      </div>
    </section>
  </div>
</main>

Security Best Practices:

1. Always use handshake for transaction verification
2. Never expose TranzilaPW in client-side code
3. Validate amounts server-side before processing
4. Use HTTPS for all communications
5. Implement proper error handling for failed transactions
6. Store transaction references for reconciliation
7. Use only tranzila iframe parameters to create any type of payment form.

Error Handling:

Common error codes and solutions:

Error – 912791
Description – Amount mismatch
Solution – Ensure handshake amount matches form amount

Error – Invalid terminal
Description – Wrong supplier name
Solution – Verify terminal name with Tranzila

Error – Authentication failed
Description – Wrong password
Solution – Check TranzilaPW parameter

Checklist Before Going Live:

• Obtained production supplier and TranzilaPW
• Implemented handshake mechanism
• Configured all required form parameters
• Tested payment flow end-to-end
• Implemented error handling
• Customized display (colors, language, button text)
• Tested installments (if applicable)
• Verified invoice generation (if using products)
• Secured all sensitive parameters server-side
• Implemented transaction logging
Was this page helpful?