# Parameters source: https://developer.mastercard.com/easy-savings-specials/documentation/parameters/index.md ## 1. Offers {#1-offers} Retrieves all available Mastercard Easy Savings Specials Merchant Offers specific to a given 8-digit BIN, country, and language. | Method | Endpoint | |--------|--------------------------------| | `GET` | `/easysavings/specials/offers` | ### Query parameters {#query-parameters} | Parameter | Description | Required | Type | Example | |------------|---------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|----------| | `bin` | The first 8 digits of the card are used for identifying offers available for a cardholder. | Yes | string | 52345678 | | `country` | The three-letter ISO country code [ISO 3166-1 alpha-3](https://www.iso.org/iso-3166-country-codes.html), uniquely identifying each country. | Yes | string | IND | | `language` | A list of supported languages in the country in [IETF BCP 47 format](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1). | Yes | string | en-US | | `offset` | Number of offers to bypass before starting offer retrieval. The default value is 0. | No | integer | 10 | | `limit` | Maximum number of offers to display per page. The default value is 30. | No | integer | 5 | ### Sample request {#sample-request} ```h https://sandbox.sme.api.mastercard.com/easysavings/specials/offers?bin8=52345678&country=IND&language=en-US&offset=10&limit=5 ``` ### Response body parameters {#response-body-parameters} Note: Default parameter type is **String** unless explicitly mentioned. | Attribute | Description | |---------------------|--------------------------------------------------------------------------------------------| | `entity` | Specifies the type of response. - Example: **Collection** | | `offset` | Number of offers to bypass before starting offer retrieval. - Type: **Integer** | | `limit` | Maximum number of offers to display per page. The default value is 30. - Type: **Integer** | | `count` | Number of offers available in the requested dataset. - Type: **Integer** | | `total` | Number of offers available in the data collection. - Type: **Integer** | | `offers` | List of offers provided for the particular BIN. - Type: **Array of offerAttributes** | | `offerId` | The unique identifier for the offer. | | `type` | The type of the offer. | | `status` | The status of the offer. - Example: **Active** , **Expired** | | `startDate` | Start date of the offer. - Format: **Date (YYYY-MM-DD)** | | `endDate` | End date of the offer. - Format: **Date (YYYY-MM-DD)** | | `displayParameters` | Display details of the offer. - Type: **Object** | | `name` | The name of the offer. | | `description` | A detailed description of the offer. | | `terms` | Terms and conditions of the offer. | | `redemptionChannel` | Platform for redeeming the offer. - Example: **Online** - Type: **Array of Strings** | | `redemptionUrl` | The URL where the offer can be redeemed. | | `imageUrl` | A URL of the offer image. | | `merchant` | Details about the merchant providing the offer. - Type: **Object** | | `name` | The name of the merchant providing the offer. | | `website` | The official website of the merchant. | | `description` | Description of the merchant and the services they provide. | | `logoUrl` | The URL of the merchant logo. | | `Categories` | Different categories of offers are present. - Type: **Array of Strings** | ### Sample response {#sample-response} ```java { "entity": "collection", "offset": 0, "limit": 30, "count": 1, "total": 30, "offers": [ { "offerId": "QDWC0NRZmyabde", "type": "offer", "status": "active", "startDate": "2023-12-21", "endDate": "2024-09-14", "displayParameters": { "name": "Amazon Special Offer", "description": "Get 10% off on your purchase", "terms": "Minimum purchase of 1000 rupees required", "redemptionChannels": [ "online" ], "redemptionUrl": "https://www.test.com/redeem", "imageUrl": "https://www.test.com/" }, "merchant": { "name": "Amazon", "website": "https://www.amazon.com/", "description": "Online shopping platform", "logoUrl": "https://merchant.com/" }, "categories": [ "shopping" ] } ] } ``` ## 2. Redemptions {#2-redemptions} Creates a unique Redemption Order ID and fetches redemption details against the request. | Method | Endpoint | |--------|-----------------------------------| | `POST` | /easysavings/specials/redemptions | ### Request body parameters {#request-body-parameters} | Field | Description | Required | Type | Example | |------------|--------------------------------------------------------------------------------------------|----------|--------|----------------| | `bin` | The first 8 digits of the card are used for identifying offers available for a cardholder. | Yes | string | 52345672 | | `offer.id` | Unique identifier for the offer. | Yes | string | QDWC0NRZmyabde | ### Sample request {#sample-request} ```h https://sandbox.sme.api.mastercard.com/easysavings/specials/redemptions ``` ```java { "bin": "52345678", "offers": [ { "id": "QDWC0NRZmyabde" } ] } ``` ### Response body parameters {#response-body-parameters} Note: Default parameter type is **String** unless explicitly mentioned. | Attribute | Description | |--------------|-------------------------------------------------------------------------------------------| | `orderId` | The unique identifier for the order. | | `entity` | Specifies the type of response. - Example: **Orders** | | `status` | The status of the order. - Example: **Success** , **Pending** | | `createdAt` | The date when the order was created. - Format: **Date (YYYY-MM-DD)** | | `orders` | Contains details of the order. - Type: **Object** | | `count` | Number of order items in the order. - Type: **Integer** | | `orderItems` | A list of individual order items. - Type: **Array of OrderItemAttributes** | | `offerId` | The unique identifier for the offer associated with the order. | | `status` | The status of the order item. - Example: **Success** | | `vouchers` | A list of vouchers associated with the order item. - Type: **Array of VoucherAttributes** | | `code` | The voucher code linked to the offer. | ### Sample response {#sample-response} ```java { "orderId": "QITxGqu30qzxcv", "entity": "orders", "status": "success", "createdAt": "2022-12-20", "orders": { "count": 1, "orderItems": [ { "offerId": "QDWC0NRZmyabde", "status": "success", "vouchers": [ { "code": "test" } ] } ] } } ``` Retrieves redemption details generated previously in POST `/redemptions`. | Method | Endpoint | |--------|----------------------------------------------| | `GET` | /easysavings/specials/redemptions/{order_id} | #### Path parameter {#path-parameter} | Parameter | Description | Required | Type | Example | |------------|-----------------------------------------------------------------------|----------|--------|----------------| | `order_id` | A reusable unique identifier created for the redemption request made. | Yes | string | QDWC0NRZmyabde | ### Sample request {#sample-request} ```h https://sandbox.sme.api.mastercard.com/easysavings/specials/redemptions/QDWC0NRZmyabde ``` ### Response body parameters {#response-body-parameters} Note: Default parameter type is **String** unless explicitly mentioned. | Attribute | Description | |--------------|-------------------------------------------------------------------------------------------| | `orderId` | The unique identifier for the order. | | `entity` | Specifies the type of response. - Example: **Orders** | | `status` | The status of the order. - Example: **Success** , **Pending** | | `createdAt` | The date when the order was created. - Format: **Date (YYYY-MM-DD)** | | `orders` | Contains details of the order. - Type: **Object** | | `count` | Number of order items in the order. - Type: **Integer** | | `orderItems` | A list of individual order items. - Type: **Array of OrderItemAttributes** | | `offerId` | The unique identifier for the offer associated with the order. | | `status` | The status of the order item. - Example: **Success** | | `vouchers` | A list of vouchers associated with the order item. - Type: **Array of VoucherAttributes** | | `code` | The voucher code linked to the offer. | ### Sample response {#sample-response} ```java { "orderId": "QITxGqu30qzxcv", "entity": "orders", "status": "success", "createdAt": "2022-12-20", "orders": { "count": 1, "orderItems": [ { "offerId": "QDWC0NRZmyabde", "status": "success", "vouchers": [ { "code": "test" } ] } ] } } ``` ## 3. Countries {#3-countries} Retrieves the list of countries, with the default language of each country. | Method | Endpoint | |--------|---------------------------------| | `GET` | /easysavings/specials/countries | ### Request parameter {#request-parameter} No request parameters required. ### Sample request {#sample-request} ```h https://sandbox.sme.api.mastercard.com/easysavings/specials/countries ``` ### Response body parameters {#response-body-parameters} Note: Default parameter type is **String** unless explicitly mentioned. | Parameter | Description | |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `data` | Contains a list of countries where offers, categories, and redemptions are valid. - Type: **Array of Objects** | | `countries` | Contains details about each country where the offers are valid. - Type: **Array of Country Objects** | | `isoCode` | The three-letter ISO country code, uniquely identifying each country. - Example: **EGY** - Format: [ISO 3166-1 alpha-3](https://www.iso.org/iso-3166-country-codes.html) | | `languages` | A list of supported languages in the country. - Type: **Array of Language Objects** - Format: [IETF BCP 47 format](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) | | `languageCode` | The language code identifying a specific language used in the country. - Example: **ar-SA** - Format: [IETF BCP 47](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) | ### Sample response {#sample-response} ```java { "countries": [ { "isoCode": "EGY", "languages": [ { "languageCode": "ar-SA" } ] } ] } ```