Visa Installments

To learn more about Visa Installments, please refer to link

Before initiating the payment request you will need to get the eligible installment plans. For this purpose you have to send an action request to the REST API. The following fields are required in the request:

Field name	M/O/C	Description
`requestType`	M	Use value 'PaymentCardInstallmentRequest' if card is used Use value 'PaymentTokenInstallmentEligibilityRequest' if hosted data is used Use value 'PaymentCardProtectedInstallmentEligibilityRequest' if encrypted card data is used
`paymentCard.number`	C	If clear card number is used
`paymentToken.value`	C	If the eligibility check should be handled for a token linked to a card.
`paymentCardEncrypted....`	C	If eligibility call is initiated from POS, card data must be send as described in the guide for transactions initiated from POS
`storeId`	O	The store ID for which the eligibility call is initiated.
`amount.total`	M	Amount for which the eligibility call is initiated.
`amount.currency`	M	Currency of the card for which the eligibility call is initiated.

If the transaction is eligible for Visa installments, then one to many plans will be included with the following objects:

Field name	Presence	Description
`installmentPlanId`	M	This objects contains the reference to the installment plan defined by Visa.
`InstallmentPlanInquiryId`	M	Contains plan ID generated by the Gateway.
`provider`	M	Service provider of the individual installment plan
`tenure`	M	Number of installments of the individual installment plan
`installmentFrequency`	M	Frequency of the individual installment plan. Possible values: WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY
`interestRate`	M	Interest rate of the individual installment plan
`currency`	M	3-digit ISO Alpha code currency code of the individual installment plan
`installmentFee`	M	Processing fee by the Issuer
`totalFee`	M	This is the complete set of Fees, which includes, recurring fees, processing fees, upfront fees etc.
`amountPerInstallment`	M	Total amount payable by the customer per installment
`termsAndConditionText`	M	Terms and conditions to be displayed and acknowledged by the customer.
`termsAndConditionVersion`	M	Related version of the terms and conditions.
`additionalTermsAndConditionsURL`	C	Additional terms and conditions to be displayed and acknowledged by the customer.
`productCode`	C	Bank defined product code. Only applicable for APAC region.
`programCode`	C	Bank defined program code. Only applicable for APAC region.
`languageCode`	M	Language of terms and conditions
`bankName`	C	Available bank name for respective BIN. Only present for specific banks in APAC region.
`bankCode`	C	Available bank code for respective BIN. Only present for specific banks in APAC region.
`installmentMerchantId`	C	Only present for specific banks in APAC region with multi MID setup for installments.
`installmentTerminalId`	C	Only present for specific banks in APAC region with multi MID setup for installments.

Example:

{
    "requestType": "PaymentCardInstallmentRequest",
    "paymentCard": {
        "number": "45093xxxx0012535"
    },
    "storeId": "470xxx9111",
    "amount": {
        "total": "2500",
        "currency": "HKD"
    }
}

{
    "type": "GetInstallmentPlansResponse",
    "clientRequestId": "2838649",
    "apiTraceId": "ljklkjlkjasdflkjlkj123",
    "installmentPlans": [
        {
            "installmentPlanInquiryId": "asdf4617-c2c7-03f0-5028-1332aa5b5678",
            "installmentPlanId": "a2a44617-c2c7-03f0-5028-1332aa5bd601",
            "provider": "VIS",
            "tenure": 12,
            "interestRate": 0,
            "currency": "HKD",
            "installmentFee": 0.00,
            "totalFee": 0.00,
            "amountPerMonth": 208.34,
            "totalAmount": 2500.00,
            "termsAndConditionText": "Test",
            "termsAndConditionVersion": "1",
            "languageCode": "eng",
            "bankName": "Standard Chartered Bank",
            "bankCode": "003"
        },
        {
            "installmentPlanInquiryId": "asdf4617-c2c7-03f0-5028-1332aa5b5679",
            "installmentPlanId": "f173c504-d012-6a45-1032-106f2b77f701",
            "provider": "VIS",
            "tenure": 3,
            "interestRate": 0,
            "currency": "HKD",
            "installmentFee": 0.00,
            "totalFee": 0.00,
            "amountPerMonth": 833.34,
            "totalAmount": 2500.00,
            "termsAndConditionText": "Test TC text",
            "termsAndConditionVersion": "2",
            "languageCode": "eng",
            "bankName": "Standard Chartered Bank",
            "bankCode": "003"
        },
        {
            "installmentPlanInquiryId": "asdf4617-c2c7-03f0-5028-1332aa5b5680",
            "installmentPlanId": "bd14019e-b3f7-e486-fdec-118f2944ed01",
            "provider": "VIS",
            "tenure": 6,
            "interestRate": 0,
            "currency": "HKD",
            "installmentFee": 0.00,
            "totalFee": 0.00,
            "amountPerMonth": 416.67,
            "totalAmount": 2500.00,
            "termsAndConditionText": "Test",
            "termsAndConditionVersion": "1",
            "languageCode": "eng",
            "bankName": "Standard Chartered Bank",
            "bankCode": "003"
        },
        {
            "installmentPlanInquiryId": "asdf4617-c2c7-03f0-5028-1332aa5b5681",
            "installmentPlanId": "7a27924d-70c8-9451-882c-1f1cbd54a301",
            "provider": "VIS",
            "tenure": 9,
            "interestRate": 0,
            "currency": "HKD",
            "installmentFee": 0.00,
            "totalFee": 0.00,
            "amountPerMonth": 277.78,
            "totalAmount": 2500.00,
            "termsAndConditionText": "Test",
            "termsAndConditionVersion": "1",
            "languageCode": "eng",
            "bankName": "Standard Chartered Bank",
            "bankCode": "003"
        }
    ]
}

Once you have received the eligible installment plans from the Gateway, you can display the list of plans to the cardholder.

If the cardholder chooses one of the installment plans, then you have to include the selected plan into the payment request to the Gateway. Otherwise, you don't need to include any information into the payment request.

Example:

{
    "requestType": "PaymentCardSaleTransaction",
    "transactionAmount": {
        "total": "4000",
        "currency": "HKD"
    },
    "paymentMethod": {
        "paymentCard": {
            "number": "45093xxxx0012535",
            "securityCode": "979",
            "expiryDate": {
                "month": "12",
                "year": "24"
            }
        }
    },
    "order": {
        "selectedInstallmentPlan": {
            "installmentPlanId": "a2a44617-c2c7-03f0-5028-1332aa5bd601",
            "provider": "VIS",
            "tenure": 12,
            "interestRate": 0,
            "currency": "HKD",
            "installmentFee": 0.00,
            "totalFee": 0.00,
            "amountPerMonth": 208.34,
            "totalAmount": 2500.00,
            "termsAndConditionText": "Test",
            "termsAndConditionVersion": "1",
            "languageCode": "eng",
            "bankName": "Standard Chartered Bank",
            "bankCode": "003"
        }
    }
}

{
    "type": "transactionResponse",
    "clientRequestId": "2838649",
    "apiTraceId": "ljklkjlkjasdflkjlkj123",
    "ipgTransactionId": "84370670021",
    "orderId": "R-75b190bc-64f3-48e9-95dc-5338427e070c",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "VISA",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "12",
                "year": "2024"
            },
            "bin": "450936",
            "last4": "2535",
            "brand": "VISA"
        },
        "paymentMethodType": "PAYMENT_CARD",
        "paymentMethodBrand": "VISA"
    },
    "country": "Hong Kong",
    "terminalId": "00001137",
    "merchantId": "620000000001137",
    "transactionTime": 1722924804,
    "approvedAmount": {
        "total": 4000.00,
        "currency": "HKD",
        "components": {
            "subtotal": 4000.00
        }
    },
    "transactionAmount": {
        "total": 4000.00,
        "currency": "HKD",
        "components": {
            "subtotal": 4000.00
        }
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:234567:4370670021:PPX :421906960021",
    "processor": {
        "referenceNumber": "421906960021",
        "authorizationCode": "234567",
        "responseCode": "00",
        "responseMessage": "Function performed error-free",
        "avsResponse": {
            "streetMatch": "NO_INPUT_DATA",
            "postalCodeMatch": "NO_INPUT_DATA"
        }
    },
    "selectedInstallmentPlan": {
        "installmentPlanId": "a2a44617-c2c7-03f0-5028-1332aa5bd601",
        "provider": "VIS",
        "tenure": 12,
        "interestRate": 0,
        "amountPerMonth": 208.34,
        "totalAmount": 2500.00
    }
}

API Products

Point of Sale

Developer

Resources