Gift Card

'Gift Card' cards support enrolling prepaid cards also known as gift certificate, gift voucher or gift token.

Links (URLs) to get balance and transactions history in real time is provided in the Partners Portal. If a partner needs to integrate communication between Samsung Wallet server and the partner’s server to support the feature, the partner has to set the links in Partners Portal.

Wallet card type

 Wallet card subtype
giftcard

 others

Others

Figure 9: Sample UI: Gift card

Wallet Card data fields

Attributes

Type

 Value

 Description
attributes.{fields}

 title
String (32)

 (Required)
Main title.
e.g., Samsung Gift Card.
eventId
String (36)

 (Optional)
If full cancelation of the event occurs, find and process all gift cards with this ID
orderId
String (36)

 (Optional)
A unique identifier for an order.
subtitle1
String (32)

 (Optional)
The auxiliary field which displays supporting information
logoImage
String (256)

 (Optional)
Logo image URL to be displayed in the card item.
The file size should not exceed 256 KB.
logoImage.darkUrl
String (256)

 (Optional)
Logo image URL in dark mode.
The file size should not exceed 256 KB.
logoImage.lightUrl
String (256)

 (Optional)
Logo image URL in light mode.
The file size should not exceed 256 KB.
providerName
String (32)

 (Required)
Gift card provider name
user
String (64)

 (Optional)
Name of person who holds the gift card
preventCaptureYn
String (1)

 (Optional)
Flag whether this wallet card view prevents screen capture.
Either 'Y' or 'N', the default value is 'N'.
startDate
Long (13)

 (Optional)
Start date (Display Start date).
Epoch timestamp in milliseconds.
endDate
Long (13)

 (Optional)
End date (Display End date).
Epoch timestamp in milliseconds.
locations
String (1024)

 (Optional)
List of locations where the gift card can be used.
* See Location format.
noticeDesc
String (5000)

 (Optional)
Text of the notice.
* Long content is allowed.
* See Additional Information format.
csInfo
String (512)

 (Optional)
Providers’ customer service Information
Using data in JSON format converted to escape string
* Allowed items: call, email, or website
* See the example below.
appLinkLogo
String (256)

 (Required)
App link image URL.
The file size should not exceed 256 KB.
appLinkName
String (32)

 (Required)
App link name
appLinkData
String (256)

 (Required)
Information about the partner app link
bgImage
String (256)

 (Optional)
URL for card art (background) image.
The recommended size for image resources is 888 x 555 px
mainImg
String (256)

 (Optional)
URL for gift card image.
The file size should not exceed 512 KB.
bgColor
String (8)

 (Optional)
Color of the card art.
e.g.,#00FFFF.
fontColor
String (8)

 (Optional)
Color of the font on the card art.
Acceptable values: dark, light.
blinkColor
String (8)

 (Optional)
Color of the blinking effect which indicates that a card cannot be captured in the Indicator area.
e.g., #00FFFF.
barcode.value
String (4096)

 (Optional)
Actual data that is delivered when the barcode/QR code is scanned.
barcode.serialType
String (32)

 (Optional)
Presentation type.
e.g., SERIALNUMBER, BARCODE....
*See Barcode format.
barcode.ptFormat
String (32)

 (Optional)
Presentation format.
e.g., BARCODE, QRCODE, SERIAL....
*See Barcode format.
barcode.ptSubFormat
String (32)

 (Optional)
Presentation sub-format.
e.g., CODE_128, QR_CODE....
* See Barcode format.
barcode.pin
String (16)

 (Optional)
PIN to show with a barcode
barcode.errorCorrectionLevel
String (4)

 (Optional)
Amount of redundancy or error correction data included in the code.
There are four error correction levels available in QR codes.
* Code options: L/M/Q/H
merchantId
String (36)

 (Optional)
Merchant identifier
merchantName
String (32)

 (Optional)
Merchant name to display
amount
String (32)

 (Optional)
Initial balance.
This is going to be shown as received.
e.g., $1,000.
balance
String (32)

 (Optional)
Remaining balance.
This is going to be shown as received.
e.g., $1,000.
summaryUrl
String (256)

 (Optional)
Web url that show details, such as balance or transactions history.

Example

{
    "card": {
        "type": "giftcard",
        "subType": "others",
        "data": [
            {
                "refId": "b3fdc982-28c9-47a3-b02f-d484779698a7",
                "createdAt": 1672574400000,
                "updatedAt": 1672574400000,
                "language": "en",
                "attributes": {
                    "title": "Samsung Gift Card",
                    "eventId": "event-001",
                    "logoImage": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "logoImage.darkUrl": "https://gpp.walletsvc.samsung.com/mcs/images/contents/wallet_intro_logo.png",
                    "providerName": "Samsung Gift Card Provider",
                    "user": "MS. Jane Doe",
                    "noticeDesc": "<ul><li>Gift Card Test</li></ul>",
                    "csInfo": "{\"call\":\"0000-0000\",\"email\":\"samsungwallet@samsungwallet.com\",\"webSite\":\"https://www.samsungwallet.com/cs/\" }",
                    "appLinkLogo": "https://play-lh.googleusercontent.com/ZnFa1roZ7hpv9j-jIAcBjmjuDl2x-FnuwTE0OYvbbcwvf5VPzOQQiKBXGK7d-APTvag=w240-h480-rw",
                    "appLinkName": "Gift Card Link",
                    "appLinkData": "https://www.samsung.com/",
                    "bgColor": "#0A1A4F",
                    "fontColor": "light",
                    "blinkColor": "#00FFFF",
                    "barcode.value": "CS16138353212584806754FG1802",
                    "barcode.serialType": "QRCODE",
                    "barcode.ptFormat": "QRCODESERIAL",
                    "barcode.ptSubFormat": "QR_CODE"
                }
            }
        ]
    }
}

Business Support for Special Purposes

Server APIs are provided for cases where it is necessary to manage a large number of cards. Cards created through API can also be checked and managed in the same way on the ‘Wallet Partners Portal'.

Changes to each card status can be processed at the ‘Wallet Partners Portal', and information on how to change them should be checked through the Partner Server Portal Guide. The attributes related to the server API are as follows.

Attributes

Type

 Value

 Description
Payload object

 cardTemplate
Object

 (Required)
Wallet card template object
cardTemplate.prtnrId
String(32)

 (Required)
Partner ID
cardTemplate.templateRefId
String(19)

 (Required)
Partner Template ID
cardTemplate.title
String(32)

 (Required)
Wallet Card Name
cardTemplate.countryCode
String(2)

 (Conditional)
The Main (Headquarters) Location.
* Required when creating a template
cardTemplate.cardType
String(100)

 (Conditional)
This value is set to “giftcard”.
* Required when creating a template.
cardTemplate.subType
String(100)

 (Conditional)
This value is set to “others”.
* Required when creating a template.
cardTemplate.prtnrAppPckgName
String(128)

 (Optional)
The Application Package Name.
cardTemplate.appLogoImg
String(200)

 (Optional)
The banner logo image URL.
cardTemplate.noNetworkSupportYn
String(1)

 (Optional)
This must be set to either 'Y' or 'N'.
* Default: 'N'.
cardTemplate.shareButtonExposureYN
String(1)

 (Optional)
This must be set to either 'Y' or 'N'.
* Default: 'Y'.
cardTemplate.privacyModeYn
String(1)

 (Optional)
This must be set to either 'Y' or 'N'.
* Default: 'N'.
cardTemplate.preventCaptureYn
String(1)

 (Optional)
This value is a screen capture prevention flag that defines whether the content view prevents screen capture.
cardTemplate.state
String(15)

 (Optional)
Wallet card's state
* Default: 'DRAFT'
cardTemplate.testingModeOff
String(1)

 (Optional)
TestMode Off
Either 'Y' or 'N'
* Default: ‘N’
Available only when updating templates
cardTemplate.desc
String(500)

 (Optional)
Description

 
{
  "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",
  }
}