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_code for rejections.
  • Our endpoint is idempotent on {{ExternalId}}: a repeated ExternalId never 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