API Call Overview

This section provides a high-level overview of how to make API calls within the loyalty platform. It covers authentication, required headers, request structure, common flows, and best practices.

Authentication and Headers

All API requests must include the following mandatory headers:

Header	Type	Required	Description
x-api-key	string	Yes	Client or integration-specific API key
x-source-type	string	Yes	Origin of the request (e.g., POS, Kiosk, Web)
x-source-name	string	Yes	Name of the integration partner or source system
x-pos-id	string	Yes	Unique ID of the terminal making the request
x-branch-id	string	Yes	ID of the business branch performing the operation
x-return-assets	string	No	Filter assets to return (active, inactive, or all)
x-return-benefits	boolean	No	Whether to return calculated discounts for the member

Request Structure

Most endpoints accept application/json payloads. The structure typically contains objects such as:

{
  "member": {
    "phoneNumber": "1234567890"
  },
  "transaction": {
    "transactionId": "TX12345",
    "openTime": "2025-05-23T12:00:00Z",
    "totalAmount": 5000
  }
}

Other commonly used request components:

• newMemberData for registration and updates
• payment for loyalty-based transactions
• action for operations like pay, cancel, send, or verify

Common Use Cases

Use Case	Endpoint	Notes
Check member + benefits	/member/details	Can return assets and discount previews
Register new member	/member/register	Requires phone/email and consent fields
Update member profile	/member/update	Include only fields to modify
Secure login	/member/shortCode	Use send, get, or verify as action
Loyalty payment	/payment	Process payment using points/credit or cancel existing payment
Submit transaction	/transaction	Track segmentation, rewards, or cancel a purchase
Record event	/event	Log behavior for workflows like birthdays, visits, etc.

Error Handling

All responses include a top-level status field. If status is error, an error object is returned.

{
  "status": "error",
  "error": {
    "code": "503",
    "message": "dateTime is required",
    "path": "body.transaction.dateTime"
  }
}

Common HTTP Status Codes

• 200 OK – Successful response
• 400 Bad Request – Invalid or missing fields
• 401 Unauthorized – API key missing or invalid
• 404 Not Found – Resource not found
• 500 Internal Server Error – Unexpected server issue

Best Practices

• Always use HTTPS (TLS 1.2+)
• Validate and sanitize inputs
• Do not log sensitive information
• Monitor response times and failure rates
• Use consistent User-Agent strings
• Implement retries and timeouts for network resilience