Card Template Management
buses, others ticket performances, sports, movies, entrances, others coupon others giftcard others loyalty others idcard employees, nationals, students, drivers, guests, others digitalkey doors, residents, hotels, cars, others payasyougo evcharges, others generic others reservation rentalcars, restaurants, accommodations, etickets, taxis, activities, others transitcard others clip businesstrips, trips, others wallet card templates attributes type value description payload cardtemplateobject required wallet card template object cardtemplate titlestring 32 conditional wallet card name* required when adding wallet card template cardtemplate countrycodestring 2 conditional the main headquarters location * required when adding wallet card template cardtemplate cardtypestring 100 conditional this value is set to cardtype * required when adding wallet card template cardtemplate subtypestring 100 conditional this value is set to subtype * required when adding wallet card template cardtemplate designtypestring 100 optional the value that definesthe design type of the wallet card * for generic templates i e , when cardtype is set to generic , set designtype to one of the following values "generic 01", "generic 02", or "generic 03" * default "generic 01" cardtemplate prtnrapppckgnamestring 128 optional the application package name cardtemplate applogoimgstring 200 optional the banner logo image url cardtemplate nonetworksupportynstring 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate sharebuttonexposureynstring 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate privacymodeynstring 1 optional this must be set to either 'y' or 'n' * default 'n' cardtemplate preventcaptureynstring 1 optional this value is a screen capture prevention flag that defines whether the content view prevents screen capture cardtemplate sharebuttonexposureynstring 1 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate prtnrcarddatastring 1000 optional [get card data] partner url check the url format below and implement the api according to the url refer to get card data for instance, you can use https //{yourdomain} cardtemplate prtnrcardstatestring 1000 optional [get card state] partner url check the url format below and implement api according to url refer to send card state send card event for instance, you can use https //{yourdomain} cardtemplate statestring 15 optional wallet card's state* default 'verifying'a card is always created in the verifying state; this field cannot be set at creation time use this field in the update api to change the state to active only the verifying → active transition is supported cardtemplate testingmodeoffstring 1 optional testmode off this must be set to either 'y' or 'n' * default ‘n’ * available only when updating templates cardtemplate saveinserverynstring 2 optional this must be set to either 'y' or 'n' * default 'y' cardtemplate categorystring 20 optional select from the following values “parking_pass”, “membership”, “reservations”, “insurance”, “health”, “receipt”, “coupon_stamp”, “note”, “photo”, and “others” * this field is applicable only to generic card templates i e , when cardtype is set to generic cardtemplate descstring 500 optional description cardtemplate layoutobject optional defines presentation rules for card data in samsung wallet this field is applicable only when the designtype is set to generic-{subtype}-default for detailed specifications, see the section layout specs examples boarding pass { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551312", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "boardingpass", "subtype" "airlines", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } } event ticket { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551314", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "ticket", "subtype" "entrances", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "n", "privacymodeyn" "n", "preventcaptureyn" "n" } } coupon { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551313", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "coupon", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n", } } gift card { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551315", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "gift", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n", } } loyalty { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551316", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "loyalty", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "n", "privacymodeyn" "n", "preventcaptureyn" "n" } } digital id { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551317", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "idcard", "subtype" "employees", "applogoimg" "http //www yourdomain com/banner_logo_image png", "saveinserveryn" "y", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } } pay as you go { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551318", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "payasyougo", "subtype" "evcharges", "applogoimg" "http //www yourdomain com/banner_logo_image png", "nonetworksupportyn" "n", "sharebuttonexposureyn" "y", "privacymodeyn" "n", "preventcaptureyn" "n" } } generic card { "cardtemplate" { "prtnrid" "4082825513190138240", "templaterefid" "2138240408282551319", "title" "wallet card title", "prtnrapppckgname" "prtnrapppckgname", "countrycode" "us", "desc" "desc", "cardtype" "generic", "subtype" "others", "applogoimg" "http //www yourdomain com/banner_logo_image png", "designtype" "generic 02", "nonetworksupportyn" "n", "category" "membership", "privacymodeyn" "n", "preventcaptureyn" "n" } } layout specs this document provides detailed specifications for the layout field used when adding wallet card templates through the card management api it is intended to be referenced from the layout field description in the adding wallet card template overview this section describes the specification of the layout field used when adding wallet card template the layout object defines presentation rules for card data in samsung wallet it does not contain display values directly instead, it references card data using attribute keys layout object structure the layout object consists of three sections header primary auxiliary each section defines a layout preset and a list of entry mappings type value description layout object layoutobject optional defines presentation rules for card data in samsung wallet layout headerobject required defines the header area of the card layout header presetstring 10 required header layout preset allowed values logo, logotext, text layout header entries[]array of object required list of entry mappings that define how header ui slots reference card data layout header entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout header entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value layout primaryobject required defines the primary content area of the card layout primary presetstring 20 required primary layout preset generic cards landscape, square, vertical, textonlyboarding pass threefields, fourfields, fivefields layout primary entries[]array of object required list of entry mappings that define how primary ui slots reference card data layout primary entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout primary entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value layout primary useboardingtimeboolean optional controls which time is displayed on the boarding pass card - false default displays the departure time- true displays the boarding start timeapplies only when cardtype = boardingpass layout auxiliaryobject required defines additional information displayed when the card is expanded layout auxiliary presetstring 20 optional defines the number of fields to be displayed allowed values twofields, threefields, fourfields layout auxiliary entries[]array of object required ordered list of fields rendered as label–value pairs each value is an attribute key layout auxiliary entries[] entrynamestring 100 required identifier of the ui slot format {role}_{index} e g , image_01, field_01, subfield_01 layout auxiliary entries[] entrykeystring 100 required attribute key used to retrieve the corresponding data value example { "layout" { "header" { “preset” "logotext", "entries" [ { "entryname" "image_01", "entrykey" "providerlogo" }, { "entryname" "field_01", "entrykey" "providername" }, { "entryname" "subfield_01", "entrykey" "vehiclenumber" } ] }, "primary" { “preset” "square", "entries" [ { "entryname" "image_01", "entrykey" "wideimage" }, { "entryname" "field_01", "entrykey" "grade" }, { "entryname" "field_02", "entrykey" "seatclass" } ] }, "auxiliary" { “preset” "twofields", "entries" [ { "entryname" "field_01", "entrykey" "entrance" }, { "entryname" "field_02", "entrykey" "seatnumber" } ] } } } header – required entryname by preset preset required entryname description logo image_01, subfield_01 logo image with secondary text logotext image_01, field_01, subfield_01 logo image with primary and secondary text text field_01, subfield_01 primary and secondary text without image primary – required entryname by preset preset required entryname description landscape image_01 landscape image only square image_01, field_01, field_02 square image with two text fields vertical image_01, field_01, field_02 vertical image with two text fields textonly field_01 single text field without image primary / auxiliary – field-based presets preset required entryname description twofields field_01, field_02 displays two label–value pairs threefields field_01, field_02, field_03 displays three label–value pairs fourfields field_01, field_02, field_03, field_04 displays four label–value pairs fivefields field_01, field_02, field_03, field_04, field_05 displays five label–value pairs allowed where applicable data mapping layout → card data the layout object does not contain display values each field defined in layout references card data using an attribute key this section describes how attribute keys are resolved data resolution rule when a field is defined in layout, the value is resolved from the following locations in order card data[] attributes card data[] attributes extendedfields[] entrykey standard attribute mapping if the entrykey defined in layout matches a field inside card data[] attributes the value is resolved directly from that attribute example layout … "primary" { … “preset” "square", "entries" [ { "entryname" "field_01", "entrykey" "providername " }, … } … example card data[] "attributes" { … "providername" "samsung wallet" … } extended fields mapping in addition to predefined attributes, layout fields may reference values inside extendedfields extendedfields is a user-defined data container that allows partners to define additional fields not included in the standard card specification extendedfields structure { "card" { "data" [ { … "attributes" { … "extendedfields" [ { "label" "gate", "value" "a12", "entrykey" "gatenumber" }, { "label" "zone", "value" "3", "entrykey" "boardingzone" } ] } } ] } } extendedfields resolution logic if the layout field key does not exist in predefined attributes the system searches attributes extendedfields[] entrykey when a matching entrykey is found value → resolved from extendedfields[] value label → resolved from extendedfields[] label example layout referencing extendedfields … "auxiliary" { “preset” "twofields", "entries" [ { "entryname" "field_01", "entrykey" "gatenumber" }, { "entryname" "field_02", "entrykey" "boardingzone" } ] } … result • gatenumber → value "a12", label "gate" • boardingzone → value "3", label "zone" mapping priority if the same key exists in both • predefined attributes • extendedfields the resolution priority is • attributes predefined fields • extendedfields summary • layout fields reference data by attribute key • standard attributes are resolved first • extendedfields enables user-defined data expansion • layout does not directly contain display value