Begin checkout for a replacing order
curl --request POST \
--url https://business.papp.sa/api/v1/orders/checkout/{publicKey} \
--header 'Content-Type: application/json' \
--data '
{
"total_price": 150.75,
"order_number": "ORD-2024-0001",
"phone_number": "512345678",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"metadata": {
"source": "mobile_app",
"notes": "Deliver ASAP"
},
"callback_url": "https://merchant.example.com/callback"
}
'import requests
url = "https://business.papp.sa/api/v1/orders/checkout/{publicKey}"
payload = {
"total_price": 150.75,
"order_number": "ORD-2024-0001",
"phone_number": "512345678",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"metadata": {
"source": "mobile_app",
"notes": "Deliver ASAP"
},
"callback_url": "https://merchant.example.com/callback"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
total_price: 150.75,
order_number: 'ORD-2024-0001',
phone_number: '512345678',
name: 'Ahmed Al-Saud',
shipping_amount: 15,
tax_amount: 22.5,
discount_amount: 10,
shipping_address: {city: 'Riyadh', line1: '1234 King Fahd Rd, Al Olaya'},
products: [{product_name: 'Cappuccino', product_price: 18.5, quantity: 2}],
metadata: {source: 'mobile_app', notes: 'Deliver ASAP'},
callback_url: 'https://merchant.example.com/callback'
})
};
fetch('https://business.papp.sa/api/v1/orders/checkout/{publicKey}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://business.papp.sa/api/v1/orders/checkout/{publicKey}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'total_price' => 150.75,
'order_number' => 'ORD-2024-0001',
'phone_number' => '512345678',
'name' => 'Ahmed Al-Saud',
'shipping_amount' => 15,
'tax_amount' => 22.5,
'discount_amount' => 10,
'shipping_address' => [
'city' => 'Riyadh',
'line1' => '1234 King Fahd Rd, Al Olaya'
],
'products' => [
[
'product_name' => 'Cappuccino',
'product_price' => 18.5,
'quantity' => 2
]
],
'metadata' => [
'source' => 'mobile_app',
'notes' => 'Deliver ASAP'
],
'callback_url' => 'https://merchant.example.com/callback'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://business.papp.sa/api/v1/orders/checkout/{publicKey}"
payload := strings.NewReader("{\n \"total_price\": 150.75,\n \"order_number\": \"ORD-2024-0001\",\n \"phone_number\": \"512345678\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"metadata\": {\n \"source\": \"mobile_app\",\n \"notes\": \"Deliver ASAP\"\n },\n \"callback_url\": \"https://merchant.example.com/callback\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://business.papp.sa/api/v1/orders/checkout/{publicKey}")
.header("Content-Type", "application/json")
.body("{\n \"total_price\": 150.75,\n \"order_number\": \"ORD-2024-0001\",\n \"phone_number\": \"512345678\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"metadata\": {\n \"source\": \"mobile_app\",\n \"notes\": \"Deliver ASAP\"\n },\n \"callback_url\": \"https://merchant.example.com/callback\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://business.papp.sa/api/v1/orders/checkout/{publicKey}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"total_price\": 150.75,\n \"order_number\": \"ORD-2024-0001\",\n \"phone_number\": \"512345678\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"metadata\": {\n \"source\": \"mobile_app\",\n \"notes\": \"Deliver ASAP\"\n },\n \"callback_url\": \"https://merchant.example.com/callback\"\n}"
response = http.request(request)
puts response.read_body{
"status": true,
"message": "",
"appended_data": {},
"data": {
"checkout_url": "https://pay.papp.sa/session/abcd1234"
}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "The given data was invalid.",
"appended_data": {},
"errors": {
"total_price": [
"The total price field is required."
],
"products.0.quantity": [
"The quantity must be at least 1."
]
}
}Orders
Begin checkout for a replacing order
Starts a checkout session for a replacing (redeem + pay) order using the merchant’s public key. This endpoint does not require the x-api-key header — the public key in the path authenticates the call.
When phone_number is provided but no matching customer exists, the returned checkout_url lands on an onboarding page where the customer can register before paying. The response shape is identical in both cases.
POST
/
v1
/
orders
/
checkout
/
{publicKey}
Begin checkout for a replacing order
curl --request POST \
--url https://business.papp.sa/api/v1/orders/checkout/{publicKey} \
--header 'Content-Type: application/json' \
--data '
{
"total_price": 150.75,
"order_number": "ORD-2024-0001",
"phone_number": "512345678",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"metadata": {
"source": "mobile_app",
"notes": "Deliver ASAP"
},
"callback_url": "https://merchant.example.com/callback"
}
'import requests
url = "https://business.papp.sa/api/v1/orders/checkout/{publicKey}"
payload = {
"total_price": 150.75,
"order_number": "ORD-2024-0001",
"phone_number": "512345678",
"name": "Ahmed Al-Saud",
"shipping_amount": 15,
"tax_amount": 22.5,
"discount_amount": 10,
"shipping_address": {
"city": "Riyadh",
"line1": "1234 King Fahd Rd, Al Olaya"
},
"products": [
{
"product_name": "Cappuccino",
"product_price": 18.5,
"quantity": 2
}
],
"metadata": {
"source": "mobile_app",
"notes": "Deliver ASAP"
},
"callback_url": "https://merchant.example.com/callback"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
total_price: 150.75,
order_number: 'ORD-2024-0001',
phone_number: '512345678',
name: 'Ahmed Al-Saud',
shipping_amount: 15,
tax_amount: 22.5,
discount_amount: 10,
shipping_address: {city: 'Riyadh', line1: '1234 King Fahd Rd, Al Olaya'},
products: [{product_name: 'Cappuccino', product_price: 18.5, quantity: 2}],
metadata: {source: 'mobile_app', notes: 'Deliver ASAP'},
callback_url: 'https://merchant.example.com/callback'
})
};
fetch('https://business.papp.sa/api/v1/orders/checkout/{publicKey}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://business.papp.sa/api/v1/orders/checkout/{publicKey}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'total_price' => 150.75,
'order_number' => 'ORD-2024-0001',
'phone_number' => '512345678',
'name' => 'Ahmed Al-Saud',
'shipping_amount' => 15,
'tax_amount' => 22.5,
'discount_amount' => 10,
'shipping_address' => [
'city' => 'Riyadh',
'line1' => '1234 King Fahd Rd, Al Olaya'
],
'products' => [
[
'product_name' => 'Cappuccino',
'product_price' => 18.5,
'quantity' => 2
]
],
'metadata' => [
'source' => 'mobile_app',
'notes' => 'Deliver ASAP'
],
'callback_url' => 'https://merchant.example.com/callback'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://business.papp.sa/api/v1/orders/checkout/{publicKey}"
payload := strings.NewReader("{\n \"total_price\": 150.75,\n \"order_number\": \"ORD-2024-0001\",\n \"phone_number\": \"512345678\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"metadata\": {\n \"source\": \"mobile_app\",\n \"notes\": \"Deliver ASAP\"\n },\n \"callback_url\": \"https://merchant.example.com/callback\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://business.papp.sa/api/v1/orders/checkout/{publicKey}")
.header("Content-Type", "application/json")
.body("{\n \"total_price\": 150.75,\n \"order_number\": \"ORD-2024-0001\",\n \"phone_number\": \"512345678\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"metadata\": {\n \"source\": \"mobile_app\",\n \"notes\": \"Deliver ASAP\"\n },\n \"callback_url\": \"https://merchant.example.com/callback\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://business.papp.sa/api/v1/orders/checkout/{publicKey}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"total_price\": 150.75,\n \"order_number\": \"ORD-2024-0001\",\n \"phone_number\": \"512345678\",\n \"name\": \"Ahmed Al-Saud\",\n \"shipping_amount\": 15,\n \"tax_amount\": 22.5,\n \"discount_amount\": 10,\n \"shipping_address\": {\n \"city\": \"Riyadh\",\n \"line1\": \"1234 King Fahd Rd, Al Olaya\"\n },\n \"products\": [\n {\n \"product_name\": \"Cappuccino\",\n \"product_price\": 18.5,\n \"quantity\": 2\n }\n ],\n \"metadata\": {\n \"source\": \"mobile_app\",\n \"notes\": \"Deliver ASAP\"\n },\n \"callback_url\": \"https://merchant.example.com/callback\"\n}"
response = http.request(request)
puts response.read_body{
"status": true,
"message": "",
"appended_data": {},
"data": {
"checkout_url": "https://pay.papp.sa/session/abcd1234"
}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "Invalid or inactive API key",
"appended_data": {}
}{
"status": false,
"message": "The given data was invalid.",
"appended_data": {},
"errors": {
"total_price": [
"The total price field is required."
],
"products.0.quantity": [
"The quantity must be at least 1."
]
}
}Path Parameters
Public key that identifies the merchant.
Body
application/json
Checkout amount (SAR).
Required range:
x >= 0Example:
150.75
Merchant order reference. A leading # is stripped server-side.
Example:
"ORD-2024-0001"
Customer phone number. Accepted formats: +966XXXXXXXXX, 00966XXXXXXXXX, 966XXXXXXXXX, 0XXXXXXXXX, or bare 5XXXXXXXX. Normalised server-side to 5\d{8}.
Example:
"512345678"
Customer name.
Maximum string length:
255Example:
"Ahmed Al-Saud"
Required range:
x >= 0Example:
15
Required range:
x >= 0Example:
22.5
Required range:
x >= 0Example:
10
Optional shipping address. All fields are individually optional.
Show child attributes
Show child attributes
Line items. Nullable — orders can be created without per-item detail.
Minimum array length:
1Show child attributes
Show child attributes
Optional metadata that will be stored with the order.
Example:
{
"source": "mobile_app",
"notes": "Deliver ASAP"
}
URL to redirect the customer after checkout completion.
Example:
"https://merchant.example.com/callback"
⌘I