# Loyalty Transactions Service source: https://developer.mastercard.com/transactions-service/documentation/index.md ## Overview {#overview} Mastercard Transactions Service is a loyalty transaction history API for displaying points earned per purchase in banking apps and customer service tools. It is named **Loyalty Transactions** in project setup and **Loyalty Transactions API** in the OpenAPI specification. The Loyalty Transactions Service API retrieves transactions for active accounts enrolled in the Mastercard Rewards System. Accounts may only be enrolled with the user's explicit acceptance of program terms. The Transactions Service API response provides a view of an individual consumer's points earned or transaction data based on the requested timeframe. The service is used where the user or consumer is seeking to view points earned or transaction details. For instance, in a customer service application, to help with problem resolution. Note: For Loyalty Transactions Service API, the transaction details are shared only where Mastercard scores a Rewards or Promotions program for a customer. The Transactions Service API does not share aggregate-level data. In some cases, the Promotions Digital Enablement Transaction endpoint is recommended as an alternative, your Solution Engineer or Program Manager will guide you. The timing of the transaction availability depends on the integration. For instance: * For transactions completed through Mastercard (that is, GCMS, GCO, or MDS), the details are provided daily after receiving from clearing (our system only sees the cleared transactions). The transactions appear in the system about two to five days after the transaction date, although a small percentage will come later. All of these processes are heavily dependent on the merchant. * For transactions that come from the customer or partner, a schedule will be established when the program is onboarded (based on the integration details). ### Who can use this loyalty transaction API? {#who-can-use-this-loyalty-transaction-api} Issuers and merchants with eligible Mastercard Rewards System programs can retrieve enrolled account activity for their own applications. Fintechs building a customer or partner-hosted experience need to confirm their role, program eligibility, and access with a Mastercard representative. Being a fintech or merchant does not itself grant access to cardholder data. The customer's application authenticates the consumer and must restrict searches to accounts that consumer or servicing agent is authorized to access. Mastercard authenticates the customer's API request separately. Start with [Sandbox project access](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/sandbox-access-tutorial/index.md), then complete [production onboarding](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/production-access-tutorial/index.md) before using live accounts. ### Choose a rewards data API {#choose-a-rewards-data-api} | Need | Service scope and next step | |-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Show purchases with points earned or investigate unexpected credits | Use Loyalty Transactions Service for enrolled account transaction records, including `basePointsEarned` and promotion earning details where available. See the [rewards workflows](https://developer.mastercard.com/transactions-service/documentation/use-cases/transaction-details-service/index.md). | | Work with a user's points activity | Review [Loyalty Points Activity Service](https://developer.mastercard.com/points-activity-service/documentation/) and confirm the required activity with your Mastercard representative. It is a separate API, not another name for Loyalty Transactions Service. | | Retrieve an account identifier before searching transactions | Use the Loyalty User Account Management reference-search flow described below if you do not already hold the account's RANAC. Loyalty Transactions Service requires `userIdType` to be `RANAC`. | | Retrieve transactions for a Promotions integration | Ask your Solution Engineer or Program Manager whether the Promotions Digital Enablement Transaction endpoint is the appropriate alternative. | | Retrieve arbitrary bank-account history, real-time authorizations, or aggregate analytics | Loyalty Transactions Service does not provide unrestricted bank-data access, an authorization feed, or aggregate-level data. Its scope is eligible enrolled rewards accounts. | When comparing loyalty APIs, confirm account eligibility, transaction history coverage, data arrival times, authentication, and Sandbox enablement. Loyalty Transactions Service supports up to 13 months of history with searches in increments of up to 90 days; see [timeframe limitations](https://developer.mastercard.com/transactions-service/documentation/support/index.md). It retrieves credited activity rather than managing earning rules or issuing rewards. ## How It Works {#how-it-works} The Loyalty Transactions Service API enables customers to get a snapshot view of their transaction history. The types of customers who will benefit from this service are issuers and merchants, and the target groups would be: * Programs where the client is hosting the entire user experience through Mastercard Reward APIs. * Programs in which Mastercard hosts the product offering (that is, the client uses Mastercard white-labeled solutions, products, etc.) but the transactions are displayed on a client-hosted platform. Note: There is no service dependency if a customer has an opaque identifier like RANAC or RANCU to query the endpoints such as Loyalty Points Activity Service, Loyalty User Account Management, or Loyalty Transactions Service. However, if the customer is not storing an opaque identifier, the user-management `/users/references/searches` endpoint is used to get the RANAC and RANCU using BAN or BCN. This creates a dependency to use the Loyalty Points Activity Service or Loyalty Transactions Service. RANCU is a Random Customer Number and RANAC is a Random Account Number. Both are tokens meant to hide PCI (Personal Customer Information). ##### The following diagram shows a high-level flow between the Consumer, Customer, and the Loyalty Transactions Service API. {#the-following-diagram-shows-a-high-level-flow-between-the-consumer-customer-and-the-loyalty-transactions-service-api} ![Consumer and customer application exchange transaction details through the Loyalty Transactions Service API.](https://static.developer.mastercard.com/content/transactions-service/uploads/how_it_works_tlp.png) ###### Execution Steps {#execution-steps} 1. The consumer signs into the customer's application. 2. The customer authenticates the consumer. 3. The customer authenticates its request as described in [API Basics](https://developer.mastercard.com/transactions-service/documentation/api-basics/index.md#client-authentication) and calls [POST /transactions/searches](https://developer.mastercard.com/transactions-service/documentation/use-cases/transaction-details-service/index.md#endpoint) with the account identifier and search criteria. 4. The Loyalty Transactions Service validates the request. If validation fails, use [Code and Formats](https://developer.mastercard.com/transactions-service/documentation/code-and-formats/index.md) to interpret the error and correct the request. 5. The Loyalty Transactions Service retrieves transaction activity for the supplied search criteria; see the [Transaction Details workflow](https://developer.mastercard.com/transactions-service/documentation/use-cases/transaction-details-service/index.md). 6. The Loyalty Transactions Service returns the [transaction details response](https://developer.mastercard.com/transactions-service/documentation/api-reference/index.md) for the customer to display to the consumer. Follow [success validation](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/api-testing-tutorial/index.md#validate-a-successful-response) to check the result. ### Good to Know {#good-to-know} * We have created a [Reference Application](https://developer.mastercard.com/transactions-service/documentation/reference-app/index.md) to get you started. * Refer to the [Use Cases](https://developer.mastercard.com/transactions-service/documentation/use-cases/index.md) for additional details on how the API works. * Refer to the [Tutorials and Guides](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/index.md) for additional guidance. Tip: If you don't have a Mastercard representative, reach out for help from the [support page](https://developer.mastercard.com/transactions-service/documentation/support/index.md#get-help). ## Next Steps {#next-steps} Start with the [Quick Start Guide](https://developer.mastercard.com/transactions-service/documentation/quick-start-guide/index.md) for project setup and a first Sandbox call. Refer to [API Basics](https://developer.mastercard.com/transactions-service/documentation/api-basics/index.md) for authentication and environment details, then [Integration and Testing](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/api-testing-tutorial/index.md) for success and error-path tests.