Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

KNET

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

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

Overview

KNET payments follow a two-step process:

  1. Request a KNET payment
  2. Redirect the customer

Request a payment

The POST request

Endpoints

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

Header parameters

HeaderValue

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 nameDescription

amount

REQUIRED

INTEGER
The payment amount

currency

REQUIRED

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

source

REQUIRED

OBJECT
Details about the payment source.

source.type

REQUIRED

STRING
The type of payment source. Set this to knet.

source.language

REQUIRED

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

source.user_defined_field1

OPTIONAL

STRING

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

OPTIONAL

STRING

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

OPTIONAL

STRING


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. 

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

OPTIONAL

STRING

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.

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

OPTIONAL

STRING

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

OPTIONAL

STRING


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.

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

OPTIONAL

STRING

This is an ID for merchant PTLF functionality tracking. The value will appear on the bank statement.

If you include this in your request, source.user_defined_field5 must be empty, because they share a KNET API field.

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 POST 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"
    }
  }
}

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 payment

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

The GET request

Use the details below to set up your request.

Endpoints

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

Header and path parameters

HeaderValue

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
PathValue

payment_id

REQUIRED

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

The GET 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 payment

KNET supports full, partial and multiple partial refunds. Refund a payment through the Hub or by using our refund API.

To enable refunds for KNET payments, contact your bank and ask them to enable this functionality. Once KNET has received confirmation from your bank, you will be able to process refunds.

Cancel a payment

If, after landing on the KNET payment page, the customer attempts to complete the payment after 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

To start testing, you'll need to:

  • create a test account, and
  • contact your Customer Success manager or Integrations engineer to activate KNET payments in the sandbox environment.
  1. Create a KNET transaction as above, following the redirect link in the response to KNET's website.
  2. Enter the following details:
    1. Select your bank: Knet Test Card [KNET1]
    2. Card number888888 000 000 000 1
    3. Expiration date: 09 | 2021
    4. PIN: 1234
  3. Click Submit and then click ConfirmYou should then be redirected to your predefined success URL.