KNET

Start accepting payments using KNET, the leading payment method in Kuwait.

To start accepting KNET payments, please contact your customer success manager.

Process a KNET payment

KNET payments follow a two-step process:

  1. Request a KNET payment
  2. Redirect the customer

Step 1: Request a KNET payment

The request

Use the details below to set up your request.

Endpoints

Live

https://api.checkout.com/payments

Sandbox

https://api.sandbox.checkout.com/payments

Header parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Body parameters

The table below describes the minimum recommended fields. You can find the full list, as well as complete request and response examples, in our API reference.

Field name
Description

amount
Integer
required

The payment amount in the major currency.

currency
string
required

The currency in which the payment is being made (three-letter ISO 4217 code). Set this to KWD.

source
Object
required

Details about the payment source.

source.type
String
required

The type of payment source. Set this to knet.

source.language
String
required

The customer's preferred language (2-letter ISO code). Set this to either ar (Arabic) or en (English).

source.user_defined_field1
String
optional

You can use this to pass and store any additional transaction data you wish to archive with the transaction and make available as searching criteria.
<= 255 characters. Alphanumeric characters and spaces only.

source.user_defined_field2
String
optional

You can use this to pass and store any additional transaction data you wish to archive with the transaction and make available as searching criteria.
<= 255 characters. Alphanumeric characters and spaces only.

source.user_defined_field3
String
optional

You can use this to pass and store any additional transaction data you wish to archive with the transaction and make available as searching criteria.
Note: Omit this field if you include source.card_token in your request, because the latter is passed to the KNET gateway as udf3.
<= 255 characters. Alphanumeric characters and spaces only.

source.card_token
String
optional

This token (an eight-digit token generated by the merchant) allows you to re-use card details for multiple payments. When a subsequent payment is initialized with the same card token, the customer will be presented with two options: pay with KFast (where they don't need to enter their card details again), or with KNET as usual.
Note: If you include this in your request, source.user_defined_field3 must be empty, because they share a KNET API field.

source.user_defined_field4
String
optional

You can use this to pass and store any additional transaction data you wish to archive with the transaction and make available as searching criteria.
<= 255 characters. Alphanumeric characters and spaces only.

source.user_defined_field5
String
optional

You can use this to pass and store any additional transaction data you wish to archive with the transaction and make available as searching criteria.
Note: Omit this field if you include source.ptlf in your request, because the latter is passed to the KNET gateway as udf5.
<= 255 characters. Alphanumeric characters and spaces only.

source.ptlf
String
optional

This is an ID for merchant PTLF functionality tracking. The value will appear on the bank statement.
Note: If you include this in your request, source.user_defined_field5 must be empty, because they share a KNET API field.
<= 45 characters. Alphanumeric characters and spaces only.

Payment requests including a card token

When sending a payment request that includes source.card_token, the option to pay via KFast is offered. If the token is new, the first payment will happen via the usual flow, but with the option to "register for KFast" before submitting. This flow is not testable in the sandbox environment because the registration for KFast requires the customer to enter a one-time password sent to the mobile phone number registered with the bank, which is not present in sandbox.

Request example

{
  "amount": 1000,
  "currency": "KWD",
  "source": {
    "type": "knet",
    "language": "en",
    "user_defined_field1": "first user defined field",
    "user_defined_field2": "second user defined field",
    "card_token": "01234567",
    "user_defined_field4": "fourth user defined field",
    "ptlf": "96033587c7b5"
  }
}

The response

If you receive a 202 Success response containing a status field set to Pending, your request was successful.

Response example

{
  "id": "pay_4gubyq2w335upc54dx7a4257lq",
  "status": "Pending",
  "customer": {
    "id": "cus_r3cajfpbj3ju7jyq7afcg3qc4a"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_4gubyq2w335upc54dx7a4257lq"
    },
    "redirect": {
      "href": "https://sbapi.ckotech.co/knet-external/redirect/tok_tl6kftlhdpzephqelsbpyovl4i/pay"
    }
  }
}

Step 2: Redirect the customer

Redirect your customer to the redirect link’s href in the response. This will allow the customer to authorize the payment, before they are transferred to your predefined success or failure URL.

Get details about a KNET payment

You can retrieve details about an existing KNET payment with the following endpoint.

The request

Use the details below to set up your request.

Endpoint

Live

GEThttps://api.checkout.com/payments/{payment_id}

Sandbox

GEThttps://api.sandbox.checkout.com/payments/{payment_id}

Header and path parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Path
Value

payment_id
Required

The payment ID found in the response of the initial payment.

The response

Response example

{
  "id": "pay_4gubyq2w335upc54dx7a4257lq",
  "requested_on": "2019-05-23T17:04:05Z",
  "source": {
    "type": "knet",
    "language": "en",
    "user_defined_field1": "first user defined field",
    "user_defined_field2": "second user defined field",
    "user_defined_field4": "fourth user defined field",
    "card_token": "01234567",
    "ptlf": "96033587c7b5",
    "knet_payment_id": "100201914315601265",
    "knet_result": "Captured",
    "bank_reference": "914310000349",
    "knet_transaction_id": "201914384388126",
    "auth_code": "B00775",
    "post_date": "0524",
    "avr": "N"
  },
  "amount": 1000,
  "currency": "KWD",
  "payment_type": "Regular",
  "status": "Captured",
  "approved": true,
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_kx75h5tcegyednxeyvtn6vy3sq"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_c2ynk5nnjacuxia3r4matf5wmu"
    },
    "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_c2ynk5nnjacuxia3r4matf5wmu/actions"
    }
  }
}

Refund a KNET payment

If you want to refund a KNET payment, you need to do so through KNET's own portal.

Any refunds processed via KNET will not appear in your Checkout.com Hub account or be available in reports you create with our reconciliation API.

Cancel a KNET payment

If the customer fails to complete their payment within seven minutes, we will automatically void the payment and send a payment_expired webhook.
If the customer cancels their payment, we will send a payment_canceled webhook.

Testing KNET

Before testing, please ensure that your account has been enabled to support KNET payments. Contact your customer success manager for more information.

  1. Create a KNET transaction as above, following the redirect link in the response to KNET's website.

  2. Enter the following details:
      -   Select your bank: Knet Test Card [KNET1]
      -   Card number: 888888 000 000 000 1
      -   Expiration date: 09 | 2021
      -   PIN: 1234

  3. Click "Submit", and then "Confirm".

  4. You should then be redirected to your predefined success URL.

Can we help?

Thanks for using Checkout.com. If you need any help or just have a question, please get in touch with our support team at support@checkout.com.

KNET


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.