Loading...
In this Hosted Payment Page (HPP) reference, we present an overview of each request type, examples of request and response values, as well as how to handle them. For more information on Installment Service, see our Overview.
When displaying plan details, you must comply with the messaging options in our Installments Enabled by Visa UX Guide. To download it, see the "Display installment plan details" section of our guide.
The HPP response includes the following plan details. You can display this information on the confirmation page after the purchase is complete.
INS_number_of_installmentsINS_installment_frequencyINS_instalment_payment_amountINS_first_installment_feeINS_total_feesINS_annual_percentage_rateINS_total_plan_costINS_currencyINS_terms_and_conditions_textINS_terms_and_conditions_url| Element/Field | Category | Format | Description |
|---|---|---|---|
| INS_number_of_installments | integer | 1-4 | Maximum number of installments that can be in the plan acceptance created from this plan. |
| INS_installment_frequency | string | enum | Supported tenure types for a plan: WEEKLY (not currently supported) BIWEEKLY (not currently supported) MONTHLY BIMONTHLY (not currently supported) |
| INS_instalment_payment_amount | integer | Sum of cost_info.first_instalment.upfront_fee + cost_info.first_instalment.instalment_fee + cost_info.first_instalment.amount This amount should be in the smallest unit of the required currency (e.g., 2,000 = €20.00). | |
| INS_first_installment_fee | integer | Cost details (fee and principal) for the first instalment. The amount is a numerical value represented in the minor units of the currency (e.g. £6.48 = 648). | |
| INS_total_fees | integer | 1-15 | Total fees charged calculated as totalUpfrontFees + totalRecurringFees. |
| INS_annual_percentage_rate | Number | 1-5 | Annual percentage rate (APR) as configured by the Issuer during plan creation. Not used for calculations; used only for display purposes. Interest-fee rate in percentage applied on installment payment. Percentage rate is a non-negative value. Percentage value is represented with two implicit decimals (e.g., 13.99%). |
| INS_total_plan_cost | integer | 1-15 | Calculated as totalFees + (numberOfInstallments * installmentAmount). |
| INS_currency | string | ISO 4217 | The processing currency of the transaction. See list of Currency Codes. Example: CAD |
| INS_terms_and_conditions_text | string | 1-2000 | Text of the terms and conditions (T&Cs) for the installment plan. |
| INS_terms_and_conditions_url | string | T&Cs HTTPS URL hosted by the Issuer for displaying to the cardholder for acceptance when initiating a plan acceptance for this plan. Must not invoke an executable script and must point to an HTML page containing T&C text in a displayable manner. When provided during onboarding, the URL is checked for validity. Pattern: ^(http)(s?)://0-9a-zA-Z(:(0-9))(/?)([a-zA-Z0-9-.?,'/\+&%$#_=])?$ Example: http://www.myurl.com |
You can filter installment plans by sending the following filter parameters in the request:
HPP_PLAN_TYPEHPP_MAX_TERM_MONTHS_MERCHANT_FUNDEDHPP_AMOUNT_THRESHOLDIf available, up to two installment plans will be displayed on the HPP.
In the following example, both plans are CONSUMER_FUNDED on the HPP if available for a specific user.
{
"TIMESTAMP": "20240311160300",
"MERCHANT_ID": "vayuvisa",
"ACCOUNT": "installment",
"CURRENCY": "CAD",
"AMOUNT": "45000",
"ORDER_ID": "853f6574-b02c-4cae-8e14-26506ab69809",
"AUTO_SETTLE_FLAG":"0",
"HPP_PLAN_TYPE":"CONSUMER_FUNDED",
"HPP_MAX_TERM_MONTHS_MERCHANT_FUNDED":"",
"HPP_AMOUNT_THRESHOLD":"",
"SHA1HASH": "7c5be41124b37c40f3b8851ad2dd1bc11a70a972"
}Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.
Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]
| Element/Field | Type | Description |
|---|---|---|
| HPP_PLAN_TYPE | O | Used to filter installment plans based on plan type. Allowed values: MERCHANT_FUNDED (if sent, will return merchant funded plans only) CONSUMER_FUNDED (if sent, will return consumer funded plans only) HYBRID_FUNDED (if sent, will return both merchant and consumer funded plans) BILATERAL (if sent, will return BILATERAL plans only) ANY (if sent, returns two plans from all available plans) (default) Note: If not present, request will be sent with default value. |
| HPP_MAX_TERM_ MONTHS_MERCHANT_FUNDED | O | Used to retrieve installment plans with specific tenure. Applicable to all plan types. Should accept numbers only; max length is 4 digits. For example: max_term_months_merchant_funded = 12 A value of 12 sent means that: –Only plans with tenure ≤ 12 months are retrieved. –Merchant-funded plans with tenure > 12 months are not returned. Default: 1,000 Note: If not present, request will be sent with default value. |
| HPP_AMOUNT_ THRESHOLD | O | Used to determine whether to return the longest or shortest tenure/duration plans depending on the amount sent. Should accept numbers only; max length is 15 digits. The amount should be sent in the smallest unit of the required currency (e.g., 2,000 = €20.00). For example, a 50,000 value sent means that: –For transactions < €500.00, plans with the shortest tenure are displayed first. –For transactions >= €500.00, plans with the longest tenure are displayed first. Note: If not present, requests will be sent with default value: plans with the longest tenure. |