Points API Documentation

The Points PHP SDK is the fastest way to integrate Points into a PHP backend. It calls the same API documented in the API Reference, but with less boilerplate, typed clients, and built-in webhook verification helpers.

Repository: points/php-sdk
Package: papp/points-sdk
Runtime: PHP 8.2+

When to use the SDK

Use the SDK when you want to:

initialize a typed client once and reuse it across your backend
reduce manual request signing and header handling
speed up integration in Laravel or PHP projects
use built-in helpers for webhook parsing and order actions

Use direct REST calls if your stack does not use PHP, or if you prefer to work directly with HTTP.

What the SDK covers

checkout session creation
earning and redemption order flows
order lifecycle actions (authorize, capture, complete, cancel)
shipping status updates
refunds
webhook management and verification helpers

Authentication model

the private key is used for authenticated backend operations (sent as the x-api-key header)
the public key is used for checkout endpoint calls
webhook verification uses your webhook secret

The SDK is for backend usage only. Never expose your private key in frontend code.

Install

composer require papp/points-sdk

Quick start

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Papp\Points\Client;

$points = new Client([
    'private_key' => 'points_private_key_xxx',
    'public_key' => 'points_public_key_xxx',
    'base_url' => 'https://business.papp.sa/api/v1',
    'timeout' => 30,
    'retries' => 3,
]);

Create a checkout

$checkoutUrl = $points->orders()->createCheckout([
    'phone_number' => '0555123456',
    'name' => 'Customer Name',
    'total_price' => 150.50,
    'order_number' => 'SHOP-1001',
    'products' => [
        [
            'product_name' => 'T-Shirt',
            'product_price' => 150.50,
            'quantity' => 1,
        ],
    ],
]);

Continue the order lifecycle

use Papp\Points\Enums\PaymentMethod;

$order = $points->orders()->authorize('550e8400-e29b-41d4-a716-446655440000');
$order = $points->orders()->capture($order->uuid);
$order = $points->orders()->complete($order->uuid, PaymentMethod::Visa);

Configuration

string

required

Required. Sent as the x-api-key header for authenticated backend requests.

string

Optional. Used for checkout-related endpoints when needed.

string

required

Set this explicitly for the environment you want to call.

integer

default:"30"

Request timeout in seconds.

integer

default:"3"

Number of retry attempts.

Webhooks

Use the built-in webhook handler to parse incoming webhook payloads with your webhook secret:

use Papp\Points\Webhooks\WebhookHandler;

$handler = new WebhookHandler('your_webhook_secret');
$event = $handler->parse($rawPayload, $secretHeader, $eventHeader);

Best fit

Use the PHP SDK when you are building with:

plain PHP services
Laravel applications
existing PHP commerce backends that need checkout and order actions

Introduction

E-commerce Platforms

Authentication

Integration Guide

Webhooks

Widgets

SDKs

Testing

PHP SDK

When to use the SDK

What the SDK covers

Authentication model

Install

Quick start

Create a checkout

Continue the order lifecycle

Configuration

Webhooks

Best fit

See also

​When to use the SDK

​What the SDK covers

​Authentication model

​Install

​Quick start

​Create a checkout

​Continue the order lifecycle

​Configuration

​Webhooks

​Best fit

​See also

When to use the SDK

What the SDK covers

Authentication model

Install

Quick start

Create a checkout

Continue the order lifecycle

Configuration

Webhooks

Best fit

See also