Overview

The Loyalty API is a modular and secure platform for integrating real-time loyalty services into your retail, kiosk, or digital channels. This API is designed for retailers and developers looking to integrate robust loyalty program functionalities into their existing systems, providing a comprehensive set of endpoints to register and manage members, process transactions, issue and redeem benefits, and track customer activity across touchpoints.

This documentation outlines how to interact with the API effectively and securely while maintaining consistency across use cases.

Requesting an API Key

Requesting an API Key

To use the API, you need a valid API Key.
If you don’t already have one, please request it by emailing us.

To request an API Key, please get in touch with support team and include:

• Your company or business name
• Intended usage (e.g. production, staging)
• Contact person's name and email

Once reviewed, we’ll provide you with an API Key specific to your integration environment.

Architecture & Design Principles

The API is built on the following principles:

• Stateless communication: All operations are atomic and REST-compliant.
• Real-time interaction: Requests respond with up-to-date balances, eligibility, and benefit decisions.
• Security-first model: All communication must be encrypted and authenticated.
• Extensibility: Core objects like member, transaction, and event are designed for long-term evolution.

Core Functional Areas

Area	Description
Member	Register, identify, and update loyalty users securely.
Transaction	Submit sales data to calculate benefits, log activity, and trigger rewards.
Payment	Accept or cancel loyalty payments via points or credit.
Assets	Manage redeemable gifts (e.g., vouchers, birthday offers).
Deals	Apply automatic promotions or discounts based on segmentation logic.
Events	Send behavioral or external triggers to drive segmentation and automation.

Each object and operation is designed to plug seamlessly into customer journeys.

Common Workflows

Use Case	Endpoint(s)	Purpose
Register a new member	/member/register	Collects member information and consents to join the loyalty program, enabling personalized engagement from day one.
Update profile or permissions	/member/update	Modify contact fields, GDPR consents, or preferences, maintaining data accuracy and compliance while respecting customer privacy choices.
Identify or verify a member	/member/details, /member/shortCode	Securely fetch member details or generate short login codes, ensuring seamless customer recognition and personalized service delivery.
Process a purchase	/transaction	Records full transaction data and evaluates loyalty assets or deals, ensuring accurate reward calculation and instant benefit application.
Make a loyalty payment	/payment	Pay using points or credit, or reverse previous payments, providing flexible payment options that increase customer satisfaction and retention.
Trigger a behavioral event	/event	Log member actions like visits, signups, referrals, or milestones, enabling automated campaigns and personalized marketing triggers.

Object Model Overview

The API is composed of consistent reusable objects across all endpoints:

Member

Used in: register, details, update, payment, event, transaction
Fields: phoneNumber, email, membershipKey, externalId

View full model

Check the Member object reference for all fields and usage.

Transaction

Used in: transaction, payment, member/details
Fields: transactionId, items, payments, dateTime, totalAmount, usedAssets, appliedDeals

View full model

Check the Transaction object reference for all fields and usage.

Payment

Used in: payment, transaction
Fields: action, amount, confirmationCode (if canceling), type

View full model

Check the Payment object reference for all fields and usage.

Discount & Asset

Used in: member/details, transaction
Describes: Promotions, birthday gifts, vouchers, and applied campaign benefits

View full model

Check the Discount & Asset reference for all fields and usage.

Security & Authentication

All endpoints are protected by API keys and must be accessed over HTTPS using TLS 1.2 or higher.

Required Headers

Header	Description
x-api-key	Integration-specific authentication token
x-source-type	Origin of request (POS, Web, Kiosk, etc.)
x-source-name	Source system or client name
x-branch-id	Business unit identifier
x-pos-id	Terminal identifier

danger

Never expose API keys in frontend code. Secure keys using backend server-to-server communication.

Response & Error Handling

All API responses contain a status field indicating whether the request was successful or not.

• If status is "success", the response will also include other fields depending on the endpoint (e.g., member, confirmationCode).
• If status is "error", the response will contain an error object with code and message.

Example: Success Response

{
  "status": "success",
  "confirmationCode": "ABC123"
}

Example: Error Response

{
  "status": "error",
  "error": {
    "code": "203",
    "message": "Cannot find any member with the given identifier!"
  }
}

Integration Recommendations

• Use idempotent transaction IDs to avoid duplication
• Log confirmation codes for audit and troubleshooting
• Monitor usage and timeouts proactively to detect issues
• Do not log sensitive data like emails, phone numbers, or tokens
• Structure payloads to match object schemas across endpoints

Versioning

All endpoints are versioned. Current version: v1
Base URL:

https://pos-api.fidelizacion.app/v1/