Quick Start - Loyalty API
Last updated
Last updated
Welcome to the Factor4 Loyalty API Quick Start Guide! This document provides a rapid introduction to integrating prepaid (loyalty/gift) card management functionalities into your application. The Factor4 Loyalty API allows you to programmatically activate, query, top-up, process payments, and manage loyalty points for customer cards.
The Factor4 Loyalty API is designed to offer comprehensive management of gift and loyalty cards. It enables merchants and developers to perform essential operations related to prepaid cards, including card activation, balance inquiries, funds top-ups, processing payments using gift cards, and managing loyalty point issuance and redemption. All API requests are processed via HTTPS POST and require a JSON Web Token (JWT) in the request header, along with a signature for robust authentication and request verification.
The Factor4 Loyalty API provides various functionalities to manage prepaid (loyalty/gift) cards, primarily through the following API endpoints:
Activate Gift Card: Used to activate a prepaid card and link it to customer information.
(Specific URL not provided in all references, but general capability is listed).
Query Gift Card: Used to retrieve the current balance and associated customer details for a specific prepaid card.
POST /ovstrade/openLoyaltyPay/giftInquiry
Top-up Gift Card: Allows adding funds (reloading/topping-up) to an existing prepaid card. This operation can also optionally activate the card or update customer information.
(Specific URL for Top-up, sometimes referred to as giftIssuance, is implied but not explicitly provided for the "Top-up" name across all references).
Pay Gift Card: Used to process payments by using the available balance on a customer's prepaid (loyalty/gift) card.
(Specific URL not provided in all references, but general capability is listed).
Void Gift Card: This endpoint is used to void a prior prepaid card transaction, such as a payment or a reload. A void typically reverses the original operation before it has been settled.
POST /ovstrade/openLoyaltyPay/giftVoid
Issue Points - Gift Card: This endpoint is used to issue loyalty points to a customer's prepaid card. This specifically adds points, not monetary value.
POST /ovstrade/openLoyaltyPay/loyaltyIssuance
Redeem Points - Gift Card: Utilized to consume or redeem loyalty points from a customer's prepaid card, serving as the inverse of the "Issue Points" operation.
POST /ovstrade/openLoyaltyPay/loyaltyRedemption
Add Tip - Gift Card: For adding a tip to a prepaid card transaction that has already been completed, common in service industries.
POST /ovstrade/openLoyaltyPay/giftTip
All requests to the Factor4 Loyalty API must be secured using a JSON Web Token (JWT) and a signature.
Protocol: HTTPS
HTTP Method: POST
Required Headers:
Content-Type: Must be application/json.
jwt-token: Your transaction token, obtained using your developer credentials.
sign: The request signature. Refer to the Signature Generation Guide for detailed instructions on generating this signature.
Factor4 Loyalty API provides a Sandbox environment for development and testing purposes.
To begin utilizing the Factor4 Loyalty API, follow these fundamental steps:
Obtain Developer Credentials: Secure your clientId and any other credentials necessary for generating your jwt-token and sign.
Generate JWT Token: Create a valid JWT token using your developer credentials.
Generate Request Signature: Follow the specific instructions in the Signature Generation Guide to produce the required request signature.
Construct Request Body: Assemble the JSON formatted request body for your chosen API endpoint, including parameters like clientId, loyaltyChannel, accountId, tranOrderNo, and others as required.
Send POST Request: Transmit your POST request, complete with the correct headers and request body, to the relevant API endpoint in the Sandbox environment.
Below are some frequently used parameters found in the Loyalty API request bodies:
clientId (String, Required): Your unique developer ID.
tranOrderNo (String, Required): A unique order ID generated by your system for the specific transaction (e.g., for points issuance, redemption, top-up, void, tip).
loyaltyChannel (String, Required): The designated prepaid channel provider.
accountId (String, Required): The unique identifier for the prepaid card.
entryType (String, Required): Specifies the method used to input the accountId. Valid codes include: B (Barcode), K (Keyed/Manual), M (Magnetic Stripe), P (Proximity/NFC/Contactless).
oriOrderNo (String, Required): The checkoutId of the original transaction you want to void (for giftVoid) or the original payment transaction ID for adding a tip (for giftTip).
tranCurrency (String, Required): The 3-letter ISO currency code for the transaction, e.g., "USD" (used for adding tips).
amount (String): The total transaction amount, e.g., "10.50" (used for top-up, void, tips).