KNET Gateway
Overview
KNET is the primary card-based payment method in Kuwait. All debit cards issued in the country must carry the KNET brand. Of the 5 million cards issued, 80 percent are debit cards and therefore KNET cards.
KNET uses the latest information and e-commerce technology on the payment gateway. It applies advanced safety and security measures to protect users from hacking and related threats.
KNET allows customers to make purchases using any local debit card issued by member banks of Kuwait.
For more information, refer to KNET.
Prerequisites
To offer the KNET payment method through the Mastercard Gateway:
- Establish a merchant account with a member bank that participates in the KNET payment gateway. Obtain your KNET merchant ID (MID) and credentials. These details are required to register your domain and CNAME.
- Register with your Mastercard Gateway service provider and share your KNET MID, credentials, domain, and CNAME.
- Ask your acquirer to configure your merchant profile on the Mastercard Gateway to enable KNET acceptance.
Contact your local product team for additional support.
KNET payer journey flow
The following stages describe the KNET payer journey:
- Consumers must:
- Select products or services.
- Complete the checkout process.
- Provide basic customer information, such as first name, last name, email address, telephone number, and address details.
- Select KNET as the payment option.
- The browser redirects the consumer to the KNET page.
- The consumer enters card details and authenticates the payment.
- The browser redirects the consumer to your page with the final payment status.
If the payment is unsuccessful, the consumer can retry using another payment method.
KNET does not support the AUTHORIZATION and CAPTURE model. It supports only the PAY model.
KNET integration
KNET through direct payment
- Direct payment integration enables you to offer KNET on your checkout page.
- KNET is supported from API version 100 and later.
- Submit an Initiate Browser Payment request where:
sourceOfFunds.browserPayment.type = KNETbrowserPayment.operation = PAY
KNET transactions
| Transaction details | Value |
|---|---|
| Payment type | Debit Switch Gateway |
| Supported countries | Kuwait |
| Supported currencies | KWD |
| Supported operations | Purchase (PAY), PARTIAL REFUND, REFUND |
| Refund validity | Refunds cannot be issued after 90 days from the purchase date, as per KNET guidelines. |
| Chargeback | Not applicable |
Specific parameter fields
In addition to the standard fields required in a browser payment request, include the following parameters in the Initiate Browser Payment request for KNET:
| Parameter name | Mandatory or optional | Description |
|---|---|---|
| order.amount | Mandatory | Specifies the transaction amount. |
| order.currency | Mandatory | Specifies the transaction currency. |
| order.notificationUrl | Mandatory | Specifies the notification URL. |
| sourceOfFunds.type | Mandatory | Specifies the source of funds. |
| sourceOfFunds.browserPayment.type | Mandatory | Specifies the browser payment type. |
| browserPayment.operation | Mandatory | Specifies the payment operation. |
Initiate KNET payment request
{
"apiOperation": "INITIATE_BROWSER_PAYMENT",
"billing": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "KWT",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive",
"postcodeZip": "2000"
}
},
"shipping": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "KWT",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive",
"postcodeZip": "2000"
}
},
"browserPayment": {
"operation": "PAY",
"returnUrl": "https://qa06.gateway.mastercard.int/api/documentation/integrationGuidelines/index.html"
},
"customer": {
"account": {
"id": "customerAccount"
},
"dateOfBirth": "1xx9-1x-x1",
"email": "axxsh.maxxli@mxxd.com",
"firstName": "Axxsh",
"lastName": "Maxxi",
"mobilePhone": "07792xxxx55",
"nationalId": "nationalId1",
"phone": "9898xxxx98"
},
"order": {
"reference": "TEST-SUCCEED",
"amount": "90.00",
"itemAmount": "90.00",
"currency": "KWD",
"item": [
{
"detail": {
"unitTaxRate": "0"
},
"name": "Spud",
"quantity": "1",
"unitPrice": "45",
"unitTaxAmount": "0.02",
"unitDiscountAmount": "0.03",
"description": "item1 description",
"sku": "item1"
},
{
"detail": {
"unitTaxRate": "0"
},
"name": "item2",
"quantity": "1",
"unitPrice": "45",
"unitTaxAmount": "0.02",
"unitDiscountAmount": "0.03",
"description": "item2 description",
"sku": "item2"
}
],
"shippingAndHandlingAmount": "0.02",
"taxAmount": "0.04",
"description": "apmspi test order"
},
"sourceOfFunds": {
"browserPayment": {
"type": "KNET"
},
"type": "BROWSER_PAYMENT"
}
}
Initiate KNET payment response
{
"billing": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "KWT",
"postcodeZip": "2000",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive"
}
},
"browserPayment": {
"interaction": {
"status": "INITIATED",
"timeInitiated": "2024-10-09T15:34:34.203Z"
},
"operation": "PAY",
"redirectHtml": "<div id=\"initiateRedirect\" xmlns=\"http://www.w3.org/1999/html\"><iframe srcdoc=\"<script src='https://drogon.ottu.dev/b/checkout/redirect/start/?session_id=713b7f6a052d431d84f5a98c1ab743cb79f94c38&pg_code=KNET'>window.top.location.href='https://drogon.ottu.dev/b/checkout/redirect/start/?session_id=713b7f6a052d431d84f5a98c1ab743cb79f94c38&pg_code=KNET';</script>\" id=\"redirectFrame\" name=\"redirectFrame\" height=\"100%\" width=\"100%\"></iframe></div>",
"returnUrl": "https://mtf.gateway.mastercard.com/api/documentation/integrationGuidelines/index.html"
},
"customer": {
"account": {
"id": "customerAccount"
},
"email": "axxsh.mxxli@txx.com",
"firstName": "Axxsh",
"lastName": "Mxxli",
"mobilePhone": "07792xxxx55",
"nationalId": "nationalId1",
"phone": "9898xxxx98"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TEST_MERCHANT",
"order": {
"amount": 90,
"chargeback": {
"amount": 0,
"currency": "KWD"
},
"creationTime": "2024-10-09T15:34:34.081Z",
"currency": "AED",
"description": "apmspi test order",
"discount": {
"amount": 30
},
"id": "5699400641",
"item": [
{
"description": "item1 description",
"detail": {
"unitTaxRate": 0
},
"name": "Spud",
"quantity": 1,
"sku": "item1",
"unitDiscountAmount": 10,
"unitPrice": 20,
"unitTaxAmount": 10
},
{
"description": "item2 description",
"detail": {
"unitTaxRate": 0
},
"name": "item2",
"quantity": 2,
"sku": "item2",
"unitDiscountAmount": 10,
"unitPrice": 20,
"unitTaxAmount": 10
}
],
"itemAmount": 60,
"lastUpdatedTime": "2024-10-09T15:34:35.703Z",
"merchantAmount": 70,
"merchantCurrency": "AED",
"reference": "TEST-SUCCEED",
"shippingAndHandlingAmount": 10,
"status": "INITIATED",
"taxAmount": 30,
"totalAuthorizedAmount": 0,
"totalCapturedAmount": 0,
"totalDisbursedAmount": 0,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "ACCEPTED",
"gatewayCode": "SUBMITTED",
"gatewayRecommendation": "NO_ACTION"
},
"result": "SUCCESS",
"shipping": {
"address": {
"city": "Edinburgh",
"company": "MPGS",
"country": "KWT",
"postcodeZip": "2000",
"stateProvince": "Scotland",
"street": "OceanPoint",
"street2": "OceanDrive"
}
},
"sourceOfFunds": {
"browserPayment": {
"type": "KNET"
},
"type": "BROWSER_PAYMENT"
},
"timeOfLastUpdate": "2024-10-09T15:34:35.703Z",
"timeOfRecord": "2024-10-09T15:34:34.194Z",
"transaction": {
"acquirer": {
"id": "OTTU_SPI",
"merchantId": "drogon-ottu-dev"
},
"amount": 70,
"currency": "KWD",
"id": "4551482213",
"source": "INTERNET",
"stan": "0",
"type": "PAYMENT"
},
"version": "100"
}
Interpretation of the transaction result
The following table explains the possible transaction response codes after initiating a KNET payment.
| Initiate browser payment response | Result | What this means |
|---|---|---|
response.gatewayCode=SUBMITTED |
SUCCESS |
Redirect the payer using the URL provided in the response. |
| Retrieve transaction or Retrieve order response | Result | What this means |
|---|---|---|
response.gatewayCode = APPROVED |
SUCCESS |
The payment is successful. |
response.gatewayCode = PENDING |
PENDING |
The Mastercard Gateway is waiting for a notification from the acquirer about the payment result. Try RETRIEVE_TRANSACTION again later or listen for notifications from the Mastercard Gateway. |
response.gatewayCode = CANCELLED |
FAILURE |
The payer cancelled the interaction for this payment. |
response.gatewayCode = DECLINED or ACQUIRER_SYSTEM_ERROR |
FAILURE |
The payment was declined. Offer the payer another payment method. If the response is ACQUIRER_SYSTEM_ERROR, contact the acquirer for the reason or try RETRIEVE_TRANSACTION again. |
response.gatewayCode = TIMED_OUT |
FAILURE |
Treat this as a declined payment. The Mastercard Gateway ensures the transaction is not successful or will reverse it. |
KNET through hosted checkout
Hosted Checkout integration enables you to collect payment details from the payer through an interaction hosted and displayed by the Mastercard Gateway.
From API version 100 and later, KNET is automatically available as a payment method once your payment service provider enables and configures it for your account.
For more information, refer to Browser Payments through Hosted Checkout integration.
Webhook notifications
If you subscribe to Mastercard Gateway webhook notifications, you will receive additional updates about the paymentStatus.