# Integrate Pay with Points Into Your Ecommerce Checkout
source: https://developer.mastercard.com/digital-redemptions/documentation/tutorials-and-guides/integrate-pay-with-points-checkout/index.md

This guide shows an online merchant how to let cardholders pay with bank
reward points inside its own checkout, without redirecting to the bank. It
covers the endpoint sequence for a merchant-hosted (non-SSO) integration,
from card entry to refund.

## Who this guide is for {#who-this-guide-is-for}

* Ecommerce merchants and their payment or checkout teams who want to accept loyalty points as a payment method alongside the card.
* Payment service providers building points redemption into a hosted checkout on behalf of merchants.

For the issuer-hosted flow, where the cardholder starts on the bank's rewards
website, see
[Let Cardholders Redeem Points From Your Issuer Rewards Website](https://developer.mastercard.com/digital-redemptions/documentation/tutorials-and-guides/issuer-rewards-website-sso/index.md).

## What you will build {#what-you-will-build}

1. Detect that the card the customer entered belongs to a participating rewards program and retrieve the points balance.
2. Show the points balance and its currency value at checkout.
3. Let the customer pay some or all of the order with points and charge the remainder to the card.
4. Refund the points automatically if the order is cancelled or returned.

## Prerequisites {#prerequisites}

* A Mastercard Developers project with the Digital Redemptions API added. Follow [Create a Sandbox Project](https://developer.mastercard.com/digital-redemptions/documentation/tutorials-and-guides/sandbox-access-tutorial/index.md).
* A client that signs requests with OAuth 1.0a. See [API Basics](https://developer.mastercard.com/digital-redemptions/documentation/api-basics/index.md).
* Payload encryption configured for the endpoints that carry card data. See [Use Cases](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/index.md#payload-encryption).
* Your `processedBy` identifier, assigned when you onboard to the program.

## Endpoint sequence {#endpoint-sequence}

The table lists every call in order. Each step links to the use case with the
sequence diagram, request fields, and sample payloads.

| Step |                 When                  |             Endpoint             |                                        Purpose                                        |
|------|---------------------------------------|----------------------------------|---------------------------------------------------------------------------------------|
| 1    | Customer enters card number           | `POST /redeemers/search`         | Confirm the card is eligible and return the RANAC, points balance, and cost per point |
| 2    | Checkout renders                      | (no call)                        | Display the balance and currency value returned in step 1                             |
| 3    | Customer chooses to pay with points   | `POST /redemptions`              | Redeem the points and receive a `redemptionId`                                        |
| 4    | Order is fulfilled (merchandise only) | `PUT /redemptions`               | Report fulfilment status such as shipped or back-ordered                              |
| 5    | Customer cancels or returns           | `POST /redemptions/{id}/credits` | Refund all or part of the points to the cardholder                                    |
| 6    | Reconciliation or order history       | `GET /redemptions`               | Retrieve redemptions processed for the cardholder                                     |

### 1. Check eligibility and retrieve the points balance {#1-check-eligibility-and-retrieve-the-points-balance}

When the customer enters their card number (BAN), call
`POST /redeemers/search` with the BAN in an encrypted body. The response
returns:

* the RANAC, the tokenised account identifier you use for every later call;
* the points balance and, if you pass a `redemptionItemId`, the cost per point so you can show a currency value;
* program details you can use to brand the option, for example the program name.

If the account is not found the card is not enrolled in a participating
program; hide the pay-with-points option and continue with a normal card
payment.

See [Search Redeemer Profile](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redeemers-profile/search-redeemer-profile/index.md).
Tip: To avoid a call on every checkout, store the participating BIN ranges and only call `POST /redeemers/search` when the card matches. See the [Support FAQ](https://developer.mastercard.com/digital-redemptions/documentation/support/index.md).

### 2. Show the points balance at checkout {#2-show-the-points-balance-at-checkout}

Display the points balance together with its currency equivalent next to the
payment options, for example "You have 25,000 points, worth $250". Let the
customer choose the full order amount or a partial amount in points. Design
guidance and Figma journeys are in
[Pay With Points at the Merchant Checkout (Non-SSO)](https://developer.mastercard.com/digital-redemptions/documentation/experience-design-guide/design/redemption-merchant-website-non-sso/index.md).

### 3. Redeem the points {#3-redeem-the-points}

When the customer confirms, call `POST /redemptions` with the RANAC, the
`redemptionType`, and either `pointsRedeemed` with a `redemptionMatrixItemId`
or `cashEquivalent` with a `redemptionItemId`. The response returns a
`redemptionId` and the remaining balance. Store the `redemptionId` against
the order; you need it for any refund.

Charge any remaining order amount to the card through your normal payment
processor.

See [Create Redemptions](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/post-redemptions/index.md).

### 4. Report fulfilment status (optional) {#4-report-fulfilment-status-optional}

If you ship physical goods, call `PUT /redemptions` to record order placed,
shipped, back-ordered, or invoiced against the `redemptionId`. This does not
move points.

See [Update Redemption Status](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/update-redemption-status/index.md).

### 5. Refund points when the order is cancelled or returned {#5-refund-points-when-the-order-is-cancelled-or-returned}

Call `POST /redemptions/{id}/credits` with the `redemptionId`. For a full
cancellation send no `partialCreditPoints`; for a partial return send the
number of points to give back. The points return to the cardholder's account
immediately and Mastercard reconciles the cost between the issuer program and
you.

See [Reverse Redemption](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/reverse-redemption/index.md).

### 6. Retrieve redemption history {#6-retrieve-redemption-history}

Use `GET /redemptions` to list the redemptions for a cardholder when you
reconcile orders or answer a customer-service query.

See [Get Redemptions](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/get-redemptions/index.md).

## Test in Sandbox {#test-in-sandbox}

Use the test data described in
[Create a Sandbox Project](https://developer.mastercard.com/digital-redemptions/documentation/tutorials-and-guides/sandbox-access-tutorial/index.md)
and the Java walkthrough in
[Integration and Testing](https://developer.mastercard.com/digital-redemptions/documentation/tutorials-and-guides/api-testing-tutorial/index.md)
to exercise the sequence above end to end.

## Next Steps {#next-steps}

* Request production credentials: [Production Access](https://developer.mastercard.com/digital-redemptions/documentation/tutorials-and-guides/production-access-tutorial/index.md).
* Review all endpoints in the [API Reference](https://developer.mastercard.com/digital-redemptions/documentation/api-reference/index.md).