Core requirements
Network requirements
- API base URL:
https://business.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: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.Official SDK available
An official PHP SDK is available for PHP and Laravel backends. Direct REST integration is also supported for any stack. Examples are also available in Quick start and throughout the integration guides.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
Quick start
Make your first authenticated API call.
Security
Hardening checklist for keys, webhooks, and logs.
Go-Live Checklist
Final production readiness checks.