# KNET for Unified Payments API

KNET payments follow a two-step process:

1.  [Request a KNET payment](#Request_a_payment).
2.  [Redirect the customer](#Redirect_the_customer).

---

## Request a payment

For the full API specification, see the [API reference](https://api-reference.checkout.com/).

**Live**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

> **Note**
>
> When sending a payment request that includes `source.card_token`, you can optionally pay via KFast. 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

```json
{
  "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"
  }
}
```

### Response example

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

```json
{
  "id": "pay_4gubyq2w335upc54dx7a4257lq",
  "status": "Pending",
  "customer": {
    "id": "cus_r3cajfpbj3ju7jyq7afcg3qc4a"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.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.

Use the following details to set up your request.

### Endpoints

For the full API specification, see the [API reference](https://api-reference.checkout.com/).

**Live**

`POST` `https://{prefix}.api.checkout.com/payments/{id}`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`

### Response example

```json
{
  "id": "pay_4gubyq2w335upc54dx7a4257lq",
  "requested_on": "2024-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://{prefix}.api.sandbox.checkout.com/payments/pay_c2ynk5nnjacuxia3r4matf5wmu"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_c2ynk5nnjacuxia3r4matf5wmu/actions"
    }
  }
}
```

---

## Refund a payment

KNET supports full, partial and multiple partial refunds. Refund a payment through the [Dashboard](https://dashboard.checkout.com) or by using our [Refund API](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment.md).

> **Note**
>
> Before you can refund KNET payments, you need to contact your bank and ask them to enable refunds. Your bank will then send a request to KNET to activate the 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

> **Note**
>
> To start testing, contact your account manager or integrations engineer to activate KNET payments in the sandbox environment.

1.  Create a KNET transaction following the steps on this page, and open 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 number – `888888 000 000 000 1`
    3.  Expiration date – `09 | 2030`
    4.  PIN – `1234`
3.  Select _Submit_ and then _Confirm_. You should then be redirected to your predefined success URL.