SupportAPI referenceClassic API docs
Guides
Start typing to search…

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.

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

POSThttps://api.checkout.com/payments

Sandbox

POSThttps://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.

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

🚧

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:
      -   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 [email protected].

Updated 5 months ago