# QPAY for Unified Payments API

QPay payments follow a two-step process:

1.  [Request a QPay 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`

### Request example

```json
{
  "amount": 100,
  "currency": "QAR",
  "source": {
    "type": "qpay",
    "description": "QPay Demo Payment",
    "language": "en",
    "quantity": "1",
    "national_id": "070AYY010BU234M"
  }
}
```

### Response example

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

```json
{
  "id": "pay_7eil5osdlcdehe62et5aihec4q",
  "status": "Pending",
  "customer": {
    "id": "cus_mydbq4wrfp3excwlexeefsv3be"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q"
    },
    "redirect": {
      "href": "https://sbapi.ckotech.co/qpay-external/redirect-to-qpay?pun=52h7saoi5edthll6ceec"
    }
  }
}
```

---

## 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

To retrieve details about the payment, you can use either the `id` found in the payment response or the `cko-session-id` from the success/failure URL. For example, `https://www.checkout.com/order/succeeded?cko-session-id=sid_vii64oquze5u3h2x6hh4rurc4y`.

> **Note**
>
> The `cko-session-id` expires 15 minutes after being created.

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**

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

**Sandbox**

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

### Response example

```json
{
  "id": "pay_7eil5osdlcdehe62et5aihec4q",
  "requested_on": "2024-06-20T10:03:42Z",
  "source": {
    "type": "qpay",
    "description": "QPay Demo Payment",
    "pun": "skqewp72qqxpuckrdf2c"
  },
  "amount": 100,
  "currency": "QAR",
  "payment_type": "Regular",
  "status": "Captured",
  "approved": true,
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_mydbq4wrfp3excwlexeefsv3be"
  },
  "_links": {
    "redirect": {
      "href": "https://sbapi.ckotech.co/qpay-external/redirect-to-qpay?pun=52h7saoi5edthll6ceec"
    },
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q/actions"
    },
    "refund": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q/refunds"
    }
  }
}
```

---

## Refund a payment

QPay supports both partial and full refunds. You can refund a payment through the [Dashboard](https://dashboard.checkout.com) or the [Refund API](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment).

QPay approves refunds manually every three working days, depending on overall volume.

QPay does not approve refund transactions coming from testing environments. See [Test QPay refunds](#Test_QPay_refunds) for more information.

---

## Cancel a payment

If the customer fails to complete their payment, we will automatically void it and send a `payment_expired` webhook.

If the customer cancels their payment, we will send a `payment_canceled` webhook.

---

## Test QPay payments

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

1. Create a QPay payment request.
2. In the response, follow the redirect link to QPay's website.
3.  Enter the following test card details:

| Card number | Expiry date | PIN | OTP |
| --- | --- | --- | --- |
| `6399500004271776` | `03/2028` | `677` | `1111` |
| `4215375500883243` | `06/2030` | `677` | `1111` |

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

To test declined payments, provide any of the previous test card numbers using a PIN other than `677`.

### Test QPay refunds

If you perform a refund in a testing environment, your transaction will remain in a `requested for verification` state.

Optionally, you can contact your bank to approve your test refund transaction.