Create a new Qattah Pay Order

A new Qattah Pay request is sent through an HTTPS API accepting a JSON object as order details

API call

POST https://staging-api.qattahpay.sa/api/v1/merchant-integration/orders

api_token is provided by Qattah Pay for each integration

Headers

Name	Type	Description
Content-Type*	String	header must be set to application/json
Accept*	String	header must be set to application/json
Authorization*	String	header must be the api_token

Request Body

Name	Type	Description
amount*	Double	The order total amount in “SAR”
reference	String	Reference ID that can be used to identify an order * It must be shown in the end-user application for later-on tracing.
callback_url	String	This URL will be called back when the Qattah order is paid successfully
theme	String	This is the theme of the payment session, it can be a dark theme or a light theme and you can choose by passing "dark" for the dark theme or "light" for the light theme. (Default is light).
lang	String	This is the language of the payment session. And you have to pass "ar" for Arabic or "en" for English. (Default is Arabic)
currency	String	This is the Order Currency. Note: now we support onlly 'SAR'
description	String	Description for the order
emailAddress	String	email address of the end-user
mobileNumber	String	mobile number of the end-user
success_url	String	Redirects the user to this "success" URL when payment is successful. Note: if this is a null or empty string, the user will be redirected to the success screen of Qattah Pay
failure_url	String	Redirects the user to this "failur" URL when payment is expired (timed-out). Note: if this is a null or empty string, the user will be redirected to the failure screen of Qattah Pay

200 The request had been properly processed

{
    "successful": true,
    "data": {
        "order": {
            "id": "ord_krBMWnzvOnGEe",
            "merchant_id": "mer_o9MmBQ6VQxrRe",
            "merchant_name": "MerchantName",
            "reference": "common-reference",
            "amount": "100.00",
            "started_at": null,
            "is_expired": false,
            "is_timed_out": false,
            "remaining_time": {
                "min": 0,
                "sec": 0
            },
            "activity_status": "CREATED",
            "payment_status": "PENDING",
            "callback_url": "https://testing-callback.qattahpay.sa",
            "success_url": "https://example.com/success",
            "failure_url": "https://example.com/failed"
        }
    },
    "links": {
        "redirect_to": "https://staging-app.qattahpay.sa/ord_krBMWnzvOnGEe?lang=ar&theme=dark"
    }
}

401 Unauthorized

Responses body

successful	boolean	Refers to if the request has been created successfully or not
data	object	Data object
data.order	object	Order object
data.order.id	string	Unique order id (starts with “ord_”)
data.order.merchant_id	string	Your merchant id (starts with “mer_”)
data.order.reference	string	If you send a reference id this will be returned to this key's value, if not, we will generate one for you and return it to this key too
data.order.amount	string	The total order amount which needs to be spliced into multiple users’ invoices
data.order.started_at	string	When the Qattah session started, and this must be “null” at the beginning because no user started the payment session yet
data.order.is_expired	boolean	Refers to if the Qattah session expired or not, it must be “false” at the beginning because it’s just created
data.order.is_time_out	boolean	Refers to if the Qattah session last for 15 min and timed out or not, it must be “false” at the beginning because it’s just created
data.order.remaining_time.min	int	Refers to how many minutes before this Qattah order expires.
data.order.remaining_time.sec	int	Refers to how many seconds after minutes before this Qattah order expires.
data.order.activity_status	string	This is the activity status of the order, which refers to if the order is created, started, paid, or time out. It must be “created” at the beginning because the end-user didn't add any users, yet.
data.order.payment_status	string	This is the payment status of the order, which refers to if the order is paid or still pending. It must be “pending” at the beginning because no user started the payment session yet.
data.order.invoices	array	This is the array of invoices, each user has a separated invoice to pay. It must be empty array at the beginning because the creator user did not add anyone yet.
data.order.callback_url	string	This URL will be called back when the Qattah order is paid successfully
data.order.success_url	string	Redirects the user to this "success" URL when payment is successful. Note: if this is a null or empty string, the user will be redirected to the success screen of Qattah Pay
data.order.failur_url	string	Redirects the user to this "failure" URL when payment is expired (timed-out). Note: if this is a null or empty string, the user will be redirected to the failure screen of Qattah Pay
links	object	This is the array of invoices, each user has a separated invoice to pay. It must be empty array at the beginning because the creator user did not add anyone yet.
links,redirect_to	string	This is where the user must be redirected to continue payment cycle

Order payment statuses

Read more about order payment statuses from the below link

🚉Order payment statuses

Rate limit: The rate limit is set to prevent malicious behaviour and poor user experiences. The per-hour rate limit per channel token is 20000 requests. You can contact your QattahPay representative if a higher limit is necessary.