# Create Redemptions
source: https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/post-redemptions/index.md

## Overview {#overview}

This use case creates Redemption for a giver user based on redemption type and other parameters.

## Sequence diagram {#sequence-diagram}

Diagram post-redemptions

##### Following are the execution steps for Create Redemption: {#following-are-the-execution-steps-for-create-redemption}

The following steps describe a sample integration flow of the Create Redemption API.

1. The consumer signs into the customer application.
2. The customer authenticates the consumer.
3. The customer sends a signed request to the Digital Redemptions for creating the redemption.
4. Mastercard Network API Gateway authenticates/authorizes the customer and routes the request to the Digital Redemptions in the case of a valid customer.
5. The Digital Redemptions Service validates the request parameters received via the `POST /redemptions` endpoint.
6. The Digital Redemptions Service Successfully redeemed points from member account.
7. The Digital Redemptions Service sends a response along with the redemptionId (200).
8. The Digital Redemptions 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: `POST /redemptions`

## Use case #1: CASHBACK Redemption Type {#use-case-1-cashback-redemption-type}

* Allows the redemption of one or more Rewards catalog items. Each Customer Program may have unique mix of Reward Items (merchandise, gift cards, eCerts, cashback). These customer-specific collections of Reward Items are called a Reward Matrix. When performing redemptions via this API, individual Matrix Items are used to perform the redemption.
* The Partner will need to know these Matrix Item IDs, to perform the redemption. Matrix Item IDs can be obtained by using the APIs from [Traditional Fulfillment Service](https://developer.mastercard.com/traditional-fulfillment-service/documentation/use-cases/).
* The below is a typical Cashback request. Refer to the field description on the [API reference page](https://developer.mastercard.com/digital-redemptions/documentation/api-reference/index.md) for more information. The request for creating Digital Redemptions with CASHBACK redemptionType have some fields which are NOT mandatory but good to have information.
  * **description** : Description of the Redemption.
* The following are the mandatory request parameters:
  * **userId** : The identifier used to uniquely identify an user.
  * **userIdType** : Determines the type of user identification. Supported identifier is RANAC.
  * **cashbackAccountId** : The intended account to which the cashback is to be awarded. Supported value is RANAC
  * **cashbackAmount** : Amount that cardholder would expect as a cashback.
  * **pointsRedeemed** : Total points redeemed for reward Item.
  * **redemptionMatrixItemId** : If an item is being redeemed, the Mastercard Rewards System rewards id specific to issuer program is required. As previously stated, in order to redeem, these IDs must be retrieved/available with the API client.
  * **processedBy** : Mastercard Rewards System User ID created for client while on-boarding. This is an ID assigned to each Merchant when on-boarding to the Digital Redemptions program.
  * **redemptionType** : CASHBACK.
* For CASHBACK redemption request use combination of "pointsRedeemed" and "redemptionMatrixItemId" ONLY.

##### Sample request {#sample-request}

```json
{
  "items": [
    {
      "description": "cashback for your points",
      "cashbackAmount": 11.00,
      "pointsRedeemed": 366.66,
      "redemptionMatrixItemId": "41275"
    }
  ],
  "processedBy": "MRS_WS",
  "redemptionType": "CASHBACK",
  "userId": "220094110178641288073796026652",
  "userIdType": "RANAC",
  "cashbackAccountId": "220094110178641288073796026652"
}
```

##### Sample response {#sample-response}

```json
{
  "id": "b6ad3116-973c-46d0-b990-e2e9ddd28716",
  "pointBalance": 96383462.64,
  "pointsName": "Test Points Name",
  "programName": "Pay With Points API",
  "items": [
    {
      "itemId": "9384ce65-aed8-4fe4-869a-da5549361cbc",
      "redemptionId": 4901932,
      "redemptionMatrixItemId": "41275"
    }
  ]
}
```

## Use case #2: MERCHANDISE Redemption Type {#use-case-2-merchandise-redemption-type}

* Allows the redemption of one or more Rewards catalog items. Each Customer Program may have unique mix of Reward Items (merchandise, gift cards, eCerts, cashback). These customer-specific collections of Reward Items are called a Reward Matrix. When performing redemptions via this API, individual Matrix Items are used to perform the redemption.
* The Partner will need to know these Matrix Item IDs, to perform the redemption. Matrix Item IDs can be obtained by using the APIs from [Traditional Fulfillment Service](https://developer.mastercard.com/traditional-fulfillment-service/documentation/use-cases/).
* The below is a typical Merchandise request. Refer to the field description on the [API reference page](https://developer.mastercard.com/digital-redemptions/documentation/api-reference/index.md) for more information. The request for creating Digital Redemptions with MERCHANDISE redemptionType have some fields which are NOT mandatory but good to have information.
  * **sourceCode** : Identifier that specifies the channel that generated the redemption. The value needs to be T. This is a unique code assigned to each Merchant when on-boarding to the Digital Redemptions program.
  * **processedBy** : Mastercard Rewards System User ID created for client while on-boarding. This is an ID assigned to each Merchant when on-boarding to the Digital Redemptions program.
  * **paymentOption** : Type of payment used for the redemption. For Digital Merchants payment option should be POINTS_ONLY.
  * **cashEquivalent** : Actual cash value of the pointBalance in currencyCode.
  * **redemptionItemId** : This is a unique reference to the redemption item that will be used to record the redemption.
  * **redemptionMatrixItemId** : If an item is being redeemed, the Mastercard Rewards System rewards id specific to issuer program is required. As previously stated, in order to redeem, these IDs must be retrieved/available with the API client.
  * **pointsRedeemed** : Total points redeemed for reward Item.
  * **description** : Description of the Redemption.
  * **quantity** : Quantity of the item that is redeemed for. Default value is 1.
* The following are the mandatory request parameters:
  * **userId** : The identifier used to uniquely identify an user.
  * **userIdType** : Determines the type of user identification. Supported identifier is RANAC.
  * **paymentOption** : Type of payment used for the redemption.
  * **redemptionType** : MERCHANDISE.
* Please refer to [Scenarios For Redemption Request](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/post-redemptions/index.md#scenarios-for-redemption-request) before using the combination of "cashEquivalent", "pointsRedeemed", "redemptionItemId" and "redemptionMatrixItemId".

##### Sample request {#sample-request-1}

```json
{
  "items": [
    {
      "paymentOption": "POINTS_ONLY",
      "pointsRedeemed": 1,
      "redemptionMatrixItemId": "59897",
      "redemptionItemId": "65973",
      "cashEquivalent": "1",
      "description":"Test Merchandise 2"
    }
  ],
  "processedBy": "MRSWSRED",
  "redemptionType": "MERCHANDISE",
  "sourceCode": "PP",
  "userId": "194029175821411820021023467619",
  "userIdType": "RANAC"
}
```

##### Sample response {#sample-response-1}

```json
{
  "id": "43e34a5b-42bd-471d-9920-4434b2a313bf",
  "pointBalance": 10799489.1,
  "pointsName": "Test Points Name",
  "programName": "Pay With Rewards - TRANS NOTIF",
  "cashEquivalent": 10799489.10,
  "currencyCode": "USD",
  "items": [
    {
      "itemId": "4c95b28a-d46f-452b-a7cb-292d18a25a80",
      "redemptionId": 4571761,
      "redemptionItemId": "65973"
    }
  ]
}
```

## External Item Redemption {#external-item-redemption}

* When a redemption request includes items to be redeemed that are hosted in an external catalog, the request should be handled as an External Item Redemption.
* Below sample request allows for redemptions to be performed via an external catalog provider, without having to add the offer/redemption item into the Mastercard Rewards System Program's Rewards catalog.
* Redemptions via this service will follow the "cost-per-point" model, whereby a generic redemption item will be setup in the Mastercard Rewards System Catalog for each Partner Program. This generic item description and Reward Matrix Item ID will be given to the Partner to use as input in the request. This value will be provided by the Mastercard implementation team.

##### Sample request {#sample-request-2}

```json
{
  "items": [
    {
      "description": "Merchandise",
      "paymentOption": "POINTS_ONLY",
      "pointsRedeemed": 3,
      "redemptionMatrixItemId": "41275",
      "quantity": 1,
      "additionalDetails": {
        "sourceItemId": "testItemId1",
        "merchantPartnerId": "partner1",
        "merchantId": "Merchant1",
        "itemSkuCode": "2345",
        "redemptionCategory": "Gift Cards",
        "redemptionSubCategory": "Restaurant",
        "promotionId": "promo1"
      }
    }
  ],
  "processedBy": "MRSWSRED",
  "redemptionType": "MERCHANDISE",
  "userId": "220094110178641288073796026652",
  "userIdType": "RANAC"
}
```

##### Sample response {#sample-response-2}

```json
{
  "id": "61e9b1ae-4b4a-4771-95a8-006618779d25",
  "pointBalance": 10792775.1,
  "pointsName": "Test Points Name",
  "programName": "Pay With Rewards - TRANS NOTIF",
  "cashEquivalent": 10792775.10,
  "currencyCode": "USD",
  "items": [
    {
      "itemId": "09eb2569-f206-4781-a5f8-426c282ebdfc",
      "redemptionId": 4611174,
      "redemptionMatrixItemId": "41275"
    }
  ]
}
```

## Key Points of External Item Redemption {#key-points-of-external-item-redemption}

1. This external item redemption request is the same as Merchandise redemption but is identified by the additional details section of the request payload.
2. If additional details are present in the request payload, the redemption type will be considered external.
3. 'itemSkuCode' field must be provided when the customer posts an External Item Redemption request.
4. 'sourceCode' valid values for an external item redemption request are 'EC' or 'ES'.
5. If 'itemSkuCode' is not provided in the request, then the API will throw the below error message and error reason code: 'Invalid request. ItemSkuCode must be provided'. Reason Code '-1'.
6. If value of 'sourceCode' is other than 'EC' or 'ES', then api will throw below error message and error reason code: 'VALID Source Codes for Externally Hosted Item Redemption are 'EC','ES''. Reason Code '-1'.

## Use case #3: TRAVEL Redemption Type {#use-case-3-travel-redemption-type}

* Provides the ability for consumers to process Travel redemptions. Consumers placing orders for travel packages on the travel vendor's website will use generic reward items to perform these redemptions.
* After a booking is complete on the travel vendor's website, the vendor will perform this call, referencing the travel component Reward Items that are set up in Rewards. This notifies Rewards that a travel redemption has been completed and deducts points from the cardholder's balance.
* The below is a typical Travel request. Refer to the field description on the [API reference page](https://developer.mastercard.com/digital-redemptions/documentation/api-reference/index.md) for more information. The request for creating Digital Redemptions with TRAVEL redemptionType have some fields which are NOT mandatory but good to have information.
  * **sourceCode** : Identifier that specifies the channel that generated the redemption. The value needs to be T. This is a unique code assigned to each Merchant when on-boarding to the Digital Redemptions program.
  * **processedBy** : Mastercard Rewards System User ID created for client while on-boarding. This is an ID assigned to each Merchant when on-boarding to the Digital Redemptions program.
  * **currencyCode** : 3-letter ISO Currency Code, for the Digital Redemptions program. If program-specific Currency Code information is not configured on the PWP redemption item, this value will not be returned.
  * **externalId** : External client identifier for the overall redemption request.
  * **paymentOption** : Type of payment used for the redemption. For Digital Merchants payment option should be POINTS_ONLY.
  * **cashEquivalent** : Actual cash value of the pointBalance in currencyCode.
  * **pointsRedeemed** : Total points redeemed for reward Item.
  * **redemptionMatrixItemId** : If an item is being redeemed, the Mastercard Rewards System rewards id specific to issuer program is required. As previously stated, in order to redeem, these IDs must be retrieved/available with the API client.
  * **redemptionItemId** : This is a unique reference to the redemption item that will be used to record the redemption.
  * **description** : Description of the Redemption.
  * **quantity** : Quantity of the item that is redeemed for. Default value is 1.
* The following are the mandatory request parameters:
  * **userId** : The identifier used to uniquely identify an user.
  * **userIdType** : Determines the type of user identification. Supported identifier is RANAC.
  * **totalCashValue** : Total Cash value of the item.
  * **redemptionType** : TRAVEL.
* Please refer to [Scenarios For Redemption Request](https://developer.mastercard.com/digital-redemptions/documentation/use-cases/redemptions/post-redemptions/index.md#scenarios-for-redemption-request) before using the combination of "cashEquivalent", "pointsRedeemed", "redemptionItemId" and "redemptionMatrixItemId".

##### Sample request {#sample-request-3}

```json
{
  "userId": "781083548024764388823967569513",
  "userIdType": "RANAC",
  "redemptionType": "TRAVEL",
  "totalCashValue": 18,
  "currencyCode": "AUD",
  "pointsRedeemed": 12,
  "externalId": "1429038073",
  "processedBy": "MRSWSRED",
  "items": [
    {
      "pointsRedeemed": 1,
      "redemptionItemId": "50243",
      "cashEquivalent": "1",
      "paymentOption": "POINTS_ONLY",
      "quantity": 1
    }
  ]
}
```

##### Sample response {#sample-response-3}

```json
{
  "id": "a351a5d2-2dd4-4c0b-8ceb-0d3f466c8276",
  "pointBalance": 482085,
  "programName": "MR Test Program",
  "pointsName": "Miles",
  "cashEquivalent": 1,
  "currencyCode": "AUD",
  "items": [
    {
      "itemId": "05bf7c3b-0acb-4baa-bb1e-4da68cd09a2c",
      "redemptionId": 4571759,
      "redemptionItemId": "50243"
    }
  ]
}
```

## Eligibility to Redeem {#eligibility-to-redeem}

Once a request for Redeemer information has been received from a Merchant, Mastercard will check that the card being used belongs to a Rewards Program that is configured to participate in redemptions with that Merchant. The Cardholder's eligibility to redeem will also be validated, to ensure that

1. The account has a "Good Standing" or "Redeem Only" status and
2. The account is eligible to redeem - If the account is in a household (i.e. shared with other cardholders) then the account must be a redeemer in the household.

If any of these conditions are not met, the API will return an error message to the merchant, who can use logic within the shopping flow not to offer points redemption on that transaction.

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

When a redemption occurs successfully, the points are decremented from the Cardholder's account. The Merchant will have contracted with Mastercard regarding invoicing and payment terms for the value of these points. The Merchant is responsible for charging the cardholder directly for any balance of the purchase amount that remains after the redemption value is deducted.

In system maintenance application, there is program parameter called "Enable pay with Points Rounding Rule".For any account,linked with the program which has this param enabled, will not allow decimal values of PointsRedeemed in the request.Only whole numbers of points are accepted.

## Scenarios for redemption request {#scenarios-for-redemption-request}

I. Customer sends mastercard how many points to be redeemed.

###### Sample request with pointsRedeemed and redemptionMatrixItemId {#sample-request-with-pointsredeemed-and-redemptionmatrixitemid}

```json
{
  "items": [
    {
      "description": "exp_void",
      "paymentOption": "POINTS_ONLY",
      "quantity": 2,
      "pointsRedeemed": 3,
      "redemptionMatrixItemId": "41275"
    }
  ],
  "processedBy": "E114182",
  "redemptionType": "MERCHANDISE",
  "userId": "220094110178641288073796026652",
  "userIdType": "RANAC"
}
```

II. Customer sends mastercard cash value of redemption and mastercard calculates points to be redeemed.

**Points Rounding** : Issuer programs will be configured to use different points rounding logic. The program level rounding rule will be sent in GET/redeemers or POST/redeemers/search response - roundingMethod(for more details refer API Reference section). While calculating the points internally, API will consider these rounding methods and apply the same logic while calculating points to be redeemed. Below are the rounding rule values and the logic used.

* **UP** : Round up to the nearest whole number. Ex. 10.2467 = 11 or 5.5507 = 6
* **DOWN** : Round down to the nearest whole number. Ex. 10.2467 = 10 or 5.5507 = 5
* **NATURAL** : If the first decimal place is less than 5, then the point value will be round down to the nearest whole number and if the first decimal place is more than or equal to 5 then the point value will be round up to the nearest whole number. This is the default configuration. Ex. 10.2467 = 10 or 5.5507 = 6

###### Sample request with CashEquivalent and redemptionItemId {#sample-request-with-cashequivalent-and-redemptionitemid}

```json
{
  "items": [
    {
      "description": "Merchandise",
      "cashEquivalent": "10",
      "paymentOption": "POINTS_ONLY",
      "quantity": 2,
      "redemptionItemId": "19068"
    }
  ],
  "processedBy": "MRSWSRED",
  "redemptionType": "MERCHANDISE",
  "userId": "220094110178641288073796026652",
  "userIdType": "RANAC"
}
```

III. Customer sends mastercard both cash value of redemption and points to be redeemed. Mastercard calculates points using cash value and ensures it matches with points to be redeemed value sent by the customer. For example : If an user has to redeem 25000 points which are worth $250, then the input CashEquivalent given must be $250.

**Points Rounding** : Issuer programs will be configured to use different points rounding logic. The program level rounding rule will be sent in GET/redeemers or POST/redeemers/search response - roundingMethod(for more details refer API Reference section). While calculating the points, API clients are expected to consider these rounding methods and apply the same logic while calculating pointsRedeemed value. Below are the rounding rule values and expected rounding logic.

* **UP** : Round up to the nearest whole number. Ex. 10.2467 = 11 or 5.5507 = 6
* **DOWN** : Round down to the nearest whole number. Ex. 10.2467 = 10 or 5.5507 = 5
* **NATURAL** : If the first decimal place is less than 5, then the point value will be round down to the nearest whole number and if the first decimal place is more than or equal to 5 then the point value will be round up to the nearest whole number. This is the default configuration. Ex. 10.2467 = 10 or 5.5507 = 6

###### Sample request with both pointsRedeemed and CashEquivalent {#sample-request-with-both-pointsredeemed-and-cashequivalent}

```json
{
  "items": [
    {
      "paymentOption": "POINTS_ONLY",
      "pointsRedeemed": 1,
      "redemptionItemId": "65973",
      "cashEquivalent": "1",
      "description":"Merchandise",
      "quantity": 2
    }
  ],
  "processedBy": "MRSWSRED",
  "redemptionType": "MERCHANDISE",
  "sourceCode": "PP",
  "userId": "194029175821411820021023467619",
  "userIdType": "RANAC"
}
```