Skip to main content
This quickstart walks you through issuing your first successful Points API call — creating an earning order — in five short steps. By the end you will have awarded real loyalty points to a test customer.
If you do not yet have merchant credentials, register at business.papp.sa or email support@papp.sa to request sandbox access.

​
Prerequisites

  • A Points merchant account (sandbox or production)
  • A Private API key (see API keys)
  • A terminal with curl, or any HTTP client (Postman, Insomnia, your backend)
  • A test customer phone number in KSA format (e.g. 512345678)

​
Step 1 — Locate your API key

Sign in to the Points Business dashboard and open Settings → API Keys. Copy the Private key — you will send it in the x-api-key header on every request.
The Private key is a secret. Never expose it in client-side code, public repositories, or mobile app bundles.

​
Step 2 — Confirm the base URL

All v1 endpoints live under: 
https://api.papp.sa/api/v1
Every authenticated request must include:
HeaderValue
x-api-keyYour Private key
Content-Typeapplication/json
Acceptapplication/json

​
Step 3 — Create an earning order

The simplest integration point: award points for a completed purchase. 
curl -X POST https://api.papp.sa/api/v1/orders/earning \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phone_number": "512345678",
    "total_price": 115.00,
    "order_number": "SALE-2024-0021",
    "products": [
      { "product_name": "Cappuccino", "product_price": 18.50, "quantity": 2 },
      { "product_name": "Croissant",  "product_price": 39.00, "quantity": 2 }
    ]
  }'

​
Step 4 — Read the response

A successful call returns the created order: 
{
  "status": true,
  "message": "",
  "appended_data": {},
  "data": {
    "id": 42,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "reference_number": "REF-2024-001234",
    "order_status": "approved",
    "order_number": "SALE-2024-0021",
    "type": 1,
    "total_price": 115.00,
    "total_points": 1150,
    "created_at": "2026-04-18T10:00:00Z"
  }
}
Points to notice:
  • uuid — the Points identifier. Store this on your side; you will use it for later operations (refund, cancel, lookup).
  • order_status: "approved" — the earning order is settled and points are credited.
  • total_points — the number of points awarded to the customer.
  • type: 1 — indicates an earning order (2 = replacing / redeem checkout).

​
Step 5 — Verify in the dashboard

Open the Points Business dashboard → Orders. Your new order appears with reference_number matching the response above, and the customer balance has been credited.
That’s it — you just awarded points through the API.

​
What to build next

Set up webhooks

Receive real-time notifications when orders are approved, captured, cancelled, or refunded.

Full checkout flow

Let customers redeem points at your checkout, not just earn them.

Order lifecycle

Understand authorize → capture → refund and how each transition affects points.

API reference

Every endpoint, parameter, and response documented.

​
Troubleshooting

The x-api-key header is missing. Confirm your HTTP client is attaching it. Header names are case-insensitive but must be spelled exactly x-api-key.
The key you sent does not match any active merchant key. Regenerate from the dashboard or confirm you copied the Private key (not the Public key).
Your merchant account is not enabled for earn-only. Contact support@papp.sa to enable it.
One of the body fields failed validation. The response message field names the first failing rule. Common causes: missing phone_number for earning orders, empty products array, non-numeric total_price.
You sent another earning request for the same merchant before the previous one released its distributed lock. Retry after a short back-off; do not parallelise earning calls for the same merchant.