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

INTEGER

REQUIRED

The payment amount

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 (two-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. 

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.

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.

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.

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.

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.

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.