Iframe Integration

your iframe base url will be - https://direct.tranzila.com/terminalname/iframenew.php

Secure Payment Page Integration - Introduction

In accordance with credit card companies' guidelines, which were established in 2012, it is prohibited to capture and transmit credit card details on a payment page of a website that has not been authorized to comply with the PCI DSS security standard.

In order to make it easier for our customers, we have developed the Redirect Page - a payment page hosted on Tranzila servers that has received and passed all the certifications and requirements of the new PCI-DSS security standard.

You can integrate the payment page as an external Direct payment page or as an internal payment page on your website through an Iframe.

Why use iframe?

By using the IFRAME tag, another document can be hosted within an existing document within an inline frame.

Your website can be integrated with TranZila's redirect solution using IFRAME to prevent your customers from leaving your website and paying inside the secure framework.

By using IFRAME, you can display only the payment input fields of the redirect page within your site's Iframe payment page while still adhering to PCI-DSS's strict security standards.

Using a redirect page

With this option, the user is automatically redirected to the external payment page from the website they were browsing. The page is designed with a basic default design that can be customized and changed according to the service's needs. You can define and modify the design to suitable colors, display the service provider's logo, an image, select fields to display, and more.

Using an Iframe Embedding Window on Your Website

With this option, the iframe is actually a derivative of the redirect page. You can define the relevant fields and embed them in the payment page of your website according to your needs. The main advantage of using the payment page as an Iframe is that the user stays on the website and does not go to an external payment page, thus not compromising the user experience and flow during the purchase process, resulting in higher conversion rates. The displayed logos can be removed and the background color can be changed to match the website's color, so the user doesn't even feel the difference, even though their details are being transferred from a different URL.

For both integration options, it is important to ensure that the data is transmitted securely and encrypted according to the PCI-DSS standard.

Getting started

We recommend checking out our examples they are full of useful information to get started quickly!

Choose iframe settings in the dashboard

Data transfer and retrieval in the payment page

Data transfer to the payment page can be done through either POST or GET. For a redirect payment page, parameters can only be sent through POST, while for an iframe payment page, data can be sent through both POST and GET. We recommend using POST for both types of payment pages.

Data retrieval is done through an array that contains the response from the credit card companies and the variables (parameters) that were entered in the payment page. This array is returned through POST or GET to the success/failure URL that was defined in the payment page settings (Merchant).

If a Notify page was defined, transaction data will also be sent to it in parallel.

your iframe base url will be - https://direct.tranzila.com/terminalname/iframenew.php

iframe parameters table

predetermined additional fields

Installments

must be with cred_type=8

The formula for calculating payments is: sum = fpay + spay*npay

The calculation formula for Installments is as follows:

The sum is equal to the first payment (fpay) plus the second payment (spay) multiplied by the number of payments (npay).

Display Settings

Language display options is set with the parameter - lang - using the following Values

Add Payment Options

3DS V2 Settings

Recurring Payment - Customer Choice

Technical Specifications for Z_field Parameter

When integrating with our system, you will need to define a custom field called Z_field in the User Defined Fields section of your merchant account via the MY.TRANZILA interface. Here are the key details:

• Parameter Name: Z_field
• Maximum Length: 8 digits
• Type: Numeric

Example Usage:

"Z_field": 12345678

Working Method:

1. When Z_field is Sent:

   • If you include the Z_field parameter in your request, its value will replace the corresponding value in zData that is sent to SHVA.

2. When Z_field is Not Sent:

   • If the Z_field parameter is not included in the User Defined Fields and is not sent in the payment request, the transaction index will continue to be sent in zData as usual.

Please ensure that the Z_field parameter is defined in the User Defined Fields via the MY.TRANZILA interface and is correctly included in your requests to customize the data sent to SHVA.

Invoice Product List (Product Details)

If you have purchased Tranzila's invoice module, you can use the detailed product list solution for the invoice to display the purchased items in separate rows on the invoice. Highlights for executing product details:

• The final transaction price must be equal to the prices and quantities detailed.
• If the amount is not equal, the invoice will display the product list without detailing the amount for each product.
• If a default VAT percentage is set, VAT must be extracted and the price per product sent as the price before VAT.
• To add product details on a Direct Clearance page or Iframe, send the parameter u71=1.

Notes for displaying product details on the invoice:

• A PDF file is produced in A4 size; if the invoice is larger than A4, the display will be cut off and not fully shown.
• For an invoice with an upper logo of 21056 mm, a lower logo of 11051 mm, and using a digital signature, up to 6 products can be properly displayed.
• If you waive the lower logo or digital signature, up to 10 products will be displayed.
• If you reduce or enlarge the lower or upper logo or both, the number of products that will fit on the invoice will change.
• The product description must include up to 118 characters.
• If the product description has more than 118 characters without spaces between them, the product description will appear as one string, but the invoice will be displayed in width.
• When printing an invoice from the Tranzila system (from the invoice module), the invoice will be printed on several pages, according to the number of products displayed. (A product description that is too wide will have the same effect as in a PDF)
• You can set the document type to be produced as an HTML file; it is created in the size suitable for the invoice regardless of the quantity or length of the products.

Technical Specifications

Create an array of objects in json in the following configuration:

For example:

[ { "product_name":"product", "product_quantity":1, "product_price":1 }, { "product_name":"product2", "product_quantity":1, "product_price":1 }, { "product_name":"product3", "product_quantity":1, "product_price":1 }, { "product_name":"product4", "product_quantity":1, "product_price":1 }, { "product_name":"product5", "product_quantity":1, "product_price":1 } ]

The object array must be without spaces or line breaks, for example:

[{"product_name":"product","product_quantity":1,"product_price":1},{"product_name":"product2","product_quantity":1,"product_price":1},{"product_name":"product3","product_quantity":1,"product_price":1},{"product_name":"product4","product_quantity":1,"product_price":1},{"product_name":"product5","product_quantity":1,"product_price":1}]

*Encode the object array (URL Encoder)

The encoding must be identical to the encoding of the rawurlencode function in PHP and not similar to the urlencode function in PHP.

The URL encoding cannot contain the character + as the urlencode function does; it encodes spaces as + instead of %20, for example:

%5B%7B%22product_name%22%3A%22product%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product2%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product3%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product4%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product5%22%2C%20%22product_quantity%22%3A1%2C%20%22product_price%22%3A1%7D%5D

Send under the parameter json_purchase_data:

json_purchase_data=%5B%7B%22product_name%22%3A%22product%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product2%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product3%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product4%22%2C%22product_quantity%22%3A1%2C%22product_price%22%3A1%7D%2C%7B%22product_name%22%3A%22product5%22%2C%20%22product_quantity%22%3A1%2C%20%22product_price%22%3A1%7D%5D

Send the data in POST since the browser can decode the encoding and change it.

Examples

<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">
                    <p class="text-center">Choose Amount:</p>
                    <form action="https://direct.tranzila.com/terminal_name/iframenew.php" target="tranzila" method="POST" novalidate="novalidate" autocomplete="off">
                        <div class="form-group">
                            <label for="amount">Amount:</label> <br>
                            <input name="sum" value="5" type="number" id="sum" class="form-control" />
                            <span class="text-danger"></span>
                        </div>
                        <input type="hidden" name="buttonLabel" value="Pay" />

                        <input type="hidden" name="success_url_address" value="https://yoursite.com/success_url_address" />
                        <input type="hidden" name="fail_url_address" value="https://yoursite.com/fail_url_address" />
                        <input type="hidden" name="currency" value="1" />

                        <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>

<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">
                    <p class="text-center">Choose Amount:</p>
                    <form action="https://direct.tranzila.com/terminal_name/iframenew.php" target="tranzila" method="POST" novalidate="novalidate" autocomplete="off">
                        <div class="form-group">
                            <label for="amount">Amount:</label> <br>
                            <input name="sum" value="5" type="number" id="sum" class="form-control" />
                            <span class="text-danger"></span>
                        </div>
                        <input type="hidden" name="buttonLabel" value="Pay" />

                        <input type="hidden" name="bit_pay" value="1" />
                        <input type="hidden" name="success_url_address" value="https://yoursite.com/success_url_address" />
                        <input type="hidden" name="fail_url_address" value="https://yoursite.com/fail_url_address" />
                        <input type="hidden" name="currency" value="1" />

                        <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>

<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">
                    <p class="text-center">Choose Amount:</p>
                    <form action="https://direct.tranzila.com/terminal_name/iframenew.php" target="tranzila" method="POST" novalidate="novalidate" autocomplete="off">
                        <div class="form-group">
                            <label for="amount">Amount:</label> <br>
                            <input name="sum" value="60" type="number" id="sum" class="form-control" readonly />
                            <span class="text-danger"></span>
                        </div>
                        <input type="hidden" name="buttonLabel" value="Pay" />

                        <input type="hidden" name="bit_pay" value="1" />
                        <input type="hidden" name="npay" value="4" />
                        <input type="hidden" name="spay" value="10" />
                        <input type="hidden" name="fpay" value="20" />
                        <input type="hidden" name="cred_type" value="8" />
                        <input type="hidden" name="success_url_address" value="https://yoursite.com/success_url_address" />
                        <input type="hidden" name="fail_url_address" value="https://yoursite.com/fail_url_address" />
                        <input type="hidden" name="currency" value="1" />

                        <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>

<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">
                    <p class="text-center">Choose Amount:</p>
                    <form action="https://direct.tranzila.com/terminal_name/iframenew.php" target="tranzila" method="POST" novalidate="novalidate" autocomplete="off">
                        <div class="form-group">
                            <label for="amount">Amount:</label> <br>
                            <input name="sum" value="60" type="number" id="sum" class="form-control" readonly />
                            <span class="text-danger"></span>
                        </div>
                        <input type="hidden" name="buttonLabel" value="Pay" />

                        <input type="hidden" name="bit_pay" value="1" />
                        <input type="hidden" name="maxpay" value="3" />
                        <input type="hidden" name="cred_type" value="8" />
                        <input type="hidden" name="success_url_address" value="https://yoursite.com/success_url_address" />
                        <input type="hidden" name="fail_url_address" value="https://yoursite.com/fail_url_address" />
                        <input type="hidden" name="currency" value="1" />

                        <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>

<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://direct.tranzila.com/tranzila1/iframenew.php" target="tranzila" method="POST" novalidate="novalidate" autocomplete="off">
            <div class="form-group">
              <input name="sum" type="hidden" value="100" type="number" id="sum" class="form-control" readonly />
              <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" />
            <input type="hidden" name="recur_payments" value="12" />
            <input type="hidden" name="success_url_address" value="https://yoursite.com/success_url_address" />
            <input type="hidden" name="fail_url_address" value="https://yoursite.com/fail_url_address" />
            <input type="hidden" name="currency" value="1" />

            <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>

<script type="text/javascript" src="https://code.jquery.com/jquery-3.6.0.js"></script>
<script>document.write('<script src="https://direct.tranzila.com/js/tranzilanapple_v3.js?v=' + Date.now() + '"><\/script>');</script>
<script>var $n = jQuery.noConflict(true);</script>

<script type="text/javascript" src="https://code.jquery.com/jquery-3.6.0.js"></script> 
<script>document.write('<script src="https://direct.tranzila.com/js/tranzilanapple_v3.js?v=' + Date.now() + '"><\/script>');</script>

<iframe src="https://direct.tranzila.com/myterminal/iframenew.php" allow="payment"></iframe>

<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">
                    <p class="text-center">Choose Amount:</p>
                    <form action="https://direct.tranzila.com/terminal_name/iframenew.php" target="tranzila" method="POST" novalidate="novalidate" autocomplete="off">
                        <div class="form-group">
                            <label for="amount">Amount:</label> <br>
                            <input name="sum" value="5" type="number" id="sum" class="form-control" />
                            <span class="text-danger"></span>
                        </div>
                        <input type="hidden" name="buttonLabel" value="Pay" />

                        <input type="hidden" name="success_url_address" value="https://yoursite.com/success/process.php" />
                        <input type="hidden" name="fail_url_address" value="https://yoursite.com/failure" />
                                                <input type="hidden" name="notify_url_address" value="https://yoursite.com/notify" />
                        <input type="hidden" name="currency" value="1" />
                        <input type="hidden" name="bit_pay" value="1" />

                        <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>

Preventing Duplicate Transactions

DCdisable

The prevention solution is based on a unique value sent for a transaction under the parameter DCdisable. Below are the conditions for using the parameter:

• The solution is intended to work with a Direct IFRAME page.

• You must log into the my.tranzila system and go to the "Additional Fields for Transaction" screen, located under the terminal settings menu, and define only field 20 as the field intended for identifying DCdisable - duplicate charge.

• If it is detected that the unique value in DCdisable has already been used once, no additional charge will be made.

• The check in our DB will be performed up to 24 hours back, at the parent terminal level.

• If a transaction fails the first time, no check will be performed for it on DCdisable. We will display the following message if a duplicate transaction is detected: "This payment has already been made, please contact the business" or "This payment has already been paid. Please contact customer service."

• The customer must pass the DCdisable parameter with a unique value for that transaction.

• The customer must send the parameter u71=1 if working with the Direct page/IFRAME.

• If you have parent and child terminals, you must define the parameter in both the parent and the child.

• We recommend providing a long and complex unique value (the limit for the value is 254 characters).

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.

If the transaction amount changes, and the transaction details are not identical to the data we have stored with the unique identifier, no transaction will be made at all and an error will be received with a unique code.

We recommend implementing and using the HandShake solution to prevent fraudulent transactions.

Handshake is available for use in both iframe and hosted fields payment pages.

Using the HandShake solution requires the purchase of a token module.

1. You must enter the checkout page settings (see "Merchant Checkout Page Setup" section).

2. Enter "Information Security" and mark the HandShake field as enabled.

3. A request for a handshake must be sent before transferring the transaction to the checkout page.

4. When using the Handshake in hosted fields integration, there is no need to make changes in the settings mentioned above.

From the moment the HandShake function is activated, you will not be able to process payments without receiving the HandShake token, meaning, the solution must be fully implemented in order for you to process payments properly.

The URL to perform the handshake is:

https://api.tranzila.com/v1/handshake/create

The Request must be sent in GET

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

The new_process field must be passed to the iframe with a value of 1 so that the checkout page can perform the verification. new_process=1

• 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.

• Attempting to access the checkout page as a standalone action, without prior handshake validation, will result in an error message.

Dtran

The Dtran duplicate transaction prevention mechanism is based on checking transaction data within a time frame defined in the terminal settings.

If you choose to work with this Dtran, you will only need to define the time range without sending a specific parameter.

During the defined time range, our system checks the details of the executed transaction and identifies if there is a duplication for that specific transaction.

Currently, the time range can be set in the old system - secure5 under setting configuration 1:

INSERT SCREENSHOT

Transaction Details Checked for Duplicate Detection:

All transaction fields will be checked - including additional transaction fields

Highlights:

1. This mechanism allows the client to pass the transaction a second time as a duplicate, within the defined time range, and to receive the response a second time with the addition of the parameter - duplicate_transaction_detected which indicates the transaction duplication, which would not be possible with the Dcdisable mechanism.
2. The development works only for transactions sent via API through tranzila71u.cgi or tranzila71pme.cgi
3. Clients working with our clearing page must pass to the clearing page (along with all parameters), also the parameter u71=1
4. If a duplicate transaction is detected and there is already a response from the bank - the response from the duplicate transaction + parameter duplicate_transaction_detected=1 will be returned. If there is still no response from the bank about the original transaction, then 'Response=-96&reason=Double transaction detected. Please contact the company' will be returned
5. The blocked transaction will appear in the terminal as a failure with error 888 - Double transaction blocked.