--- title: "Gift Cards" url: "https://developer.migros.ch/apis/gift-cards-8/versions/b48148c4-b8c0-4d7f-a962-d965d98935d0" --- # Gift Cards OpenAPI specification document. ```json {"components":{"parameters":{"Accept-Language":{"description":"Defines the language (de/fr/it/en) for this request as request header. Either use the query param \"lang\" or header \"Accept-Language\", not both.","in":"header","name":"Accept-Language","schema":{"default":"de","enum":["de","fr","it","en"],"type":"string"}},"lang":{"description":"Defines the language (de/fr/it/en) for this request as query parameter. Either use the query param \"lang\" or header \"Accept-Language\", not both.","in":"query","name":"lang","schema":{"default":"de","enum":["de","fr","it","en"],"type":"string"}}},"responses":{},"schemas":{"Classification":{"description":"Represents a gift card classification.","properties":{"category_code":{"type":"string"},"label":{"nullable":true,"type":"string"},"label_code":{"description":"Position in the category.","type":"string"},"position_in_category":{"type":"integer"},"value":{"description":"Value of the classification.","nullable":true,"type":"string"},"value_code":{"description":"Value code of the classification.","nullable":true,"type":"string"}},"required":["label_code"],"type":"object"},"GiftCard":{"description":"Represents a gift card in the API.","properties":{"classifications":{"description":"Collection of classification instances.","items":{"$ref":"#/components/schemas/Classification"},"type":"array"},"digital":{"description":"Is this a digital gift card or not.","type":"boolean"},"disclaimer":{"description":"Terms and conditions.","nullable":true,"type":"string"},"hint":{"nullable":true,"type":"string"},"id":{"description":"ID of the gift card.","type":"string"},"image":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/Image"}]},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"Image":{"description":"An image and its properties.","properties":{"code":{"deprecated":true,"description":"Code for the image, useful for pictograms.","nullable":true,"type":"string"},"custom":{"deprecated":true,"description":"Image URL with placeholders for {width} and {height}.","type":"string"},"description":{"deprecated":true,"description":"Image description, useful for example as alt attribute.","nullable":true,"type":"string"},"end_date":{"deprecated":true,"description":"End date of the validity.","format":"date-time","nullable":true,"type":"string"},"hash":{"deprecated":true,"description":"Sha1 hash of original image.","nullable":true,"type":"string"},"original":{"deprecated":true,"description":"Full size image.","type":"string"},"source":{"deprecated":true,"description":"Source where the image comes from originally.","nullable":true,"type":"string"},"stack":{"deprecated":true,"description":"Image URL with a placeholder for a Rokka {stack}.","type":"string"},"start_date":{"deprecated":true,"description":"Start date of the validity.","format":"date-time","nullable":true,"type":"string"},"tags":{"deprecated":true,"items":{"type":"string"},"type":"array"}},"type":"object"}},"securitySchemes":{"Kong-Api-Key":{"description":"Kong key-auth authentication","in":"header","name":"X-Api-Key","type":"apiKey"},"basicAuth":{"scheme":"basic","type":"http"}}},"info":{"contact":{"email":"arg_mgb-udp-products-services@mgb.ch","name":"MGB-UDP-Products-Services"},"description":"Get information about gift cards. See Wiki","title":"Gift Cards","version":"8"},"openapi":"3.0.0","paths":{"/migros/customers/payment-methods/v1/giftcards/{id}":{"get":{"description":"Get information about a single type of gift card by ID.\n\nSpecify language via Accept-Language header.","operationId":"get-giftcard","parameters":[{"description":"Gift card ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/Accept-Language"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}},"description":"Returned when successful"}},"summary":"Get a single type of gift card (language-dependent)","tags":["Gift Cards"]}},"/migros/customers/payment-methods/v1/personal-giftcards/{person_id}/cards/{card_id}":{"get":{"description":"Returns status information about the specified personal gift card.","operationId":"get-personal-giftcard","parameters":[{"description":"Customer's person ID.","in":"path","name":"person_id","required":true,"schema":{"type":"string"}},{"description":"Gift Card Id","in":"path","name":"card_id","required":true,"schema":{"type":"string"}},{"description":"Gift Card Pin. Required for security reasons, even though not mandatory by gift card SOAP service.","in":"query","name":"pin","required":true,"schema":{"type":"string"}},{"description":"Gift Card POS Protocol Specification Version 1.5.0.","in":"query","name":"POS_ID","schema":{"maxLength":16,"type":"string"}},{"description":"Gift Card POS Protocol Specification Version 1.5.0.","in":"query","name":"TERMINAL_ID","schema":{"maxLength":16,"type":"string"}},{"description":"Store Number/Merchant number.","in":"query","name":"STORE_ID","schema":{"maxLength":16,"type":"string"}},{"description":"The name of the sales person.","in":"query","name":"SELLER_NAME","schema":{"maxLength":32,"type":"string"}},{"description":"Local transaction date from POS.","in":"query","name":"POS_TIMESTAMP","schema":{"format":"date-time","type":"string"}},{"description":"Transaction ID from POS.","in":"query","name":"POS_TRANS_ID","schema":{"maxLength":16,"type":"string"}},{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/Accept-Language"}],"responses":{"200":{"description":"Returned when successful"},"400":{"description":"Returned when the request is incorrect"},"403":{"description":"Returned when the gift card is not found or pin is invalid"},"502":{"description":"Returned when the gift card backend has a problem"}},"summary":"Returns status information about the specified personal gift card.","tags":["Gift Cards"]}},"/migros/customers/payment-methods/v1/personal-giftcards/{person_id}/cards/{card_id}/virtualize":{"post":{"description":"This registers the information that this gift card is used on an electronic system into the gift card server.\nThis call fetches the gift card to check if it really is already active, then creates a transaction for the gift card,\nand sends a fake activation call to the gift card server. This activation is expected to fail (as the card is already active)\nbut will be logged on the gift card server side so that people know that this card is associated with a mobile device.","operationId":"virtualize-personal-giftcard","parameters":[{"description":"Customer's person ID.","in":"path","name":"person_id","required":true,"schema":{"type":"string"}},{"description":"Gift Card ID to activate.","in":"path","name":"card_id","required":true,"schema":{"type":"string"}},{"description":"Gift Card Pin. Required for security reasons, even though not mandatory by gift card SOAP service.","in":"query","name":"pin","required":true,"schema":{"type":"string"}},{"description":"Gift Card POS Protocol Specification Version 1.5.0.","in":"query","name":"POS_ID","schema":{"maxLength":16,"type":"string"}},{"description":"Gift Card POS Protocol Specification Version 1.5.0.","in":"query","name":"TERMINAL_ID","schema":{"maxLength":16,"type":"string"}},{"description":"Store Number/Merchant number.","in":"query","name":"STORE_ID","schema":{"maxLength":16,"type":"string"}},{"description":"The name of the sales person.","in":"query","name":"SELLER_NAME","schema":{"maxLength":16,"type":"string"}},{"description":"Local transaction date from POS.","in":"query","name":"POS_TIMESTAMP","schema":{"format":"date-time","type":"string"}},{"description":"Transaction ID from POS.","in":"query","name":"POS_TRANS_ID","schema":{"maxLength":16,"type":"string"}}],"responses":{"200":{"description":"Returned when successful"},"400":{"description":"Returned when the request is incorrect"},"404":{"description":"Returned when the gift card is not found"},"502":{"description":"Returned when the gift card backend has a problem"}},"summary":"Virtualizes the specified gift card which must be already active.","tags":["Gift Cards"]}},"/migros/customers/payment-methods/v1/personal-giftcards/{person_id}/profiles/{profile}":{"post":{"description":"Each user may only have one single electronic gift card. If the user already has a gift card, this call just returns that card, but without the CARD_PIN information.\n\nThis call checks if mgo provides a stored digital card for the current user. If so, that card is returned,\notherwise a new card is created with the gift card server, the card id converted to a product id (with the 2of5 checksum)\nand stored in mgo for later use. The pin is not stored on any server and thus only sent once for a new card.\nThere is no recovery process for lost pins because the gift card server does not provide one.\nThe app has to make sure the user creates backups of the pin for his virtual card.","operationId":"create-personal-giftcard","parameters":[{"description":"Customer's person ID.","in":"path","name":"person_id","required":true,"schema":{"type":"string"}},{"description":"Profile of the card to create.","in":"path","name":"profile","required":true,"schema":{"type":"string"}},{"description":"Gift Card POS Protocol Specification Version 1.5.0.","in":"query","name":"TERMINAL_ID","schema":{"maxLength":16,"type":"string"}},{"description":"Store Number/Merchant number.","in":"query","name":"STORE_ID","schema":{"maxLength":16,"type":"string"}},{"description":"The name of the sales person.","in":"query","name":"SELLER_NAME","schema":{"maxLength":32,"type":"string"}},{"description":"Local transaction date from POS.","in":"query","name":"POS_TIMESTAMP","schema":{"format":"date-time","type":"string"}},{"description":"Transaction ID from POS.","in":"query","name":"POS_TRANS_ID","schema":{"maxLength":16,"type":"string"}}],"responses":{"200":{"description":"Returned when successful"},"400":{"description":"Returned when the request is incorrect"},"404":{"description":"Returned when the profile is not found"},"502":{"description":"Returned when the gift card backend has a problem"}},"summary":"Creates a new gift card with the specified profile.","tags":["Gift Cards"]}}},"security":[{"Kong-Api-Key":[],"basicAuth":[]}],"servers":[{"description":"URL of upstream","url":"https://api.migros.ch"}],"tags":[{"name":"Gift Cards"},{"name":"mapi"}],"x-active-from":"01-01-2024","x-company":"migros","x-edm-domain":"products","x-eol":"31-12-2049","x-headmatter":{"readable_by":"*"},"x-kong-route-defaults":{"protocols":["https"],"strip_path":false},"x-kong-service-defaults":{"connect_timeout":5000,"read_timeout":15000,"retries":1,"write_timeout":5000},"x-leanIx-id":"350641a5-55a2-4641-8332-76d32846eb56","x-link-get-access":"https://forms.office.com/e/zhzbEqAQ26","x-link-get-support":"https://teams.microsoft.com/l/channel/19%3Aa7851e50d0194268ba0c7a0d7a63403b%40thread.tacv2/2.%20Support%20%F0%9F%92%A1?groupId=58b919a5-7d36-47f3-a77a-03cfd051098a&tenantId=35aa8c5b-ac0a-4b15-9788-ff6dfa22901f"} ```