Skip to main content

Event integration

Available

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 funnelFire RegisterEvent?
Referral link openedNo
Application submittedNo
KYC passed, account activatedYes
Application rejected or abandonedNo

The payload​

The referral event is carried in BDATA before encoding:

BDATA payload before encoding
{
"virtualId": "pub_8f14e45fceea167a",
"channelName": "YOURCHANNEL",
"eventType": "Referral",
"subEventType": "REPLACE_REFERRAL_CODE",
"additionalParams": "{\"isNewUser\":true}"
}
FieldTypeDescription
virtualIdstringThe referee — the customer whose account was just activated
channelNamestringYour channel, matching CHANNELID on the envelope
eventTypestring"Referral" for this module
subEventTypestringThe referral code the referee signed up with
additionalParamsstringA JSON string, not an object. {"isNewUser":true} for a first-time customer
additionalParams is a string containing JSON

It 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.

The referrer is resolved from the code

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.

Sign on your server, never on a device

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​

POST /api/RegisterEvent
{
"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))")
}
Prefer the server-to-server call for conversions

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.

Next​