Installments
Coming soon
This feature is only available in Middle East region and limited to certain acquirers.
This feature can only be used if your account has been enabled with the respective service.
To utilize installments on a terminal that connects to the Gateway using the nexo acquirer protocol (v6), the following steps must be performed.
To retrieve the eligible installment plans from the Gateway, the terminal needs to send a modified version of balance inquiry (Acceptor Authorisation Request).
| Field | Presence | Value |
|---|---|---|
MsgFctn | M | AUTQ |
Tx/TxId | M | Same value needs to be used in subsequent sale transaction |
Card/CardBrnd | M | Card brand identified by the terminal. As of now, only 'V' for VISA is supported. |
Cntxt/PmtCntxt/CardPres | M | true |
Cntxt/PmtCntxt/CrdhldrPres | M | true |
Tx/TxDtls/TtlAmt | M | |
Tx/TxDtls/Ccy | M | |
Tx/TxDtls/AmtQlfr | M | ACTL Note: Only sale is support. |
Tx/TxCaptr | M | false |
Tx/TxType | M | BALC |
CardDataNtryMd | M | |
AttndncCntxt | M | ATTD |
OrgnlTx | - | not present |
AddtlTxData | M | /Installlment/EligablePlansQuery |
The Gateway sends the balance inquiry response (Acceptor Authorisation Response) to the terminal.
| Field | Presence | Value |
|---|---|---|
MsgFctn | M | AUTP |
Tx/TxDtls/TtlAmt | M | |
Tx/TxDtls/Ccy | M | |
Tx/TxDtls/AmtQlfr | M | ACTL |
RspnToAuthstn/Rspn | M | 'APPR' in case there are 1 or more eligible installment plans 'DECL' in case there's no eligible installment plan |
RspnToAuthstn/RspnRsn | M | Response code + text |
TxRspn/AuthstnRslt/RspnToAuthstn/AddtlRspnInf | M | /InstallmentPlanQueryResult (even present in case of RspnToAuthstn/Rspn='DECL') |
CmpltnReqrd | M | false |
Bal | - | not present |
Actn | C | Not present if RspnToAuthstn/Rspn='DECL'One occurence per eligible installment plan with: ActnTp='DISP'MsgToPres/MsgDstn='CDSP'MsgToPres/Frmt='TEXT'MsgToPres/MsgCntt= see below key value pair as JSON structure |
JSON structure:
Subfield of MsgToPres/MsgCntt | Description | Type | Example |
|---|---|---|---|
installmentPlanInquiryId | Gateway internal reference to the plan. Needs to be used in subsequent sale request to chose an installment plan | string, max length 50 | asdf4617-c2c7-03f0-5028-1332aa5b5678 |
installmentPlanID | Identifier for an installment plan generated by installment provider | string, max length 36 | a2a44617-c2c7-03f0-5028-1332aa5bd601 |
installmentProvider | Service provider of the installment plans As of now, only Visa Installment Service is supported. | string, max length 10 | In case of Visa Installment Service: 'VISA' |
planDetails.numberOfInstallments | Number of installments | number, fixed length 4 | 0005 |
planDetails.installmentFrequency | Frequency of the installments | enum Possible values: weekly biweekly monthly bimonthly | monthly |
planDetails.annualInterestRate | Interest rate per year (in percentage) | number, max length 5 | 5.4 |
planDetails.currency | Currency of amounts | ISO 4217 - currency code | AED |
planDetails.oneTimeFeeAmount | One time installment fee amount | number, max length 15, decimal places depending on 'Currency' | 123.55 |
planDetails.totalFeeAmount | Sum of all fees | number, max length 15, decimal places depending on 'Currency' | 456.87 |
planDetails.rateAmount | Recurring rate | number, max length 15, decimal places depending on 'Currency' | 2233.44 |
termsAndConditions.text | Terms and conditions provided by issuer of the installment plan | string, max length 2000 | Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. |
termsAndConditions.url | A Terms and Conditions HTTPS URL hosted by the Issuer for displaying to the cardholder for acceptance when initiating a plan acceptance for this plan. | string, max length 1000 | https://example-url.com |
termsAndConditions.language | Language of 'TermsAndConditionsText' | ISO 639-2 - language code | eng |
termsAndConditions.version | Version of the Terms & Conditions accepted by the consumer. | string, max length 10 | 1.0 |
islamicPlan | Indicates whether the plan is an Islamic Plan. If this field is set to true, the plan should be displayed according to Shariah Banking principles, for example using the term profit instead of interest. | boolean | false |
Example:
{
"installmentPlanInquiryId":"asdf4617-c2c7-03f0-5028-1332aa5b5678",
"installmentPlanID":"a2a44617-c2c7-03f0-5028-1332aa5bd601",
"installmentProvider":"VISA",
"planDetails":{
"numberOfInstallments":"0005",
"installmentFrequency":"monthly",
"annualInterestRate":5.4,
"currency":"eng",
"oneTimeFeeAmount":123.55,
"totalFeeAmount":456.87,
"rateAmount":2233.44
},
"termsAndConditions:{
"text":"abc",
"url":"https://xyz.com",
"language":"eng";
"version":"1.0"
},
"islamicPlan":false
}
Terminal sends sale request (Acceptor Authorisation Request) with a reference to the chosen installment plan.
Its' no required to send all plan detail in the sale request. If no plan was chosen by the cardholder, then terminal sends a standard sale request without any additional information.
| Field | Presence | Value |
|---|---|---|
Tx/TxCaptr | M | true |
Tx/TxId | M | Tx/TxId used in balance inquiry request (Acceptor Authorisation Request) for the retrieval of eligible installment plans |
AddtlTxData | C | /installment/installmentProvider/installmentPlanInquiryId(values to be used from balance inquiry response) |
Updated 3 days ago
