Adding Installments to the Payment Page

It is common practice for Israeli credit card companies to offer splitting payments into multiple installments. You, as a merchant, can take advantage of this by offering installments to the customer on the payment page.

There are two types of installments:

1. Regular installments. If you owe ₪X for the transaction, it's broken up into multiple installments where every month an equal portion of X gets charged to your card. These incur no interest.

2. Credit installments. If you owe ₪X for the transaction, it's broken up into 3 or more installments where every month you owe a portion of X plus interest on X.

There is no need for you, as a merchant, to handle these installments; they are completely managed by the credit card company. As long as the transaction has been created with installments, the credit card company is responsible for processing the charges.

Prerequisites

Newly opened terminals support installments by default.

In rare cases, installment transactions get declined due to a lack of payment permissions from credit card companies. If this happens, please get in touch with Hyp support.

Payment page integration

To enable installments on the payment page, you make a regular payment page request where:

• The creditType element is set to Payments to enable regular installments, or SpecialCredit to enable credit installments.

• The numberOfPayments element is added, specifying the maximum number of installments you want to offer to the customer. If creditType is set to SpecialCredit, then numberOfPayments must be 3 or more.

Here's an example of a payment page request that enables regular installments with a maximum of 6 installments:

<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>doDeal</command>
        <doDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <cardNo>CGMPI</cardNo>
            <total>{total}</total>
            <transactionType>Debit</transactionType>
            <creditType>Payments</creditType>
            <numberOfPayments>6</numberOfPayments>
            <currency>ILS</currency>
            <transactionCode>Internet</transactionCode>
            <validation>TxnSetup</validation>
            <mid>{mid}</mid>
            <uniqueid>{uniqueid}</uniqueid>
            <mpiValidation>AutoComm</mpiValidation>
            <successUrl>{successUrl}</successUrl>
            <errorUrl>{errorUrl}</errorUrl>
        </doDeal>
    </request>
</ashrait>

This is an example of a payment page request that enables credit installments with a maximum of 10 installments:

<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>doDeal</command>
        <doDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <cardNo>CGMPI</cardNo>
            <total>{total}</total>
            <transactionType>Debit</transactionType>
            <creditType>SpecialCredit</creditType>
            <numberOfPayments>10</numberOfPayments>
            <currency>ILS</currency>
            <transactionCode>Internet</transactionCode>
            <validation>TxnSetup</validation>
            <mid>{mid}</mid>
            <uniqueid>{uniqueid}</uniqueid>
            <mpiValidation>AutoComm</mpiValidation>
            <successUrl>{successUrl}</successUrl>
            <errorUrl>{errorUrl}</errorUrl>
        </doDeal>
    </request>
</ashrait>

Payment experience

When the customer opens the payment page, it will contain a drop-down allowing them to choose the number of installments, up to the maximum number you've defined in your payment page request.

For regular installments, the payment page automatically calculates and displays the amount of each installment:

Payment page with 6 regular installments selected

For credit installments, the payment page only shows the number of installments, as the interest rate applied to each installment is not known in advance:

Payment page with 6 credit installments selected

Using installments in direct charge and two-phase commit

When you perform a direct charge (without showing the payment page) or send an approval request in a two-phase commit, your approval request needs to explicitly contain additional elements. The set and meaning of these elements depend on whether you're using regular or credit installments.

Regular installments

With regular installments (creditType is set to Payments), the request must include:

• firstPayment: the amount of the first payment in the installment series, specified in currency subunits such as cents or agorot.

• periodicalPayment: the amount of each subsequent payment in the installment series, specified in currency subunits such as cents or agorot.

• numberOfPayments: instead of indicating the maximum allowed number of payments, this element indicates the actual number of periodical payments requested, not including the first payment. For example, to split the transaction into a total of 6 regular installments (1 first payment and 5 periodical payments), set numberOfPayments to 5.

Credit installments

With credit installments (creditType is set to SpecialCredit), the request must include:

• periodicalPayment: the amount of each payment in the credit installment series, specified in currency subunits such as cents or agorot. Credit installments do not have a first payment, so this is the only payment amount.

• numberOfPayments: the actual number of payments requested.