Event integration
This is the one piece of the referral module you have to build server-side, and the one that decides
whether a referral pays out. When the referee's account is activated, your backend calls
RegisterEvent with a referral event. Cheggout
attributes it, checks eligibility, and assigns the reward to both sides.
POST https://bankapi.cheggout.com/api/RegisterEvent (Production)
POST https://bankapi-uat.cheggout.com/api/RegisterEvent (UAT)
Authentication — signed envelope
When to fire it
Fire on activation, not on application. A submitted application is not a converted referral — if you fire early and the application later fails KYC, you have paid for an acquisition that never happened.
| Event in your funnel | Fire RegisterEvent? |
|---|---|
| Referral link opened | No |
| Application submitted | No |
| KYC passed, account activated | Yes |
| Application rejected or abandoned | No |
The payload
The referral event is carried in BDATA before encoding:
{
"virtualId": "pub_8f14e45fceea167a",
"channelName": "YOURCHANNEL",
"eventType": "Referral",
"subEventType": "REPLACE_REFERRAL_CODE",
"additionalParams": "{\"isNewUser\":true}"
}
| Field | Type | Description |
|---|---|---|
virtualId | string | The referee — the customer whose account was just activated |
channelName | string | Your channel, matching CHANNELID on the envelope |
eventType | string | "Referral" for this module |
subEventType | string | The referral code the referee signed up with |
additionalParams | string | A JSON string, not an object. {"isNewUser":true} for a first-time customer |
additionalParams is a string containing JSONIt is escaped JSON inside the payload, not a nested object. Serialising it as an object is the most
common integration mistake on this endpoint. Note the \" escaping in the example above.
You send the referee and the code. Cheggout resolves the referrer from the code — you never send both sides.
Building the request, step by step
The signed envelope is specified in full on Signed envelope. Worked through with the referral payload, it is three steps.
Step 1 — Base64-encode the payload to create BDATA
Serialise the JSON above, encode it as UTF-8 bytes, then Base64-encode those bytes.
{"virtualId":"...","channelName":"YOURCHANNEL","eventType":"Referral", ... }
│
▼ UTF-8 bytes
01111011 00100010 01110110 01101001 ...
│
▼ Base64
eyJ2aXJ0dWFsSWQiOiJwdWJfOGYxNGU0NWZjZWVhMTY3YSIsImV2ZW50VHlwZSI6IlJlZmVycmFsIn0=
At this point you have:
{
"CHANNELID": "YOURCHANNEL",
"BDATA": "eyJ2aXJ0dWFsSWQiOiJwdWJfOGYxNGU0NWZjZWVhMTY3YSIsImV2ZW50VHlwZSI6IlJlZmVycmFsIn0="
}
Step 2 — Sign BDATA with SHA256withRSA
Hash the Base64 string — not the original JSON — with SHA-256, sign the hash with your private key, and Base64-encode the signature.
BDATA (Base64 string)
│
▼ SHA-256
hash
│
▼ RSA sign, your private key
signature
│
▼ Base64
SIGN
SIGN = base64( RSA_sign( SHA256(BDATA), yourPrivateKey ) )
The private key never leaves your infrastructure. You share only the public certificate with Cheggout — see Key generation.
A referral event is a payout instruction. If the signing key is embedded in a mobile app, anyone who extracts it can mint referral conversions against your campaign budget. Keep signing behind your backend.
Step 3 — Send it
{
"CHANNELID": "YOURCHANNEL",
"SIGN": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8...",
"BDATA": "eyJ2aXJ0dWFsSWQiOiJwdWJfOGYxNGU0NWZjZWVhMTY3YSIsImV2ZW50VHlwZSI6IlJlZmVycmFsIn0="
}
What Cheggout does with it
If the signature does not verify, the request is rejected before the payload is even decoded. A
verification failure is almost always one of: signing the decoded JSON instead of the BDATA
string, a certificate mismatch between environments, or whitespace differences from re-serialising
the JSON after encoding.
Reliability
Because nothing surfaces to either customer when this call is missed, treat it as a payment-grade integration:
- Make it idempotent. Retrying an activation must not double-pay. Confirm with Cheggout how duplicates are handled for your channel, and de-duplicate on your side by activation reference.
- Queue and retry. Fire from a durable queue with backoff, not inline in the activation transaction. An outage should delay a reward, not lose it.
- Alert on the gap. Reconcile activations-with-a-referral-code against events successfully sent. A widening gap is the only early warning you will get.
TBD The published material does not specify the endpoint's idempotency behaviour or its full response codes. Confirm both during onboarding, and see Error codes for the platform conventions.
SDK methods
Both mobile SDKs expose a client-side equivalent.
Android
CHEGNetworkCallHelper.registerEvent(
virtualId,
"Referral",
referralCode,
"{\"isNewUser\":true}",
object : CHEGregisterCampaignEventCallBack {
override fun onResponse(responseString: String?) { }
}
)
iOS
CheggoutApp.registerEvent(
VirtualId: virtualId,
EventType: "Referral",
SubEventType: referralCode,
additionalParams: "{\"isNewUser\":true}"
) { response in
print("registerEvent: \(String(describing: response))")
}
The device does not know whether an account was really activated, and it may be offline or closed at the moment activation completes. Use the SDK methods for in-session signals; use the signed server-to-server call for the conversion that pays out.