Core requirements
| Requirement | What you need |
|---|---|
| HTTPS | All API calls and webhook deliveries use HTTPS. Your webhook endpoint must present a valid TLS certificate. |
| JSON | Request and response bodies are application/json. |
| Server-side integration | Authenticated API calls must originate from your backend, never from browser/mobile client code. |
| Secrets storage | Your Private API key and webhook secret must be stored in environment variables or a secrets manager. |
| Public webhook URL | Points must be able to reach your webhook endpoint from the public internet. |
| Order persistence | You must store the returned Points order uuid and your own order_number. |
Network requirements
- API base URL:
https://api.papp.sa/api/v1 - Webhook delivery: HTTPS
POSTfrom Points to your endpoint - TLS: TLS 1.2 or higher
- Ports: standard HTTPS on
443 - IP allow-listing: optional and available on request, but the primary verification mechanism is
X-Webhook-Secret
Application requirements
1. You need a backend service
Points is not a client-side integration. Your system must have a backend capable of:- calling the REST API
- storing orders and webhook events
- validating
X-Webhook-Secret - running asynchronous work after webhook receipt
2. You must store these values
At minimum, persist:| Value | Why it matters |
|---|---|
Your internal order_number | Your reconciliation key |
Points order uuid | Required for lookup, cancel, refund, capture, status update |
| Webhook event receipts | Needed for idempotency and audit |
reference_number | Useful for merchant support and dashboard matching |
3. Your webhook handler must be fast
Points’ webhook worker posts to your endpoint with a10 second HTTP timeout and retries failed deliveries up to 3 times. In practice, your handler should:
- verify the secret
- enqueue work
- return
2xximmediately
Data expectations
Phone numbers
- KSA format is expected
- the backend normalises
+966,00966,966, and leading0 - the final accepted mobile format is
5XXXXXXXX
Amounts
- all monetary values are in SAR
- all request totals must be numeric
- points are derived server-side from your order amount
Order items
For both earning and checkout flows, send line items whenever possible. They improve reconciliation, merchant support, and customer-facing history.No official SDK requirement
There is currently no official SDK. Any stack with a modern HTTP client works:- Node.js
- PHP / Laravel
- Python
- Ruby
- Java / Kotlin
- .NET
Recommended production setup
Minimum recommended architecture
Minimum recommended architecture
Frontend calls your backend, your backend calls Points, Points calls your webhook, your worker updates your order state. This gives you auditability and retry control on both sides.
Recommended reconciliation
Recommended reconciliation
Keep webhooks as the primary signal, but run a scheduled reconciliation job that queries
GET /v1/orders/{uuid} for any order still waiting on a terminal state.Recommended observability
Recommended observability
Monitor 4xx and 5xx rates to the API, webhook verification failures, duplicate webhook attempts, and orders that never receive a terminal event.
Platform note
Points supports direct API integration today. If you are integrating through a commerce platform or custom middleware, the technical requirements above still apply unless your platform-specific connector explicitly abstracts them for you.Next
Quickstart
Make your first authenticated API call.
Security
Hardening checklist for keys, webhooks, and logs.
Go-Live Checklist
Final production readiness checks.