OnAim Integration — Information Request
Please fill in this document and send it back to your OnAim contact in one reply. Each section points to the part of the Integration Guide (Sections 1–6) that explains it.
Download a fillable copy: backend-information-request.md.
Never send private keys. Send passwords and secrets through the secure channel agreed with your OnAim contact (e.g. a one-time secret link), not in plain email.
1. Player identification
Guide: 1.1 The player id and Section 2
1.1 Player id. Which id identifies a player? It must be the same in tokens, events and payouts.
| Question | Answer |
|---|---|
| Name of the id in your system | |
| Example value | |
| Can it ever change or be reused? (must be "no") |
1.2 Authentication method — tick one:
- A. Signed JWT (default) → fill in 1.3
- B. One-time token + player endpoint → fill in 1.4
- C. Token pass-through → fill in 1.4 (skip the credentials row)
1.3 Signed JWT
| Item | Value |
|---|---|
RSA public key (PEM, attach as .pem) |
|
Token lifetime (exp), max 5 min |
|
| Example decoded token payload |
1.4 Player endpoint (methods B and C)
| Item | Value |
|---|---|
URL template with {token}, e.g. https://api.example.com/onaim/player/{token} |
|
| Auth (method B only): Basic username / password or "HMAC" | |
Response field holding the player id (→ Id) |
|
Response field holding the display name (→ UserName) |
|
| Example successful response (JSON) | |
| Token lifetime |
2. Events
Guide: Section 3
2.1 Delivery method — tick one:
- REST API (default) — OnAim will send you the endpoint URL and signing secret.
- Kafka — fill in 2.2.
2.2 Kafka (only if chosen)
| Item | Value |
|---|---|
| Bootstrap servers | |
| Authentication: SASL_SSL SCRAM-SHA-256 or mTLS | |
| Username / password or client cert + key (secure channel) | |
CA certificate (attach .crt) |
|
| Message format: JSON or Avro + Schema Registry URL | |
Player id field name: customerId or customer_id |
Topics:
| Topic | Event type it carries |
|---|---|
Deposit |
|
We will send you our egress IP(s) and consumer-group prefix for your firewall and ACLs.
2.3 Event list. Every event type you will send. Deposit is required.
eventType value (exact, case-sensitive) |
When it is sent | Approx. volume per day |
|---|---|---|
Deposit |
When a deposit is credited | |
2.4 Event time. Which field on your events holds the time the action happened (e.g. create_time)? It must be the same field on every event type and in ISO 8601 with Z or an offset.
| Question | Answer |
|---|---|
| Event time field name | |
| Example value |
2.5 Event catalog. Attach one of:
- the event metadata file (JSON, format in Event Metadata File), or
- a spreadsheet with, per event type: field name, type, description, whether it is a summable amount, and the full list of possible values for enumerable fields.
In both cases also attach one real example payload per event type (anonymised player id is fine).
2.6 Money
| Question | Answer |
|---|---|
| Currencies your events can contain (ISO codes) | |
| For each monetary event: which field is the amount, which is the currency | |
Are amounts in major units (12.50)? If not, what unit? |
|
Can amounts be negative (e.g. bets sent as -5)? |
2.7 Games (only if you send game activity and want game-based promotions)
- Game list attached (CSV/XLSX), columns at least:
game_code,provider,game_name,game_type(slot, live, table, crash, sport, …). - Which event fields carry the game code and provider? ________________
3. Reward payouts
Guide: Section 4
3.1 Reward types. Which kinds of rewards can OnAim give players?
| Reward kind | Yes / No | Notes (e.g. wagering, max value) |
|---|---|---|
| Cash (real money) | ||
| Bonus money | ||
| Free spins | ||
| Free bets | ||
| Other: ________ |
3.2 Payout endpoint — copy this table once per endpoint.
| Item | Value |
|---|---|
| Reward kind(s) handled by this endpoint | |
| URL | |
Method (POST / PUT / PATCH / GET / DELETE) |
|
| Authentication: Basic (user / pass) / HMAC / static header (name + value) | |
Request body or query template, using {{placeholders}} (example below) |
|
Fields that differ per reward option (e.g. bonus_template_id) and their values |
|
| Example success response | |
| Example rejection response (unknown player, invalid bonus) |
Template example:
{
"request_id": "{{ExternalId}}",
"user_id": "{{PlayerId}}",
"bonus_template_id": "<per reward option>",
"amount": "{{Value}}",
"count": "{{Quantity}}"
}
3.3 Reward options / packages. The concrete rewards OnAim may offer, with your ids:
| Reward option (what the player sees) | Endpoint | Your id(s) for it (bonus template, free-spin package, …) | Value / quantity |
|---|---|---|---|
| e.g. 20 free spins, Book of Dead | free-spins | FS-20-BOD |
20 spins × €0.20 |
3.4 Confirmations — please confirm each:
- Our endpoint returns HTTP 200 only when the reward is credited; 4xx or non-zero
error_codefor rejections. - Our endpoint is idempotent on
{{ExternalId}}: a repeatedExternalIdnever credits twice. - Our endpoint accepts all body values as strings.
- Our endpoint responds within 30 seconds.
- OnAim can send test payouts to our endpoint. Test player id(s): ________________
4. Network
| Item | Answer |
|---|---|
| Do your endpoints (player endpoint, payout) require IP allow-listing? If yes, we will send our egress IPs. | |
| Hostnames of your APIs |
What OnAim sends you after receiving this
The details you need to start building:
- Event API base URL and event signing secret (REST), or egress IPs + consumer-group prefix (Kafka)
- HMAC secret for calls to your endpoints (if you chose HMAC)
- Promotion page base URL and test promotion ids
- OnAim egress IP addresses
- Access to the Admin Panel for your promotion team