# Loyalty Transaction History and Points Earned
source: https://developer.mastercard.com/transactions-service/documentation/use-cases/transaction-details-service/index.md

Use Loyalty Transactions Service to retrieve a rewards account's transaction history and points earned with `POST /transactions/searches`. The same account-level search supports cardholder rewards activity feeds, customer service enquiries, and loyalty-program credit checks.

## Pre-requisites {#pre-requisites}

You need an enabled project, credentials for the selected environment, and the RANAC of an active account enrolled in an eligible Mastercard Rewards System program. The consumer must have accepted the program terms. Authenticate the consumer or servicing agent in your application and authorize access to the requested account before sending an authenticated API request.

Follow the [Quick Start Guide](https://developer.mastercard.com/transactions-service/documentation/quick-start-guide/index.md) for a complete Sandbox request and response. The request requires `userId` containing the account RANAC and `userIdType` set to `RANAC`. Do not use a card number or RANCU in this search.

### Display a rewards activity feed {#display-a-rewards-activity-feed}

To show which purchases earned points in a mobile banking app or an existing rewards account page:

1. Resolve the signed-in consumer's authorized account RANAC on your backend. Keep API signing keys and tokens out of the browser or mobile application.
2. Call `POST /transactions/searches?offset=0&limit=25` with `userId`, `userIdType`, and optional `fromDate` and `toDate` in `YYYY-MM-DD` format. Use date windows of no more than 90 days within the available 13-month history.
3. Map each returned transaction's `date`, `description`, `transactionAmount`, and `transactionCurrencyCode` to the activity row. Display `basePointsEarned` and, where present, `promotions` details with their `name`, `pointType`, and `pointsEarned`.
4. Use the response's `offset`, `count`, and `total` to request subsequent pages. Increase the offset by the count received and stop when the total is reached or the page is empty. Keep the account and date filters unchanged while paging.
5. Provide separate loading, error, and no-matching-activity states. A missing points field is not evidence of zero points. Do not add base and promotion values together without confirming how your program represents earning types; promotion entries can include a `Base` point type.

The API returns data for your application to display, not a ready-made rewards UI. Use the [transaction history experience design guide](https://developer.mastercard.com/transactions-service/documentation/experience-design-guide/design/retrieve-trans-details/index.md) for presentation guidance and [success validation](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/api-testing-tutorial/index.md#validate-a-successful-response) to check the returned account and activity.

### Investigate missing cardholder rewards points {#investigate-missing-cardholder-rewards-points}

Showing purchase-level earning details can help cardholders answer rewards questions themselves and reduce avoidable customer service calls. When an enquiry still needs an agent:

1. Confirm the authorized account and the purchase date, merchant, and amount with the cardholder. Search the relevant date window and inspect every result page before treating a purchase as absent.
2. Check transaction availability. Mastercard-cleared transactions generally appear two to five days after the transaction date, with some arriving later; customer-supplied transactions follow the agreed integration schedule. See [transaction availability](https://developer.mastercard.com/transactions-service/documentation/index.md#overview).
3. Compare the matching record's `basePointsEarned` and available promotion details with the customer's question. Use `postingDate` and `processedDate`, when present, to distinguish the purchase date from later processing.
4. Explain the recorded earnings or investigate the discrepancy against the program terms. An empty search or missing promotion entry alone does not prove that the purchase was ineligible.
5. Escalate unresolved discrepancies through [Get Help](https://developer.mastercard.com/transactions-service/documentation/support/index.md#get-help), providing sanitized request criteria, response or error details, and the expected earning rule. Do not include credentials or full card numbers.

This is a rewards-points investigation workflow, not a payment chargeback process. The search endpoint cannot award missing points or reverse a payment.

### Verify base and bonus rewards credits {#verify-base-and-bonus-rewards-credits}

Loyalty-program teams can use transaction earning records to check whether credited points match the intended program rules:

1. Select known transactions for an enrolled account and retrieve all matching pages for the test period.
2. Obtain the expected earning rules from the program configuration or program owner. The response contains earning results, not the rule definitions.
3. Compare `basePointsEarned` and each applicable promotion's `id`, `name`, `pointType`, and `pointsEarned` with the expected result. Check the transaction type, relevant amount and currency, merchant category, and dates against the rule being tested.
4. Record expected and actual values separately. Confirm the program's treatment of base and bonus earning types before calculating totals, and distinguish missing data from a confirmed incorrect credit.
5. Ask the program owner to investigate and arrange any correction through the approved program process. Loyalty Transactions Service is read-only and does not update earning rules or credited points.

For repeatable tests, use a [Sandbox account with known activity](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/sandbox-access-tutorial/index.md) and follow [Integration and Testing](https://developer.mastercard.com/transactions-service/documentation/tutorials-and-guides/api-testing-tutorial/index.md). Sandbox examples demonstrate the response structure; they do not prove your production rules are configured correctly.

## Sequence Diagram {#sequence-diagram}

Diagram transaction-details-service

##### Following are the execution steps: {#following-are-the-execution-steps}

1. The consumer signs in to the issuer's app.
2. The customer authenticates the consumer.
3. The customer sends a request to the Loyalty Transactions Service for the list of transaction details.

* The request for transaction details requires the following mandatory input parameters:
  * userId
  * userIdType

4. Mastercard API Gateway authenticates/authorizes the customer and routes the request to the Loyalty Transactions Service in the case of a valid customer.
5. The Loyalty Transactions Service validates the request received via the `/transactions/searches` endpoint.
6. The Loyalty Transactions Service retrieves the list of transaction details.
7. The Loyalty Transactions Service sends a response with the list of transaction details (200).
8. The Loyalty Transactions Service sends a response with a status code of 4xx/5xx in case of an invalid request.

You will receive an error response for an invalid request or any missing request parameter. In that case, you need to update the input and perform step 3 again.

### Endpoint {#endpoint}


API Reference: `GET /transactions/searches`

Note: For more information about the error codes, refer to the [Code and Formats](https://developer.mastercard.com/transactions-service/documentation/code-and-formats/index.md) section.