QPAY for API only

Last updated: August 30, 2024

QPay payments follow a two-step process:

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2  "amount": 100,
3  "currency": "QAR",
4  "source": {
5    "type": "qpay",
6    "description": "QPay Demo Payment",
7    "language": "en",
8    "quantity": "1",
9    "national_id": "070AYY010BU234M"
10  }
11}

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


1{
2  "id": "pay_7eil5osdlcdehe62et5aihec4q",
3  "status": "Pending",
4  "customer": {
5    "id": "cus_mydbq4wrfp3excwlexeefsv3be"
6  },
7  "_links": {
8    "self": {
9      "href": "https://api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q"
10    },
11    "redirect": {
12      "href": "https://sbapi.ckotech.co/qpay-external/redirect-to-qpay?pun=52h7saoi5edthll6ceec"
13    }
14  }
15}

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.

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.

For the full API specification, see the API reference.

get

https://api.checkout.com/payments/{id}


1{
2  "id": "pay_7eil5osdlcdehe62et5aihec4q",
3  "requested_on": "2024-06-20T10:03:42Z",
4  "source": {
5    "type": "qpay",
6    "description": "QPay Demo Payment",
7    "pun": "skqewp72qqxpuckrdf2c"
8  },
9  "amount": 100,
10  "currency": "QAR",
11  "payment_type": "Regular",
12  "status": "Captured",
13  "approved": true,
14  "risk": {
15    "flagged": false
16  },
17  "customer": {
18    "id": "cus_mydbq4wrfp3excwlexeefsv3be"
19  },
20  "_links": {
21    "redirect": {
22      "href": "https://sbapi.ckotech.co/qpay-external/redirect-to-qpay?pun=52h7saoi5edthll6ceec"
23    },
24    "self": {
25      "href": "https://api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q"
26    },
27    "actions": {
28      "href": "https://api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q/actions"
29    },
30    "refund": {
31      "href": "https://api.sandbox.checkout.com/payments/pay_7eil5osdlcdehe62et5aihec4q/refunds"
32    }
33  }
34}

QPay supports both partial and full refunds. You can refund a payment through the Dashboard or the Refund API.

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 for more information.

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.

Note

To start testing, you'll need to contact your account manager or Integrations engineer to activate QPay payments in your testing environment.

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

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

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.

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.

QPAY for API only

Request a payment

Request example

Response example

Redirect the customer

Get details about a payment

Note

Endpoints

Response example

Refund a payment

Cancel a payment

Test QPay payments

Note

Test QPay refunds