Instalment

1. Purpose and Scope

This guide explains how an Online merchant can:

Query the instalment plans available for the On-us card.

Display eligible plans, fees, and repayment amounts to the cardholder.

Submit an Online payment using the plan selected by the cardholder.

Combine +FUN$ points redemption with instalment payment when that service is enabled.

Handle inquiry failures, payment timeouts, reversals, cancellation, and the current refund limitation.

The solution applies only to eligible On-us cards issued by Acquirer and to merchants enabled for the instalment service.

2. Solution Overview

The Online checkout consists of two separate business steps:

Instalment Plan Inquiry — the merchant submits the card or token and transaction amount. The service returns the eligible plans configured for that merchant and transaction.

Instalment Payment — after the cardholder selects a plan, the merchant submits a payment request that references both the original inquiry and the selected instalmentPlanID.

A typical flow is:

The instalment plan is determined by Acquirer configuration, which may include card BIN, transaction floor limit, scenario, tenor, and handling-fee rate. Supported configurable tenors are 3, 6, 9, 12, 24, etc months. A particular transaction may receive only a subset of those tenors, or no eligible plans.

3. Instalment Plan Inquiry

3.1 Inquiry request fields

JSON path	Required	Format / values	Merchant instruction
`merchantTransInfo.merchantTransID`	Yes	String, max 32	Unique merchant ID for this inquiry. Preserve it for the payment request.
`merchantTransInfo.merchantTransTime`	Yes	ISO 8601	Merchant transaction time.
`paymentMethod.type`	Yes	`card` or `token`	Select the matching card-data path.
`paymentMethod.encryptedCardInfo`	Conditional	Encrypted payload	Use for a merchant without PCI DSS certification.
`paymentMethod.cardInfo.cardNumber`	Conditional	PAN	Only for a PCI DSS-certified merchant. Do not use a real PAN in logs or test documents.
`paymentMethod.token.type`	Conditional	`gatewayToken` or `merchantToken`	Applies when `type` is `token`; defaults to `gatewayToken` if omitted. Explicitly sending it is recommended.
`paymentMethod.token.value`	Conditional	String	Required when `paymentMethod.type` is `token`.
`transAmount.currency`	Yes	ISO 4217, e.g. `HKD`	Transaction currency.
`transAmount.value`	Yes	Major-unit amount string, max 12	Send the net amount after +FUN$ deduction when points are redeemed.
`transInitiator.paymentScenario`	Yes	`EC` for E-commerce	Always send `EC` explicitly. The source notes an `EC` default if omitted, but explicit submission avoids ambiguity.
`metadata`	No	String, max 512	Echoed in the response; do not place sensitive card data in it.

3.2 Response

A successful response contains an overall result and an InstalmentPlanInquiry object. The exact outer envelope may follow the current EVO payment API contract. Refer to specification.

4. Instalment Payment

4.1. Relationship to the inquiry

The payment extends the existing Payment API. It must identify the transaction as an instalment trade and reference:

the original inquiry’s merchantTransID; and

the exact instalmentPlanID selected by the cardholder.

The card/payment token and amount should remain consistent with the inquiry. If the purchase amount, points redemption, card, currency, or other eligibility input changes, perform a new inquiry and ask the cardholder to select from the newly returned plans.

4.2 Required instalment extension fields

JSON path	Required for instalment	Value / instruction
`origMerchantTransInfo.merchantTransID`	Yes	`merchantTransInfo.merchantTransID` from the original Instalment Plan Inquiry.
`tradeInfo.tradeType`	Yes	`Instalment`
`tradeInfo.tradeTypeInfo.instalmentPlanID`	Yes	Plan ID selected from the inquiry response.

Other payment fields follow the merchant’s approved Payment API integration. The source payment sample also contains merchantTransInfo, card details, transAmount, transInitiator.platform, metadata, webhook, allowAuthentication, authenticationOnly, captureAfterHours, and returnURL. Their exact requirements and behavior are not redefined by the instalment source; use the current Payment API specification agreed during onboarding.

4.3 Payment response

The Payment API response adds payment.instalment:

{
  "payment": {
    "status": "{paymentStatus}",
    "instalment": {
      "instalmentPlanID": "{selectedPlanId}",
      "tenor": 12,
      "handlingFeeRate": "{rateFromResponse}",
      "totalAmount": "{totalAmountFromResponse}",
      "totalFee": "{totalFeeFromResponse}",
      "monthlyAmount": "{monthlyAmountFromResponse}"
    }
  }
}

1. Purpose and Scope#

2. Solution Overview#

3. Instalment Plan Inquiry#

3.1 Inquiry request fields#

3.2 Response#

4. Instalment Payment#

4.1. Relationship to the inquiry#

4.2 Required instalment extension fields#

4.3 Payment response#