# 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](index.html) (Sections 1–6) that explains it.

Download a fillable copy: [backend-information-request.md](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](index.html#11-the-player-id) and [Section 2](index.html#2-authentication)*

**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](index.html#3-event-ingestion)*

**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](client-pack/EVENT_METADATA_FILE.md)), **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](index.html#4-reward-payouts-withdrawals)*

**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:

```json
{
  "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
