API Guidelines

Adding Wallet Card Specs

When integrating with Samsung Wallet, the Add to Wallet functionality allows users to securely add cards (such as loyalty cards, payment cards, or tickets) to their Samsung Wallet app. To ensure a smooth and successful integration, partners need to follow specific API guidelines for adding card specs.

Here is an overview of the steps and key components you need to consider when integrating the API for adding wallet cards.

Data Transmit Link

The Data Transmit Link is the API endpoint through which partners send the initial card data (e.g., card number, expiration date, issuer information, barcode, etc.) to Samsung Wallet.

The most common and straightforward method is the Data Transmit Link approach, which securely includes tokenized data in the ATW link. The ATW link format for this method is as follows:

Type

 Value

 Description
URL

 https://a.swallet.link/atw/v3/{cardId}#Clip?cdata={cdata}
Path parameters

 cardId
String

 (Required)
Wallet card identifier issued from Partner portal when the partner manager
signs up for partner services and registers the wallet card they want to service.
Hash path parameters

 #Clip
String

 (Required)
Parameters for the Hash link
* The first letter is capitalized
Query parameters

 cdata
String

 (Required)
Actual payload data in basic JSON format to communicate between partners
and Samsung Wallet.
This must be secured in JWT(JSON Web Token) format.
* See Security

Example - <https://a.swallet.link/atw/v3/1656147182764415319#Clip?cdata={JWE card data token}>

Data Fetch Link

The Data Fetch Link allows partners to retrieve card details after the card has been added to the Samsung Wallet.
In cases involving sensitive data or when providing static links, Data Fetch Link method is highly recommended. Links using this approach include only a unique reference ID, and Wallet Cards are added by querying data through Get Card Data path as specified in Partner portal.

Type

 Value

 Description
URL

 https://a.swallet.link/atw/v3/{CertificateId}/{cardId}#Clip?pdata={pdata}
Path parameters

 certificateId
String(4)

 (Conditional)
ertificate identifier based on a CSR during onboarding.
4 digits alphanumeric.
* Must be generated from Partner Portal
cardId
String(32)

 (Required)
Wallet card identifier.
* It must be generated from Partners Portal.
Hash path parameters

 #Clip
String(5)

 (Required)
Parameters for the Hash link
Query parameter

 pdata
String(128)

 (Required)
Unique ID defined by content providers.
This has identification for each user's Wallet Card contents.
* For secure transactions, a Reference ID (refId) must be in a form that cannot be inferred.

Example - https://a.swallet.link/atw/v3/YMtt/1656147182764415319#Clip?pdata=sIgHCzIwM9g

Data Action Link

This API is a link-based execution interface that triggers predefined user actions via the adata parameter. When opened, the app/web screen collects user inputs as required. On successful authentication, the flow continues into registration, and the partner must return the necessary card data or identifier to complete process.
This API is primarily used to invoke the Request Action API. See the Request Acoion API section for further details.

Type

 Value

 Description
URL

 https://a.swallet.link/atw/v3/{certificateId}/{cardId}#Clip?adata={adata}
Path parameters

 certificateId
String(4)

 (Conditional)
Certificate identifier based on a CSR during onboarding.
4 digits alphanumeric.
* Must be generated from Partner Portal
* Required if using v3 path
cardId
String(32)

 (Required)
Wallet card identifier.
* It must be generated from Partners Portal.
Hash path parameters

 #Clip
String(5)

 (Required)
Parameters for the Hash link
Query parameter

 pdata
String(16)

 (Required)
Specified the predefined action to execute when the link is opened. The App/Web UI collects inputs as required by server configuration. By default, once authentication succeeds, the process automatically continues into registration, with the partner returning the necessary card data or identifier for the authenticated user. Allowed values: user_auth

Example - https://a.swallet.link/atw/v3/{certificateId}/{cardId}#Clip?adata=user_auth

Updating Wallet Card Specs

When users add cards to Samsung Wallet, their data can be updated through server interactions. To manage these updates, partners need to configure their API settings via the Partner Portal.

Follow the steps below to manage and update the cards added to Samsung Wallet:

  1. Samsung server will notify the result of 'Add to Wallet' via Send Card State.
  2. Partners get the callback URL for Samsung Server API from Send Card State payload.
  3. Using the callback URL, partners can make actions for the added cards via Samsung Server API.
  4. Depending on the interfaces, Samsung Server triggers specific operations. For example, when Update Notification is called, Samsung server calls partners' server to look up the updated contents.

![](https://d3 unf4s5rp9dfh.cloudfront.net/SamsungWallet_doc/updating-wallet-card-specs.png)

Partner Server API

Samsung server can call the following API by using endpoint on the registered card information. If the partner server manages an inbound allow list, contact us to register Samsung server IP address.

Get Card Data

The Get Card Data allows partners to retrieve the most up-to-date information about a card that has already been added to Samsung Wallet. This API is crucial for ensuring that the partner’s system has accurate and current details about a user's card, whether for display, transaction validation, or other purposes.

[Request]

Type

 Value

 Description
Method

 GET
URL

 {Partner server URL}/cards/{cardId}/{refId}?fields={fields}
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
String (32)

 (Required)
Wallet card identifier.
* Refer to the 'Add to Wallet' Interfaces
refId
String (32)

 (Required)
A unique content identifier defined by the content provider
Query Parameter

 fields
String(128)

 (Optional)
Attributes which intended to retrieve.
Can be specified using commas(,) as separators.
e.g. balance,barcode.value
Payload

 N/A
Example

 GET /cards/12584806754/ref-20230304-0003

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
204 No Content
Payload
(Option1)

 cdata
String(4096)

 (Conditional)
Card object. (JSON).
* This field needs to be encrypted.
* See Security
Payload
(Option2)

 card
Object

 (Conditional)
Card information.
* Card object as an alternative to cdata.
* If cards includes sensitive data, it is highly recommended using cdata.
card.type
String (16)

 (Required)
Wallet Card type.
* See Wallet Cards
card.data[]
Array of Object

 (Required)
Wallet card data container
data[].refId
String (32)

 (Required)
A unique content identifier defined by the content provider
data[].createdAt
Long (13)

 (Required)
Timestamp of data.
Epoch timestamp in milliseconds.
data[].updatedAt
Long (13)

 (Required)
Timestamp of data.
Epoch timestamp in milliseconds.
data[].state
String (16)

 (Required)
Wallet card state.
For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, CANCELED, PENDING, SUSPENDED.
* See Card States for details
data[].language
String (8)

 (Required)
Default content language code.
e.g., en, ko
data[].attributes
Object

 (Required)
Card data attributes
data[].attributes. {fields}

 Attribute fields by card type.
*See Wallet Cards
data[].localization[]
Array of Object

 (Optional)
Information for multilingual support
localization[]. language
String (8)

 (Required)
Multilingual content language code.
e.g., en, ko
localization[]. attributes.{fields}

 For displaying a given language, "data[].attributes" can be replaced by localized versions.
*See Wallet Cards

[Example (Option1)]

{ 
"cdata": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" 
}

[Example (Option2)]

{
  "card": {
    "type": "ticket",
    "subType": "movies",
    "data": [{
      "refId": "ref-20230304-0002",
      "createdAt": 1612660039000,
      "language": "en",
      "attributes": {
        "title": "Samsung Wallet"
        /* Refer to Wallet Cards */
      },
      "localization": [{
        "language": "ko",
        "attributes": {
          "title": "삼성월렛"
        }
      }]
    }]
  }
}

[Example (filtered using select parameter)]

GET /cards/12584806754/ref-20230304-0003?select=idPhoto
{ 
    "card": { 
        "type": "ticket", 
        "subType": "entrances", 
        "data": [{ 
            "refId": "ref-20230304-0003", 
            "createdAt": 1612660039000, 
            "language": "en", 
            "attributes": { 
                "idPhoto": "{idPhoto data}" 
            } 
        }] 
    } 
} 
 
OR 

{ 
    "cdata": tokenize{data}
}

[Result]

HTTP Status Code

 Description
200 OK

 Success
204 No Content

 Card doesn’t exist
400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401 Unauthorized

 Authorization token is invalid or expired
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from
fulfilling the request
503 Service Unavailable

 Server is not ready to handle the request

Send Card State

The general information page allows the partner to enter administrative details to manage their cards, as well as to define common parameters for the wallet.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {Partner server URL}/cards/{cardId}/{refId}
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
String (32)

 (Required)
Wallet card identifier.
* Refer to the 'Add to Wallet' Interfaces
refId
String (128)

 (Required)
A unique content identifier defined by the content provider
Query Parameters

 cc2
String (2)

 (Required)
Country code (cc2) for Samsung Server API
event
String (16)

 (Required)
Events on wallet card
e.g., ADDED, UPDATED, DELETED, PROVISIONED
* See Card States for details
Payload

 callback
String(1024)

 (Optional)
Callback URL for Samsung Server API

[Example]

POST /cards/12584806754/ref-20230304-001?cc2=us&event=ADDED 
{ 
"callback": "https://us-tsapi.walletsvc.samsung.com" 
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 N/A
Example

 200 OK

[Result]

HTTP Status Code

 Description
200 OK

 Success
401 Unauthorized

 Authorization token is invalid or expired
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from fulfilling the request
503 Service Unavailable

 Server is not ready to handle the request

Request Action

Handles card-related operations dynamically based on the specified actionType.

The request must include an actionType to specify the intended operation, along with a corresponding actionPayload that contains the relevant data for that action.

The response may include data required for the next step in the process.

This API is designed to handle sequential or conditional workflows, allowing both the server and client to coordinate securely across multiple steps.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {Partner server URL}/cards/{cardId}/{refId}/requestAction
Headers

 Authorization
String (1024)

 (Required)
Authentication token composed of JWT. Headers and payloads may include items that require verification such as timestamp, OTP, certificate info.
The token can have prefix "Bearer" as an authorization type.
e.g., Bearer
* See Authorization Token
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
String (32)

 (Required)
Wallet card identifier.
* Refer to the 'Add to Wallet' Interfaces
refId
String (128)

 (Conditional)
A unique content identifier defined by the content provider
Query Parameter
Payload

 actionType
String(32)

 (Required)
A string that specifies the current action to be performed in the card operation flow. This value determines how the server interprets the 'actionPayload' and responds.
* Refer to Actions
actionPayload
Object

 (Required) An object containing the data required to process the given actionType.
Its structure varies depending on the action being performed
* Refer to  Actions
actionPayload.
signedAtwLink
String

 (Optional)
A base64 encoded secure ATW link containing a timestamp(ts) and an RSA signature(sig). Used for validating the request. This field is only applicable when actionType is CHECK_ELIGIBILITY.
actionPayload.
actionDetails
Object

 (Optional)
Provides metadata about the action.
actionDetails.
timestamp
String

 (Optional)
The time when the action was initiated, represented as a Unix timestamp (e.g., "1748410130000").
actionDetails.
event
String

 (Optional)
The type of event associated with the action.
actionDetails.
reason
String

 (Optional)
The reason for the action.
actionDetails.
level
String

 (Optional)
The severity level of the event. (e.g., INFO, ERROR)
actionDetails.
source
String

 (Optional)
The source of the action.
actionPayload.
{fields}
String/Object

 (Optional)
The key-value pairs of data that the client will transmit, depending on the integration method.

[Example (TRANSFER_CARD)]

{
  "actionType": "TRANSFER_CARD",
  "actionPayload": {
    "receiverName": "leesamsung",
    "phoneNumber": "01012345678",
    "actionDetails": {
      "timestamp": "1748410130000"
    }
  }
}

[Example (RETRIEVE_CARD)]

{
  "actionType": "RETRIEVE_CARD",
  "actionPayload": {
    "actionDetails": {
      "timestamp": "1748410130000"
    },
   "transferReservationNumber": "Trasfer-1234"
  }
}

[Example (GET_REFUND_FEE)]

{
  "actionType": "GET_REFUND_FEE",
  "actionPayload": {
    "actionDetails": {
      "timestamp": "1748410130000"
    }
  }
}

[Example (REFUND_CARD)]

{
  "actionType": "REFUND_CARD",
  "actionPayload": {
    "fee": "1000",
    "actionDetails": {
      "timestamp": "1748410130000"
    }
  }
}

[Example (USER_VALIDATION)]

{
    "actionType": "USER_VALIDATION",
    "actionPayload": {
        "actionDetails": {
            "timestamp": "1748411130000",
            "event": "ISSUE_BY_USER",
            "source": "WALLET_APP"
        },
        "domainId": "DS8F7G2GH",
        "certificateNumber": "109375"
    }
}

[Example (REQ_REISSUANCE)]

{
    "actionType": "REQ_REISSUANCE",
    "actionPayload": {
        "actionDetails": {
            "timestamp": "1748410130000",
            "event": "REISSUE_REQUEST",
            "source": "WALLET_APP"
        },
        "refId": "DG76S8DFEWR"
    }
}

[Example (CHECK_REISSUE_STATE)]

{
    "actionType": "CHECK_REISSUE_STATE",
    "actionPayload": {
        "actionDetails": {
            "timestamp": "1748450130000",
            "event": "REISSUE_BY_USER",
            "source": "WALLET_APP"
        },
        "refId": "DG76S8DFEWR"
    }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
204 No Content
Payload

 actionType
String(32)

 (Optional)
A string that specifies the current action to be performed in the card operation flow. This value determines how the server interprets the actionPayload and responds.
* Refer to Actions
actionPayload
Object

 (Optional)
An object containing the data required to process the given actionType.
Its structure varies depending on the acbtion being performed
* Refer to  Actions
actionPayload.
actionDetails
Object

 (Optional)
Provides metadata about the action.
actionDetails.
timestamp
String

 (Optional)
The time when the action was performed, represented as a Unix timestamp (e.g., "1748410130000").
actionDetails.
event
String

 (Optional)
The type of event associated with the action.
actionDetails.
reason
String

 (Optional)
The reason for the action.
actionDetails.
level
String

 (Optional)
The severity level of the event. (e.g., INFO, ERROR)
actionDetails.
source
String

 (Optional)
The source of the action.
actionDetails.
code
String

 (Optional)
A unique code identifying the action result.
actionDetails.
message
String

 (Optional)
A descriptive message explaining the action result.
actionPayload.
{fields}
String/Object

 (Optional)
The key-value pairs of data that the client will transmit, depending on the integration method.

[Example]

(SUCCESS) 
200 OK | 204 No Content 

(Successful case)
{
  "actionType": "ACTION_TYPE",
  "refId": "reference_id",
  "actionPayload": {
    "actionDetails": {
      "timestamp": "1748410130000"
    }
  }
}

(Successful case - TRANSFER_CARD) 
{
    "actionType": "TRANSFER_CARD",
    "refId": "reference_id",
    "actionPayload": {
        "actionDetails": {
            "timestamp": "1748410130000"
        },
        "transferReservationNumber": " Trasfer-1234"
    }
}

(Successful case - GET_REFUND_FEE) 
{
  "actionType": "GET_REFUND_FEE",
  "refId": "reference_id",
  "actionPayload": {
    "fee": "1000",
    "actionDetails": {
      "timestamp": "1748410130000"
    }
  }
}

(Failed case)
{
  "actionType": "ACTION_TYPE",
  "refId": "reference_id",
  "actionPayload": {
    "actionDetails": {
      "timestamp": "1748410130000"
      "errorCode": "CODE",
      "errorMessage": "MESSASGE"
    }
  }
}

[Result]

HTTP Status Code

 Description
200 OK

 Success
204 No Content

 Card doesn’t exist.
Additionally, this indicates the completion of the processing sequence for the action corresponding to the specified actionType
400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401 Unauthorized

 Authorization token is invalid or expired
404 Not Found

 The requested resource could not be found on the server
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from fulfilling the request
503 Service Unavailable

 Server is not ready to handle the request

Samsung Server API

The Samsung Server API allows partners to notify their content changes to Samsung Wallet. Depending on your service requirements, you can choose from Private Domain or Public Domain to send notifications. The domain selection depends on your system's needs and security preferences.

Service Domain

Environment

 Domain
Public domain

 https://tsapi-card.walletsvc.samsung.com
Private domain

 ‘callback’ field from Send Card State API request payload.

Key components

Private Domain (Recommended for IP Registration) - If your service requires registering static IP addresses on your system, we recommend using the Private Domain. When you use the Private Domain, you will receive a callback URL in the Send Card State API response. This URL will direct your system to the correct endpoint to send content updates or changes.

Public Domain (Recommended for No IP Registration) - If your service does not require IP registration or has more flexible network access, you can use the Public Domain. The Public Domain API endpoint allows easier integration without requiring specific IP addresses to be registered. However, it does require a country code (cc2) as a path parameter for each request. This ensures that content is correctly routed based on the user's region or country.

To configure the API integration for different environments (e.g., testing, production), you must first register a new card service with Samsung. This process will assign you a new card ID for use in your API calls.

The card ID is crucial for identifying and tracking the specific card you are interacting with.

To ensure safe and secure communication, servers should configure Token-based Authentication. For information, refer to the Authorization Token.

Update Notification

Allows partners to notify Samsung Wallet when there are changes or updates to the content of a wallet card. This ensures that the card information within Samsung Wallet remains up-to-date and accurate.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {cc2}/wltex/cards/{cardId}/updates
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token
x-smcs-partner-id
String (32)

 (Required)
Partner ID
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cc2
String(2)

 (Conditional)
Country code (cc2) from Send Card State.
* Required if using Public domain
cardId
String (32)

 (Required)
Wallet card identifier granted from Partners Portal.
Payload

 card
Object

 (Required)
Wallet card object
card.type
String (16)

 (Required)
Wallet card type.
* See Wallet Cards
card.data[]
Array of Object

 (Required)
Wallet card data container
data[].refId
String (32)

 (Required)
A unique content identifier defined by the content provider
data[].state
String (16)

 (Required)
Wallet card state.
For example, ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED.
* See Send Card State for details
data[].atwLink
String(4096)

 (Conditional)
This "Add to Samsung Wallet" link is used when additional card registration associated with this wallet card is provided.
* This is a required field, especially when the state is "MIGRATED".
data[].oldRefId
String(128)

 (Conditional)
If a new refId is provided, it specifies the value of the associated previous refId.
* This is a required field, especially when the state is "MIGRATED".
data[].fields
String (128)

 (Optional)
Wallet Cards attributes which has been updated. Can be specified using commas(,) as separators.
It is used when 'data[].state' is UPDATED.
e.g. balance,barcode.value
* Supported Wallet Card types: generic

[Example]

POST /wltex/cards/12584806754/notification
[Headers]
Authorization: {JWT Auth token}
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003 [Payload]
[Case 1: In general cases]
{
    "card": {
        "type": "ticket",
        "data": [
            {
                "refId": "ref-ticket-0001",
                "state": "UPDATED"
            }
        ]
    }
}

[Case 2: In case of deletion]
{
    "card": {
        "type": "boardingpass",
        "data": [
            {
                "refId": "ref-boardingpass-0001",
                "state": "DELETED"            
            }
        ]
    }
}

[Case 3: When a specific field is updated]
{
    "card": {
        "type": "idcard",
        "data": [
            {
                "refId": "ref-idcard-0001",
                "state": "UPDATED",
                "fields": "balance"
            }
        ]
    }
}

[Case 4: The card is migrated]
{
    "card": {
        "type": "idcard",
        "data": [
            {
                "refId": "BJD8W6REDA",
                "state": "MIGRATED",
                "oldRefId": "DG76S8DFEWR",
                "atwLink": "{ATW Link with the (new)refId}"
            }
        ]
    }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
204 No Content
Payload

 N/A
Example

 200 OK

[Result]

HTTP Status Code

 Description
200 OK

 Success
204 No Content

 Card doesn’t exist
400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401 Unauthorized

 Authorization token is invalid or expired
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from fulfilling the request
503 Service Unavailable

 Server is not ready to handle the request

Batch Update Notification

Updating multiple contents by sending batch update to Samsung server.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {cc2}/wltex/cards/{cardId}/batch/updates
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type,
e.g., Bearer <credentials>.
* See Authorization Token
x-smcs-partner-id
String (32)

 (Required)
Partner ID
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
String(2)

 (Required)
Wallet card identifier granted from Partner Portal
Payload

 Card
Object

 (Required)
Wallet card object
card.type
String(16)

 (Required)
Wallet Card type.
*See Wallet Cards
card.data[]
Array of Object

 (Required)
Wallet card data container.
data[].eventId
String(32)

 (Required)
A unique event identifier defined by the content provider.
data[].state
String(16)

 (Optional)
Wallet card state
e.g., ACTIVE, UPDATED, EXPIRED, REDEEMED, HELD, DELETED, SUSPENDED.
* See Card States for details

[Example]

POST /wltex/cards/12584806754/batch/notification
[Headers]
Authorization: {JWT Auth token}
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
[Payload]
(Case 1: In general cases)
{
    "card": {
        "type": "ticket",
        "data": [
            {
                "eventId": "event-0001",
                "state": "UPDATED"
            }
        ]
    }
}

(Case 2: In case of deletion)
{
    "card": {
        "type": "boardingpass",
        "data": [
            {
                " eventId ": " event-0001",
                "state": "DELETED"            
            }
        ]
    }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
204 No Content
Payload

 N/A
Example

 200 OK

[Result]

HTTP Status Code

 Description
200 OK

 Success
204 No Content

 Card doesn’t exist
400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401 Unauthorized

 Authorization token is invalid or expired
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from fulfilling the request
503 Service Unavailable

 Server is not ready to handle the request

Cancel Notification

Allows partners to inform Samsung Wallet when a card (such as for performances, sports, movies, or journeys) needs to be cancelled. When a cancellation occurs, this API enables partners to set the related card(s) to an expired status. This ensures that users no longer have valid access to events or services that have been cancelled, such as a concert, flight, or movie screening.

[Request]

Type

 Value

 Description
Method

 POST
URL

 {cc2}/wltex/cards/{cardId}/cancels
Headers

 Authorization
String (1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type, e.g., Bearer <credentials>.
*See Authorization Token
x-smcs-partner-id
String (32)

 (Required)
Partner ID.
x-request-id
String (32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cc2
String(2)

 (Conditional)
Country code (cc2) from Send Card State.
* Required if using Public domain.
cardId
String (32)

 (Required)
Wallet card identifier granted from the Partners Portal.
Payload

 card
Object

 (Required)
Wallet card object
card.type
String (16)

 (Required)
Wallet card type.
* See Wallet Cards
card.data[]
Array of Object

 (Required)
Wallet card data container
data[].eventId
String (32)

 (Conditional)
Required if card.type has been set as ‘ticket’.
data[].vehicle Number
String (32)

 (Conditional)
Required if "card.type" has been set as "boardingpass".
data[].estimated OrActualStartDate
Long (13)
data[].state
String (16)

 (Required)
Wallet card state.
e.g., CANCELED
* See Card States for details

[Example]

POST /wltex/cards/12584806754/notification
[Headers]
Authorization: eyJjdHkiOiJUVRlliwidmVyIjoxLCJwYXJ0bmVySWQiOiIxMjg1O...
x-smcs-partner-id: partner-id-0001
x-request-id: req-202303140003
[Payload]
* A movie ticket has been canceled.
{
  "card": {
    "type": "ticket",
    "data": [
      {
        "refId": "event-722164a1a7",
        "state": "CANCELED"
      }
    ]
  }
}

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 N/A
Example

 200 OK

[Result]

HTTP Status Code

 Description
200 OK

 Success
204 No Content

 Card doesn’t exist
400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401 Unauthorized

 Authorization token is invalid or expired
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from fulfilling the request
503 Service Unavailable

 Server is not ready to handle the request

Get Reference Ids

Partners can call this API to get basic information regarding card refIds based on the eventId.

  • This API will require the eventId attribute in each card type. Also, the filter option must be enabled for the eventId attribute in order for this API to work.

[Request]

Type

 Value

 Description
Method

 POST
URL

 wltex/cards/{cardId}?eventId={eventId}&type={type}
Headers

 Authorization
String(1024)

 (Required)
Credential token.
The token can have prefix "Bearer" as an authorization type.
e.g., Bearer
* See Authorization Token.
x-smcs-cc2
String(2)

 (Required)
Country code (cc2).
x-request-id
String(32)

 (Required)
Request identifier.
Randomly generated UUID string.
Path Parameters

 cardId
String(32)

 (Required)
Wallet card identifier granted from Partner Portal
Query Parameter

 eventId
String(32)

 (Required)
Event ID.
Type
String(32)

 (Required)
Type of card (boardingpass, ticket, coupon, etc.)
Payload

 N/A

[Example]

GET /wltex/cards/12584806754?eventId=testing&type=boardingpass
[Headers]
Authorization: {JWT Auth token}
x-request-id: req-202303140004
x-smcs-cc2: US

[Response]

Type

 Value

 Description
HTTP Status

 200 OK
Payload

 count
String

 (Required)
Number of refIds.
refIds
String Array

 (Required)
List of reference ids.

[Example]

    "count": “1”,
    “refIds”: [“12345”]

[Result]

HTTP Status Code

 Description
200 OK

 Success
400 Bad Request

 Requests cannot or will not be processed the request due to something that is perceived to be a client error
401 Unauthorized

 Authorization token is invalid or expired
500 Internal Server Error

 Server encountered an unexpected condition that prevented it from fulfilling the request
503 Service Unavailable

 Server is not ready to handle the request