Install the Vivoldi app from Google Play to make it even more convenient.

Stamp Validation API (v2)

The Stamp Validation API checks whether a stamp is in a valid state before adding or removing stamps, or processing reward redemption.

It verifies the stamp IDX, validity period, activation status, and whether the reward has already been redeemed in a single request.

In addition to validation, it returns the current accumulation status and card details, allowing you to build a user-facing stamp view.

This API is available on the Personal plan or higher.

GET

/api/stamp/v2/validate?stampIdx={stampIdx} 


GET /api/stamp/v2/validate
     ?stampIdx=274
     &processStoreIdx=22

Request Parameters

stampIdx integer required
Stamp IDX.
processStoreIdx integer
IDX of the store where this request is actually processed. When sent, the server verifies organization ownership, active status and permissions before recording it in the processing history.
The processing branch is not taken from the request; the server derives it from this store. This is different from the issuing store (storeIdx). 
{
    "code": 0,
    "message": "",
    "result": {
        "stampIdx": 16,
        "domain": "https://vvd.bz",
        "cardIdx": 1,
        "cardNm": "Accumulate 10 Americanos",
        "cardTtl": "Collect 10 stamps to get one free Americano.",
        "stamps": 10,
        "maxStamps": 12,
        "stampUrl": "https://vvd.bz/stamp/274",
        "url": "https://myshopping.com",
        "strtYmd": "2025-01-01",
        "endYmd": "2026-12-31",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": null,
        "activeYn": "Y",
        "userId": "NKkDu9X4p4mQ",
        "userNm": null,
        "userPhnno": null,
        "userEml": null,
        "userEtc1": null,
        "userEtc2": null,
        "stampImgUrl": "https://cdn.vivoldi.com/www/image/icon/stamp/icon.stamp.1.webp",
        "regYmdt": "2025-10-30 05:11:35",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

Response Parameters

codeinteger
Response code: 0 = Success, any other value = Error
messagestring
Response message. If the response code is not 0, an error-related message is returned.
resultobject
If the verification succeeds, the response will include the stamp information.
If the verification fails, the response value will be null, and the error message will indicate the cause.
stampIdx integer
Stamp IDX.
domain string
Stamp domain.
cardIdx integer
Card IDX.
cardNm string
Card name.
cardTtl string
Card title.
stamps integer
Number of collected stamps so far.
maxStamps integer
Maximum number of stamps for the card.
stampUrl string
URL of the stamp page.
url string
The URL to which the user is redirected when clicking the button on the stamp page.
strtYmd date
Stamp validity start date.
endYmd date
Stamp expiration date.
onsiteYn string
Enum:
YN
Indicates whether on-site accumulation is enabled. If the value is Y, store staff can add stamps at the location.
onsiteToken string
Short-lived exchange token for on-site processing.
It replaces the onsitePwd plaintext that v1 returned. It does not add an authentication factor; it keeps the long-lived password out of responses and integration logs.
It expires after 180 seconds, can be used once, and cannot be reused for another organization, resource, action or processing store. Not issued when the resource does not use on-site authentication (onsiteYn = N).
onsiteTokenExpiresIn integer
Token lifetime in seconds. Absent when no token is issued.
memo string
Internal memo for reference.
activeYn string
Enum:
YN
Indicates whether the stamp is active. If deactivated, customers cannot use the stamp.
userId string
User ID. Used to manage the recipient of the stamp.
Typically, this corresponds to the website member’s login ID.
If not set, the system automatically generates a user ID.
userNm string
User name. For internal management.
userPhnno string
User phone number. For internal management.
userEml string
User email address. For internal management.
userEtc1 string
Additional internal management field.
userEtc2 string
Additional internal management field.
stampImgUrl string
URL of the stamp image.
regYmdt datetime
Stamp creation date. Example: 2025-07-21 11:50:20
branchIdx integer
Issuing branch IDX. null for head-office issuance. This is the issuing location, not the branch where this request was processed.
branchNm string
Issuing branch name. null for head-office issuance. The name is returned even if the branch is deactivated.
storeIdx integer
Issuing store IDX. null when not specified. Different from the processing store.
storeNm string
Issuing store name. null when no issuing store is specified. The name is returned even if the store is deactivated.
issueScope string
Issuance type. Either HEAD_OFFICE (issued by head office) or BRANCH (issued by a branch). HEAD_OFFICE when branchIdx is null.
useScope string
Usable scope. Either ALL (all stores) or BRANCH (specific branch).
useBranchIdx integer
Usable branch IDX. Present only when useScope = BRANCH; null when ALL.
useBranchNm string
Usable branch name. Present only when useScope = BRANCH; null when ALL. The name is returned even if the branch is deactivated.

On-site verification token (onsiteToken)

The v2 Validate API response does not include the on-site password in plaintext (onsitePwd). Instead, it returns an onsiteToken that is valid for 180 seconds.

The goal is to minimize plaintext password exposure, not to strengthen authentication. The Validate API does not verify the password itself, so the token does not add another authentication factor. Instead, its short lifetime, single-use behavior, and context binding limit how the token can be reused.

Item Value
Lifetime 180 seconds. The validity period is also returned in onsiteTokenExpiresIn.
Uses One. After the token is consumed, only retries with the same Idempotency-Key return the original result.
Binding Organization, API key account, resource, action, and the processing store confirmed during validation
Applies to Coupon redemption, stamp reward redemption, and stamp updates with useYn = Y

No token is issued for resources that do not use on-site verification (onsiteYn = N). The v1 Validate API continues to return onsitePwd in plaintext.

Numeric parameter validation

If a numeric parameter receives a non-numeric value, or a number beyond the range the server can handle, the request is rejected immediately with 400 (error code 653).

In that case no stamp data or earning history changes at all, and no event record or Webhook delivery is produced. A failed response means nothing was saved.

Specifying the processing store

Parameter Meaning Description
processStoreIdx Processing store The store where this request is actually processed. Optional. When sent, the server verifies organization ownership, active status and permissions before recording it in the processing history.

The processing branch is not accepted from the request. The server derives and records it from the store you specify.

When the usable scope is BRANCH, the request is processed only if the branch of the verified processing store matches the usable branch, or if you authenticate with that branch's on-site password. Without either, it is rejected.

Parameters that cannot be used — branchIdx (issuing branch), storeIdx (issuing store), useScope (usable scope) and useBranchIdx (usable branch) are already-stored issuance policy and cannot be changed through this API. Sending them returns 400 (error code 1227).

What Is the Role of Stamp Validation?

The Stamp Validation API goes beyond a simple validity check.
It determines the next action based on the current accumulation state.

  • Check if additional stamps can be issued
  • Verify whether reward conditions are met
  • Confirm campaign participation status
  • Retrieve per-user progress

In short, the Stamp Validation API is the core endpoint for reading campaign progress.

What You Can Determine from the Validation Result

The response (result) contains all data required to evaluate stamp progress.

With this data, you can:

  • Compare current count (stamps) with maximum (maxStamps)
  • Determine whether further accumulation is allowed
  • Check if reward conditions are satisfied
  • Verify stamp status (activeYn)
  • Evaluate availability context (onsiteYn)
  • Apply personalization based on user data

Key point: “Validation API = State retrieval + Input for decision logic”

How to Use the Response Data

The validation API response is used directly within application logic.

Examples:

  • Render progress UI: Display real-time progress on the frontend
  • Control actions: Enable or disable accumulation buttons based on state
  • Trigger rewards: Show rewards when milestones are reached
  • Handle user states: Branch logic per user progress and campaign status

In short, this API is the core data source that connects UI and business logic.

Difference from Coupon Validation API

Both APIs return validation results with detailed data, but the nature of the data differs.

Coupon validation returns transaction-focused data such as discount type, discount value, and usage limits.
Stamp validation returns progression data such as current stamps (stamps), maximum stamps (maxStamps), card name, title, and stamp image URL.

The Coupon Validation API is used to calculate “how much discount applies now”,
while the Stamp Validation API is used to show “how much has been collected and how much remains”.

Operational Importance

The Stamp Validation API is at the core of the event flow.

  • Prevents incorrect stamp accumulation
  • Blocks actions when conditions are not met
  • Improves user experience
  • Ensures stability of event logic

Skipping validation can lead to data inconsistencies and event errors.

Things to consider

  • State may change between validation and actual accumulation
  • Call the accumulation API immediately after validation to minimize risk
  • Avoid relying solely on client-side validation for business logic
  • In high-traffic environments, optimize API calls and implement retry strategies on failure