Direct API Integration

Step 1: VIS Eligibility Check

HTTP Request Method: POST
Resource (URI): {{API-GATEWAY}}/transactions/outlets/outletRef/orders/orderRef/payments/paymentRef/vis/eligibity-check

Headers:

Add these headers to your request, noting that you should replace access_token with the token you received in the previous step.

HeaderValue
AuthorizationBearer access_token
Content-Typeapplication/vnd.ni-payment.v2+json
Acceptapplication/vnd.ni-payment.v2+json

Body:

Either PAN or CardToken is mandatory.

Send PAN for Card Payments

Send CardToken for SavedCardPayment

{
   "pan": "",
   "cardToken": ""
}

Response Body (Sample):

 {
  "transactionAmount": 19000,
  "transactionCurrency": "AED",
  "paymentAccountReference": "V0010013022320223698389178905",
  "matchedPlans": [
    {
      "name": "VISTest6MonthAED",
      "type": "ISSUER_DEFAULT",
      "numberOfInstallments": 6,
      "installmentFrequency": "MONTHLY",
      "termsAndConditions": [
        {
          "url": "https://www.visa.com",
          "version": 2,
          "text": "This is a sample text to describe the terms and conditions that govern the Visa Installment services.",
          "languageCode": "eng"
        },
        {
          "url": "https://www.visa.com",
          "version": 2,
          "text": "هذا نص نموذجي لوصف الشروط والأحكام التي تحكم خدمات أقساط التأشيرة.",
          "languageCode": "ara"
        }
      ],
      "costInfo": {
        "annualPercentageRate": 0,
        "feeInfo": [
          {
            "type": "CONSUMER",
            "ratePercentage": 0,
            "flatFee": 1000
          },
          {
            "type": "MERCHANT_FUNDING",
            "ratePercentage": 0,
            "flatFee": 0
          },
          {
            "type": "MERCHANT_SERVICE",
            "ratePercentage": 10
          }
        ],
        "totalPlanCost": 20000,
        "totalFees": 1000,
        "totalUpfrontFees": 0,
        "totalRecurringFees": 1000,
        "firstInstallment": {
          "upfrontFee": 0,
          "installmentFee": 167,
          "amount": 3167,
          "totalAmount": 3334
        },
        "lastInstallment": {
          "installmentFee": 165,
          "amount": 3165,
          "totalAmount": 3330
        },
        "currency": "AED"
      },
      "vPlanID": "d1c7254a-0ee9-ed76-97e6-10ba2b310101",
      "fundedBy": [
        "CONSUMER"
      ],
      "vPlanIDRef": "00000000CB"
    }
  ],
  "merchantInfo": {
    "category": "5399",
    "merchantReferenceID": null,
    "partnerMerchantReferenceID": "5708129739"
  }
}

📘

Key Notes.

Make the eligibility check as soon as user enter card number

If the matchedPlans has atleast one plan then show the plans below the card input (saved card if it’s COF transaction)

Pay In Full should be the first option

Followed by top 5 plans (max 5 plans needs to be shown)

Follow VISA UX Specs to display the plans. Click here to learn more.

Sample Design

Sample Design

LabelDescription/Value
PAY INnumberOfInstallments
Frequency"WEEKLY" "BIWEEKLY" "MONTHLY" "BIMONTHLY"
Installment amountcostInfo.lastInstallment.totalAmount (convert to major currency)
Instalment ratecostInfo.annualPercentageRate / 100
Processing FeecostInfo.totalUpfrontFees (convert to major currency)


 {
   "matchedCandidates": [
     {
       "cardToken": "",
       "eligibilityStatus": "MATCHED"
     }
   ]
}

Step 2: Card payment (Change in request body)


HTTP Request Method: PUT
Resource (URI): {{API-GATEWAY}}/transactions/outlets/outletRef/orders/orderRef/payments/paymentRef/card

Headers:

Add these headers to your request, noting that you should replace access_token with the token you received in the previous step.

HeaderValue
AuthorizationBearer access_token
Content-Typeapplication/vnd.ni-payment.v2+json
Acceptapplication/vnd.ni-payment.v2+json

📘

Important notes

Send VIS block only if card-holder as shown the plans.

No VIS block if eligiliblity check returns empty matchedPlans

Send VIS block with planSelectionIndicator as false if card-holder has chosen Pay In Full option

Send VIS block with all the fields as listed below, when card-holder has chosen a particular plan.


Request Body:

{
    "pan": "2303779999000275",
    "expiry": "2039-12",
    "cvv": "100",
    "cardholderName": "Mr Something"
    "vis": {
      "planSelectionIndicator": true,
      "vPlanId": "9d16a09e-3812-4ce3-a258-9981cc13a1f3",
      "acceptedTAndCVersion": 2
    }
}

No Changes in the response body.



Step 3: Matched Candidates Check (Only applicable for saved cards)

This API can be used by Direct API merchants when there are multiple saved-cards for a card-holder, and based on the response, Merchant can show Eligible for Installments under the saved-card.

HTTP Request Method: POST
Resource (URI): {{API-GATEWAY}}/transactions/outlets/outletRef/orders/orderRef/payments/paymentRef/vis/matched-candidates

Headers:

Add these headers to your request, noting that you should replace access_token with the token you received in the previous step.

HeaderValue
AuthorizationBearer access_token
Content-Typeapplication/vnd.ni-payment.v2+json
Acceptapplication/vnd.ni-payment.v2+json

Request Body:

{
   "cardNumbers": ["", ""],
   "cardTokens": ["", ""]
}

Response Body:

 {
   "matchedCandidates": [
     {
       "cardToken": "",
       "eligibilityStatus": "MATCHED"
     }
   ]
}

Step 4: Saved card payment (Change in request body)


HTTP Request Method: PUT
Resource (URI): {{API-GATEWAY}}/transactions/outlets/outletRef/orders/orderRef/payments/paymentRef/saved-card

Headers:

Add these headers to your request, noting that you should replace access_token with the token you received in the previous step.

HeaderValue
AuthorizationBearer access_token
Content-Typeapplication/vnd.ni-payment.v2+json
Acceptapplication/vnd.ni-payment.v2+json

Request Body:

Send VIS block only if card-holder is shown the plans. No VIS block if eligiliblity check returns empty matchedPlans. Send VIS block with planSelectionIndicator as false if card-holder has chosen Pay In Full option. Send VIS block with all the fields as listed below, when card-holder has chosen a particular plan.

{
    "cardToken": "2adnad32e037137dadad999afac9000275==",
    "cvv": "100",
     "vis": {
        "planSelectionIndicator": true,
        "vPlanId": "9d16a09e-3812-4ce3-a258-9981cc13a1f3",
        "acceptedTAndCVersion": 2
    }
}

No Changes in the response body.