Skip to main content

iOS SDK methods

The CheggoutApp instance exposes data methods so you can render Cheggout content inside your own SwiftUI or UIKit screens rather than handing over the whole display. They return data through trailing closures; none of them draw anything.

These are network calls

Each method makes an HTTP request. Results arrive on a background queue unless stated otherwise — hop to the main queue before touching UI. There is no separate error channel on these closures, so treat a nil or empty result as failure.

Method summary​

MethodReturnsTypical trigger
getCheggoutTopBannersBanner creatives for a placementHome screen appears
getCheggoutTopStoresTop stores with logos and discountsEvery app launch
getCashbackPointsThe user's points balance and a deep linkRendering a coin badge
sendRewardCardRequestA scratch card deep link and bannerAfter a transaction completes
impressionNothing — fires a tracking beaconBanner or store displayed
registerEventNot available—

getCheggoutTopBanners​

Fetches banner creatives for a placement so you can render your own carousel.

CheggoutApp.getCheggoutTopBanners(
    languageCode: "EN",
    virtualId: "pub_8f14e45fceea167a",
    placementId: "01",
    additonalParams: "",
    securityKey: ""
) { topBanners in
    DispatchQueue.main.async {
        self.render(topBanners)
    }
}

Parameters​

ParameterTypeRequiredDescription
languageCodeStringYes2-character ISO language code, for example "EN".
virtualIdStringYes, except pre-loginThe user's virtual ID. Mandatory except on a PreLogin placement.
placementIdStringYesDefines the banner position within Cheggout, for example "01". Configured by Cheggout for your channel.
additonalParamsStringNoA JSON string of extra targeting parameters.
securityKeyStringNoPass an empty string.
completionclosureYesReceives the banner payload.
The parameter is spelled additonalParams

The label is misspelled in the SDK. Swift argument labels are part of the signature, so you must use the SDK's spelling.

Response shape​

{
  "banners": {
    "01": [
      {
        "bannerLink": "https://assets.example.com/creatives/REPLACE.jpg",
        "trackLink": "<tracking string>",
        "trackLinkExt": "<tracking string>",
        "href": "<tracking and deep-link string>",
        "bankBanner": false,
        "duration": 10,
        "bankLink": "",
        "clickLink": "<tracking string>",
        "brandDescription": "REPLACE"
      }
    ]
  }
}
FieldTypeMeaning
bannerLinkstringURL of the creative image to display. Documented with a maximum length of 500 characters.
hrefstringDeep-linking and impression tracking information. Documented with a maximum length of 1000 characters. Pass it to impression on display, and into the launch payload's DeeplinkInfo on click.
bankLinkstringDocumented values are 0 and 1. bankLink = 1 means the banner is the Bank's own and the app must not call the SDK. TBD Samples also show an empty string; what an empty value means is not documented.
bankBannerbooleanPresent in the response. TBD No semantics are documented, and its relationship to bankLink is not documented either — do not infer one from the other.
durationintegerAuto-scroll duration in seconds for a rotating carousel.
brandDescriptionstringShort brand copy to show with the creative.

The contract is three steps: fetch on home screen visit → fire the impression when the creative is displayed → launch the SDK with href in DeeplinkInfo on click.

getCheggoutTopStores​

Fetches the top stores for a placement — logos, names and current discount.

CheggoutApp.getCheggoutTopStores(
    languageCode: "EN",
    virtualId: "pub_8f14e45fceea167a",
    placementId: "00",
    additionalParams: "",
    securityKey: ""
)

Parameters​

ParameterTypeRequiredDescription
languageCodeStringYes2-character ISO code.
virtualIdStringYes, except pre-loginThe user's virtual ID.
placementIdStringYesThe store placement, for example "00".
additionalParamsStringNoJSON string of extra parameters.
securityKeyStringNoPass an empty string.

Note the label here is additionalParams — spelled correctly, unlike the banner method. The two are not interchangeable.

Response shape​

[
  {
    "storeId": "REPLACE",
    "title": "Example Retailer",
    "href": "<tracking and deep-link string>",
    "logo": "https://assets.example.com/logos/REPLACE.png",
    "discountPercentage": "5",
    "category": "Fashion"
  }
]

Call this on each launch, and display each store with its name and discount details — the discount is what earns the tap. On tap, open the SDK with that store's href in DeeplinkInfo.

getCashbackPoints​

Returns the user's Cheggout points balance for display in your own UI.

CheggoutApp.getCashbackPoints(
    virtualId: "pub_8f14e45fceea167a",
    sessionId: "SessionID"
) { cashBackPoints in
    DispatchQueue.main.async {
        self.coinBadge.text = cashBackPoints.cashbackPoints
    }
}

Parameters​

ParameterTypeRequiredDescription
virtualIdStringYesThe user's virtual ID.
sessionIdStringYesThe active session ID for this user.
completionclosureYesReceives the points payload.

Response​

{ "cashbackPoints": "100", "deepLink": "deeplinkString" }

cashbackPoints is a string, not a number. Parse defensively.

You may not need the call at all

For a simple tappable coin icon, skip the API: place the icon in your app and open the deep link Cheggout provides. The SDK opens on the Cheggout page with the points already shown. Use getCashbackPoints only when you want to render the number yourself.

sendRewardCardRequest​

Requests a scratch card for a completed transaction. This is the iOS counterpart of Android's getScratchCardDetails, and it is the client-side issuance path; the server-to-server equivalent is GetScratchCardForBank.

CheggoutApp.sendRewardCardRequest(
    triggerEventType: "UPI",
    subTriggerEventType: "",
    merchantVPA: "",
    amount: 499.00,
    extTransactionId: "PUB_TXN_20260731_000117",
    dateandtime: "31072026141530",
    virtualId: "pub_8f14e45fceea167a",
    sessionId: " ",
    additionalParams: ""
) { scratchCard in
    DispatchQueue.main.async {
        self.present(scratchCard)
    }
}

Parameters​

ParameterTypeRequiredDescription
triggerEventTypeStringYesPredefined campaign or trigger code, for example UPI, WITHINBANK, IMPS, RTGS.
subTriggerEventTypeStringNoOptional secondary trigger classification.
merchantVPAStringNoRequired only for UPI transactions.
amountDoubleYesTransaction amount to 2 decimal places, in rupees.
extTransactionIdStringYesUnique alphanumeric transaction identifier, maximum 256 characters. The idempotency key.
dateandtimeStringYesTransaction timestamp in the format DDMMYYYYHHMMSS.
virtualIdStringYesThe user's virtual ID.
sessionIdStringYesPass the literal " " — a single space — as documented. See the caution below.
additionalParamsStringNoJSON string with optional country, state, district, city, pincode, storeId, ipaddress, lat, long, gender, age, modeType, isNewUser. Used for targeting.
completionclosureYesReceives the scratch card payload.
sessionId is not a real session here

Unlike getCashbackPoints, this method does not take the user's session. The source material calls for "an empty string" and then writes it as " " — which is a single space, not an empty string. Pass the literal " " exactly as shown in the example above, because that is what is documented.

TBD Whether a truly empty string "" is also accepted is not documented. Confirm with Cheggout before changing it.

Response​

{
  "message": "Success",
  "banner": "https://assets.example.com/creatives/REPLACE.jpg",
  "status": true,
  "deepLink": "https://click.cheggout.com?type=reward&scratchCardId=1",
  "isPopup": true,
  "popupBanner": "https://assets.example.com/creatives/REPLACE.jpg",
  "popupDeepLink": "https://click.cheggout.com?type=reward&scratchCardId=5"
}
FieldMeaning
statustrue when a card was issued. false is a normal "not eligible" outcome, not an error.
bannerImage to display inline, for example on a payment success screen.
deepLinkPass into the launch payload's DeeplinkInfo to open the card inside the SDK.
isPopupWhether an interstitial should be presented.
popupBanner, popupDeepLinkCreative and destination for that interstitial.
Prefer server-side issuance

A client-initiated issuance path allows requests that are not tied to a verified transaction. Where your backend can make the signed call instead, bind virtualId and extTransactionId to a verified order server-side. See Security best practices.

impression​

Fires the impression beacon for a banner or store you have displayed. It returns nothing.

CheggoutApp.impression(userID: virtualId, impressionInfo: href)

Parameters​

ParameterTypeRequiredDescription
userIDStringYesThe user's virtual ID.
impressionInfoStringYesThe href field exactly as received from the banner or store response. Do not modify or truncate it.

Call it when the creative becomes visible, not when the response arrives. In a paging carousel that means once per creative as it scrolls into view:

func carousel(_ carousel: Carousel, didDisplay banner: Banner) {
    CheggoutApp.impression(userID: virtualId, impressionInfo: banner.href)
}

The href is a pseudo-XML tracking string carrying tags such as <click>, <track>, <clicktrack>, <browser>, <expiryduration>, <id> and <redirectURL>. The SDK parses it for you; headless integrators parse the tag they need and fire the URL with a plain GET.

registerEvent​

Not available

This method is not currently usable. It is listed here only so you recognise it if you find it in older integration material or in the framework's symbol list.

The historical specification, for reference only:

CheggoutApp.registerEvent(
    VirtualId: virtualId,
    EventType: "register",       // or "referral"
    SubEventType: "",            // for referral, the referral code
    additionalParams: "{\"isNewUser\":true}"
) { result in
    // ...
}
No server implementation

Verification against the platform found no server implementation for the RegisterEvent endpoint this method calls. Do not design a registration or referral flow around it. Confirm availability with Cheggout before committing to any work that depends on it. Tracked in Open items.

The same caveat applies to ExitEvent. See Register and Exit events.

Next​