> ## Documentation Index
> Fetch the complete documentation index at: https://lifters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking Transactions

> Send deposit and withdrawal events to Atlas for financial analytics, risk monitoring, and AML compliance.

<Snippet file="snippets/api-key-auth.mdx" />

## Event Types

Transaction events are sent to `POST /api/v1/transaction`. The Kafka topic is fixed: `atlas.events.raw.transaction`.

| Event      | Description                        |
| ---------- | ---------------------------------- |
| `deposit`  | Player adds funds to their account |
| `withdraw` | Player requests a payout           |

## Track a Deposit

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://events.atlas.io/api/v1/transaction \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "org_abc123",
      "brand_id": "brand_xyz",
      "event": "deposit",
      "user_id": "user_12345",
      "transaction_id": "txn_deposit_9876",
      "transaction_dt": "2026-03-11T14:30:00Z",
      "amount": 200.00,
      "currency": "BRL",
      "payment_method": "PIX",
      "payment_provider": "PICPAY",
      "bonus_credited": false,
      "bonus_code": "",
      "kyc_verified": true,
      "status": "APPROVED",
      "is_first_transaction": true,
      "before_balance": 0.00,
      "after_balance": 200.00
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://events.atlas.io/api/v1/transaction', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ATLAS_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      org_id: 'org_abc123',
      brand_id: 'brand_xyz',
      event: 'deposit',
      user_id: 'user_12345',
      transaction_id: 'txn_deposit_9876',
      transaction_dt: new Date().toISOString(),
      amount: 200.00,
      currency: 'BRL',
      payment_method: 'PIX',
      payment_provider: 'PICPAY',
      bonus_credited: false,
      bonus_code: '',
      kyc_verified: true,
      status: 'APPROVED',
      is_first_transaction: true,
      before_balance: 0.00,
      after_balance: 200.00,
    }),
  });
  ```
</CodeGroup>

## Track a Withdrawal

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://events.atlas.io/api/v1/transaction \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "org_abc123",
      "brand_id": "brand_xyz",
      "event": "withdraw",
      "user_id": "user_12345",
      "transaction_id": "txn_withdraw_5432",
      "transaction_dt": "2026-03-11T18:00:00Z",
      "amount": 500.00,
      "currency": "BRL",
      "payment_method": "TED",
      "payment_provider": "BANK",
      "bonus_credited": false,
      "bonus_code": "",
      "kyc_verified": true,
      "status": "REQUESTED",
      "before_balance": 750.00,
      "after_balance": 250.00
    }'
  ```
</CodeGroup>

## Request Fields

### Envelope Fields (all events)

<ParamField body="org_id" type="string" required>
  Organization identifier.
</ParamField>

<ParamField body="brand_id" type="string" required>
  Brand identifier.
</ParamField>

<ParamField body="event" type="string" required>
  Event type: `deposit` or `withdraw`.
</ParamField>

<ParamField body="ip" type="string">
  Player IP address at transaction time.
</ParamField>

<ParamField body="geolocation_lat" type="number">
  Player latitude at transaction time.
</ParamField>

<ParamField body="geolocation_long" type="number">
  Player longitude at transaction time.
</ParamField>

<ParamField body="is_test" type="boolean">
  Marks the event as operator test traffic. When `true`, the event is accepted
  (202) but rerouted to an audit-only store — it never appears in analytics,
  dashboards or risk scoring. Defaults to `false` when omitted.
</ParamField>

### Transaction Fields

<ParamField body="user_id" type="string" required>
  Your internal user identifier. Must be consistent across all events for the same player.
</ParamField>

<ParamField body="transaction_id" type="string" required>
  Your internal transaction identifier. Must be unique per transaction. Used for deduplication.
</ParamField>

<ParamField body="transaction_dt" type="string" required>
  ISO 8601 timestamp when the transaction happened.
</ParamField>

<ParamField body="amount" type="number" required>
  Transaction amount. Positive for deposits and withdrawals.
</ParamField>

<ParamField body="status" type="string" required>
  Transaction status: `RECEIVED`, `APPROVED`, `REQUESTED`, `PENDING`, `UNDER_REVIEW`, `DENIED`.
</ParamField>

<ParamField body="currency" type="string">
  ISO 4217 currency code (e.g., `BRL`, `USD`, `EUR`).
</ParamField>

<ParamField body="payment_method" type="string">
  Payment method used in the transaction (e.g., `PIX`, `TED`, `CARD`).
</ParamField>

<ParamField body="payment_provider" type="string">
  Payment provider/acquirer used to process the transaction.
</ParamField>

<ParamField body="bonus_credited" type="boolean">
  Indicates whether a bonus was credited together with the transaction.
</ParamField>

<ParamField body="bonus_code" type="string">
  Bonus campaign code applied to the transaction, when applicable.
</ParamField>

<ParamField body="kyc_verified" type="boolean">
  Indicates whether user KYC was verified at transaction time.
</ParamField>

<ParamField body="is_first_transaction" type="boolean">
  Indicates if this is the user's first financial transaction.
</ParamField>

<ParamField body="before_balance" type="number">
  Player balance immediately before the transaction. Used for balance reconciliation.
</ParamField>

<ParamField body="after_balance" type="number">
  Player balance immediately after the transaction. Used for balance reconciliation.
</ParamField>

## AML Considerations

<Warning>
  Transaction events feed directly into Atlas's **PLD (Anti-Money Laundering) engine**.

  For compliance purposes, always include:

  * `transaction_id` — for transaction-level audit trails
  * `before_balance` and `after_balance` — for reconciliation reports
  * `transaction_dt` — actual transaction time, not ingestion time
</Warning>

→ See [PLD Compliance Guide](/guides/compliance/pld) for AML monitoring configuration.

## Batch Transactions

```bash theme={null}
curl -X POST https://events.atlas.io/api/v1/transaction/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "deposit",
        "user_id": "user_001",
        "transaction_id": "txn_001",
        "transaction_dt": "2026-03-11T14:00:00Z",
        "amount": 100.00,
        "status": "APPROVED"
      }
    ]
  }'
```