# API Basics
source: https://developer.mastercard.com/pay-with-rewards/documentation/api-basics/index.md

The Pay with Rewards engine contains six primary areas of logic:

## 1. Authorization Processing {#1-authorization-processing}

When a cardholder makes a purchase on their Pay with Rewards enabled Mastercard card, the Pay with Rewards engine receives a copy of the authorization from the Mastercard network. This receipt of a copy of the authorization initiates Pay with Rewards rules processing.

Clients may share copies of authorizations not available to the Mastercard network using the Post Auth API. Once received, the processing takes place in the same manner as with Mastercard transactions.

PWR contains a specific set of rules that applies to all authorizations, in all programs. These rules include:

* **Authorization Approval** -- In order for an authorization to be processed by PWR, DE039 must be equal '00', which is the code for an authorization approval from the issuer.
* **Account in Good Standing** - The status of the transacting account must be "Good Standing" or "Redeem Only"
* **Account is eligible to redeem** -- If the account is in a household, the account must be a redeemer in the household.

<br />

If any of these conditions are not met, the PWR rules engine will stop processing the authorization.

In addition to the above rules, it is important to understand how PWR leverages the authorization amount during rules processing. Two important amounts are present in each authorization:

* **Local Purchase Amount (DE004)** -- This is the amount of the purchase in local currency where the purchase is made.
* **Billing Amount (DE006)** -- This is the amount of the purchase in the billing currency of the cardholder. If the local purchase amount is made in a different currency than the billing amount, DE004 and DE006 will contain different amounts. For example, a purchase for €100 would result in €100 in DE004, and $126.00 in DE006. DE006 is always used by the PWR engine when evaluating if rewards should be redeemed. This means a cardholder is always rewarded in their billing currency, even when transacting cross border.

## 2. Program Rules and Filters {#2-program-rules-and-filters}

Once the base PWR rules processing is complete, PWR applies program level rules and filters. Each filter is optional, but all filters are applied using an "AND" operator. By default, PWR is available at any merchant location where the authorization is processed using the Mastercard network. No filtering is applied out of the box, however given the program design; the following filters can be used. Below is a description of each filter type, followed by common scenarios where filters would be applied.

#### Minimum Purchase Amount {#minimum-purchase-amount}

The amount on the authorization is checked against a program configured minimum transaction amount. If the authorization amount does not exceed the program minimum amount, rules processing still stop.

#### Redemption Minimum {#redemption-minimum}

The redemption minimum allows a program to set a minimum cash threshold in order for a consumer to redeem. This threshold is based on the cash equivalent of the consumer's point balance.

#### Merchant Filtering {#merchant-filtering}

PWR has various types of merchant filtering available to identify specific merchants or group of merchants for eligibility. Contact your implementation team for further detail.

#### Merchant Category Code (MCC) {#merchant-category-code-mcc}

MCC Filtering can be "inclusive" or "exclusive". In an inclusive filter, only purchases at MCCs in the filter will be allowed. In an exclusive filter, only purchases at MCCs not in the filter will be allowed. Inclusive and exclusive filters cannot be used simultaneously.

#### Country {#country}

Country filtering can be "inclusive" or "exclusive". In an inclusive filter, only purchase made at countries in the filter will be allowed. In an exclusive filter, only purchases made in countries not in the filter will be allowed. Inclusive and exclusive filters cannot be used simultaneously.

## 3. Cardholder Preferences {#3-cardholder-preferences}

Cardholder preferences allow an enrolled cardholder to choose when their points will be redeemed. If a cardholder has Pay with Rewards turned "off", rewards will not be redeemed.

#### Next Transaction Only {#next-transaction-only}

A client can give cardholders the option to enable Pay with Rewards for their next eligible purchase only. Once a rewards eligible purchase is made and rewards are redeemed, Pay with Rewards is set to "OFF" automatically. This forces the cardholder to turn Pay with Rewards "ON" each time they would like to use rewards for their purchases.

#### All Transactions {#all-transactions}

This "always on" mode allows a cardholder to turn Pay with Rewards "ON" for all transactions and leave Pay with Rewards turned "ON". Rewards will be automatically redeemed until the Rewards balance is exhausted. At no time will Pay with Rewards be turned off.

## Additional preferences {#additional-preferences}

Available to use with "Next Transaction Only" or "All Transactions":

#### Cardholder Minimum Threshold {#cardholder-minimum-threshold}

The client can optionally allow an enrolled cardholder to set a minimum purchase threshold of their choice that is greater than the program minimum threshold. This allows a cardholder to configure Pay with Rewards for "my next transaction over $25".
Note: The cardholder threshold is always based on the transaction amount.

#### Cardholder Fixed Amount {#cardholder-fixed-amount}

Allows the user to set a fixed redemption amount, in cash value.

## 4. Conversion Rules {#4-conversion-rules}

Once a transaction has passed all rules, the reward currency equivalent of that transaction must be determined. To determine this, Pay with Rewards applies conversion rules to the transaction amount based on information contained in the transaction message.

Pay with Rewards currently supports the following conversion rules to determine the proper cost per point:

#### Base Conversion Rule {#base-conversion-rule}

* The Base Conversion rule is always applied first to a rewards eligible purchase.
* The Base Conversion rule determines the base cost per point for any redemption-eligible transaction.

#### Merchant Overrides {#merchant-overrides}

Several merchant overrides are available, allowing for specific cost per point calculation based on a variety of merchant identifiers. Refer to your implementation team for further detail.

#### Bank Product Override Rule {#bank-product-override-rule}

* Allows override for specific bank product code

Note: All conversion rules support a tiered structure based on the amount. For example, a purchase between $0 - $500 has a cost per point of $.01. A purchase greater than $500 has a cost per point of $.012. There is no technical limit to the number of tiers; however Mastercard recommends a simple approach to avoid consumer confusion.

## 5. Rewards Redemption/Points Processing {#5-rewards-redemptionpoints-processing}

Once Pay with Rewards identifies the cost per point to be used, a check is performed against the transacting cardholder's reward balance. Point processing is different for Mastercard versus external point banks. Details on the different integration options can be found [here](https://developer.mastercard.com/pay-with-rewards/documentation/index.md).

#### Redemption types {#redemption-types}

##### Full {#full}

For example, a $100 purchase is made and a cost per point of .01 is identified during conversion rule processing. This means the cardholder must have a rewards balance of at least 10,000 to redeem. If the cardholder has a rewards balance of 12,000, the rewards are immediately redeemed.

##### Partial {#partial}

In the event a cardholder has an insufficient rewards balance to cover the entire amount of the authorization, a program can be configured to use the PWR partial redemption functionality. The partial redemption function allows a cardholder to use rewards to cover a portion of their purchase. If this functionality is enabled for a program, a cardholder can redeem rewards in increments up to the entire purchase amount.

For example, if a program is configured for partial redemptions and rewards can be redeemed in increments of $10, a cardholder with a balance of 7,650 who makes a $100 purchase could redeem 7,000 points at a cost per point of .01. This would result in a $70 statement credit, and a remaining rewards balance of 650.

##### Fixed {#fixed}

Based on the program rules, if a cardholder has a sufficient rewards balance to redeem for any amount of statement credit, rewards are immediately deducted from the cardholder's account, and a statement credit is soon sent to GCMS.
Note: Returns on points/rebate applied to a cardholder's statement are not supported by Pay with Rewards. If a cardholder uses rewards to cover the cost of a purchase, then makes a return, the rewards remain redeemed, and the statement credit stays on the cardholder's statement.

## 6. Communications and Alerts {#6-communications-and-alerts}

Communications can be set up to be sent once Pay with Rewards processes a transaction and determines if a redemption should occur. Depending on the integration model, some communications are not available. Your implementation team can provide further details.

#### Email {#email}

* Successful Redemption -- HTML email that confirms rewards were redeemed.
* Insufficient Rewards Balance -- HTML email that alerts the cardholder Pay with Rewards was turned "ON", but the cardholder lacks a sufficient rewards balance for redemption.
  * Only available for Mastercard point banks
* Below Program Threshold --HTML email that alerts the cardholder Pay with Rewards was turned "ON", but the cardholder's purchase falls below the program minimum transaction threshold.
* The above email from Pay with Rewards can be disabled and is fully content managed by Mastercard on the client's behalf.

#### Authorization Notification {#authorization-notification}

* An HTTP Post can be sent to a client specified URL that contains information on the result of Pay with Rewards processing.
* Click [here](https://developer.mastercard.com/pay-with-rewards/documentation/use-cases/auth-notifier/index.md) for further detail.

## Next Steps {#next-steps}

Now that you have an understanding of basics of the API, proceed to the [API Security](https://developer.mastercard.com/pay-with-rewards/documentation/api-basics/api-security/index.md) section for API authentication, and environment details.