Skip to main content
POST
/
v1
/
orders
/
checkout
/
{publicKey}
Begin checkout for a replacing order
curl --request POST \
  --url https://api.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"
}
'
{
  "status": true,
  "message": "",
  "appended_data": {},
  "data": {
    "checkout_url": "https://pay.papp.sa/session/abcd1234"
  }
}

Path Parameters

​
publicKey
string
required

Public key that identifies the merchant.

Body

application/json
​
total_price
number<float>
required

Checkout amount (SAR).

Required range: x >= 0
Example:

150.75

​
order_number
string
required

Merchant order reference. A leading # is stripped server-side.

Example:

"ORD-2024-0001"

​
phone_number
string | null

Customer phone number. Accepted formats: +966XXXXXXXXX, 00966XXXXXXXXX, 966XXXXXXXXX, 0XXXXXXXXX, or bare 5XXXXXXXX. Normalised server-side to 5\d{8}.

Example:

"512345678"

​
name
string | null

Customer name.

Maximum string length: 255
Example:

"Ahmed Al-Saud"

​
shipping_amount
number<float> | null
Required range: x >= 0
Example:

15

​
tax_amount
number<float> | null
Required range: x >= 0
Example:

22.5

​
discount_amount
number<float> | null
Required range: x >= 0
Example:

10

​
shipping_address
object

Optional shipping address. All fields are individually optional.

​
products
object[] | null

Line items. Nullable — orders can be created without per-item detail.

Minimum array length: 1
​
metadata
object

Optional metadata that will be stored with the order.

Example:
{
  "source": "mobile_app",
  "notes": "Deliver ASAP"
}
​
callback_url
string<uri> | null

URL to redirect the customer after checkout completion.

Example:

"https://merchant.example.com/callback"

Response

Checkout URL generated successfully.

​
status
boolean
required
Example:

true

​
message
string | null
required
Example:

""

​
appended_data
object
required
Example:
{}
​
data
object
required