Patron REST API Specification & Reference

Official REST API reference manual for Patron merchant integrations. Validate member eligibility, query perk rules, and record purchase redemptions.

Base URL

https://www.patron.com.ng

All production and sandbox API requests must be served over secure HTTPS.

Content-Type

application/json

All request bodies must be valid formatted JSON objects.

Response Shape

{ success, redemption_id, member, perk }

Consistent JSON response format across all API endpoints.

2. Authentication & API Key Specification

Authenticate requests using your secret API key. Pass it in the HTTP Authorization header with the Bearer scheme, or via x-api-key.

HTTP Header Specifications

// Preferred Standard Header
Authorization: Bearer ptr_test_YOUR_API_KEY

// Alternative Custom Header
x-api-key: ptr_test_YOUR_API_KEY

Sandbox Test Key (ptr_test_...)

Use during development. Creates mock redemptions without deducting subscriber limits.

Production Live Key (ptr_live_...)

Use in production. Validates real member subscriptions and records real redemptions.

3. Member & Token Validation Endpoint

POST /api/merchant/qr-validate

Validates subscriber eligibility for a given perk using their email address, Digital ID QR payload token, or user UUID.

Request Body JSON Schema

Field Name	Type	Required	Description & Validation Rules
member_identifier	string	Required	Subscriber email address, user UUID, or sandbox test ID (`test.student@patron-sandbox.ng`).
perk_id	string (UUID)	Required	UUID of the active Perk offered by your merchant account.
order_total	number	Required	Gross transaction bill total in Naira (NGN), required for audit logging and minimum spend validation.

HTTP 200 OK — Success Response JSON Payload

{
  "success": true,
  "is_test": true,
  "redemption_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "member": {
    "id": "00000000-0000-4000-a000-000000000001",
    "full_name": "Adebayo Sandbox (Student)",
    "membership_tier": "student",
    "photo_url": "https://www.patron.com.ng/uploads/profiles/test.jpg"
  },
  "perk": {
    "id": "00000000-0000-4000-b000-000000000001",
    "title": "15% Off Total Order",
    "discount_percent": 15
  }
}

HTTP 422 Unprocessable — Perk Ineligible Response JSON Payload

{
  "error": {
    "code": "PERK_INELIGIBLE",
    "message": "Subscriber membership tier 'classic' does not qualify for this Student perk."
  }
}

4. Purchase Confirmation Webhook Endpoint

POST /api/merchant/purchase-webhook

Confirms a completed e-commerce purchase associated with a redemption ID, logging order financial figures for compliance auditing.

Request Body JSON Schema

Field Name	Type	Required	Description
merchant_email	string	Required	Registered email address associated with your merchant account.
redemption_id	string (UUID)	Required	Redemption UUID returned from earlier validation call.
order_total	number	Required	Gross transaction total in Naira (NGN).
discount_amount_applied	number	Required	Monetary discount amount deducted for member in Naira (NGN).

5. Exhaustive Error Code & Status Matrix

All error responses follow the standardized Patron error envelope { error: { code, message } }.

Error Reference Matrix

HTTP Code	Error Code	Description	Recommended Action
400	INVALID_JSON	Malformed JSON in request body.	Validate JSON body syntax.
401	INVALID_API_KEY	Missing or invalid Bearer API key.	Check Authorization header.
404	MEMBER_NOT_FOUND	No subscriber profile matches identifier.	Verify member email spelling.
422	PERK_INELIGIBLE	Member tier does not qualify for perk.	Check tier rules in Perk setup.
429	RATE_LIMIT_EXCEEDED	Exceeded 60 calls/min rate limit.	Retry request after 60s.

6. Rate Limits & Threshold Specifications

API requests are monitored per API key. When rate limits are exceeded, endpoints respond with HTTP 429 and standard rate limit headers.

Rate Limit Header Specification

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1755352860
Retry-After: 60

Ready to Implement a Complete Integration Step-by-Step?

Follow start-to-finish integration guides tailored for your specific use case with multi-framework code switchers (Vanilla JS, Next.js, Flutter, React Native, cURL, PHP, Python).