---
updatedAt: 2026-02-26T13:08:33.000Z
agentTools:
  projectIndex: https://docs.ngenius-payments.com/llms.txt
---

# 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.

| Header        | Value                              |
| :------------ | :--------------------------------- |
| Authorization | Bearer `access_token`              |
| Content-Type  | application/vnd.ni-payment.v2+json |
| Accept        | application/vnd.ni-payment.v2+json |

## Body:

Either PAN or CardToken is mandatory.

Send PAN for Card Payments

Send CardToken for SavedCardPayment

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

<br />

## 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"
  }
}
```

<br />

> 📘 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](https://www.merchantsignage.visa.com/brand_guidelines) to learn more.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/fc73758-Screenshot_20240626_083240_payment.sdk.android.demo.jpg",
        "",
        "Sample Design"
      ],
      "align": "center",
      "sizing": "25% ",
      "border": true,
      "caption": "Sample Design"
    }
  ]
}
[/block]

| Label              | Description/Value                                                |
| :----------------- | :--------------------------------------------------------------- |
| PAY IN             | numberOfInstallments                                             |
| Frequency          | "WEEKLY" "BIWEEKLY" "MONTHLY" "BIMONTHLY"                        |
| Installment amount | costInfo.lastInstallment.totalAmount (convert to major currency) |
| Instalment rate    | costInfo.annualPercentageRate / 100                              |
| Processing Fee     | costInfo.totalUpfrontFees (convert to major currency)            |

<br />

<br />

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

# Step 2: Card payment (Change in request body)

<br />

**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.

| Header        | Value                              |
| :------------ | :--------------------------------- |
| Authorization | Bearer `access_token`              |
| Content-Type  | application/vnd.ni-payment.v2+json |
| Accept        | application/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.

<br />

## 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.

<br />

<br />

# 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.

| Header        | Value                              |
| :------------ | :--------------------------------- |
| Authorization | Bearer `access_token`              |
| Content-Type  | application/vnd.ni-payment.v2+json |
| Accept        | application/vnd.ni-payment.v2+json |

## Request Body:

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

## Response Body:

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

<br />

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

<br />

**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.

| Header        | Value                              |
| :------------ | :--------------------------------- |
| Authorization | Bearer `access_token`              |
| Content-Type  | application/vnd.ni-payment.v2+json |
| Accept        | application/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
    }
}
```

<br />

> No Changes in the response body.