# Transaction

Payload reference for the TransactionProcessed webhook event Nexus sends when it processes a creator-attributed transaction.

The `Transaction` event type has one action, `TransactionProcessed`.
Nexus sends it when it processes a transaction attributed to a creator in your program.
The payload below is the `event` field of the standard notification envelope (`eventId`, `createdAt`, `eventType`, `eventAction`, `event`) documented in the [webhooks guide](/additional-features/webhooks/).

## Subscribe to transaction events

Only program Admins can manage webhooks.

1. In the Publisher Dashboard, open your program and select **Webhooks**.
2. Select **Add webhook**.
3. Enter your **Endpoint URL**, choose **Transaction** under **Event**, and select **Add webhook**.
4. Copy the **Signing secret** to your server. Use it to [verify each notification](/additional-features/webhooks/#verifying-a-notification).

<ThemedImage light={addWebhookLight} dark={addWebhookDark} width={512} alt="The Add webhook dialog with an endpoint URL entered and the Transaction event selected." />

Each program has one endpoint per event type.
Nexus sends a transaction to the endpoint configured when it processes that transaction, and does not send it later to an endpoint you add afterward.

## TransactionProcessed event

Nexus creates one `TransactionProcessed` event for each transaction it processes, whether you recorded the transaction with the API or it came from a webshop, a storefront, or Xsolla.
Nexus processes only transactions with the `Normal` or `Preorder` status, so a transaction you record with `status` `Test` sends no event.
A pre-order sends its event when you record it, with `transactionStatus` `Preorder`.
A later change to the transaction, such as a refund or fulfilling a pre-order, does not send a second event.

Retries can deliver the same event more than once, with the same `eventId`.
[Handle duplicates](/additional-features/webhooks/#handling-duplicate-events) before you act on an event, so a retry never credits a creator twice.

```json
{
  "attributionGroupId": "Q7mXwP2rLs9dTk4vBn8Zc",
  "attributionGroupName": "Great Game Creator Program",
  "transaction": {
    "id": "T5vRk2NwQ8xLm3Pz7HcYa",
    "code": "juniperjolt",
    "memberId": "J3nPq8wLx2Vr6TzKa9mYd",
    "memberPlayerId": "player_7f3a91c2",
    "memberPlayerMetadata": {
      "displayName": "JuniperJolt"
    },
    "transactionId": "4b8e1f2a-6c3d-4e5f-9a7b-1c2d3e4f5a6b",
    "transactionDate": "2026-06-03T21:03:18.000Z",
    "transactionStatus": "Normal",
    "origin": "API",
    "description": "Gold Pack 5",
    "skuId": "Gold_Pack_5",
    "platform": "Android",
    "playerId": "player_d56a467b7a3c145c",
    "playerName": "",
    "currency": "USD",
    "subtotal": 1999,
    "total": 1999,
    "totalCurrency": "USD",
    "memberSharePercent": 20,
    "memberShareAmount": 2.7986,
    "creatorPaid": false,
    "metrics": {
      "joinDate": "2023-12-05T06:15:23.578Z",
      "conversion": {
        "lastPurchase": {
          "date": "2024-12-06T03:44:57.881Z",
          "platform": "Apple"
        },
        "totalSpendToDate": {
          "total": 15992,
          "currency": "USD"
        }
      }
    }
  }
}
```

### Event fields

| Field | Type | Notes |
| --- | --- | --- |
| `attributionGroupId` | string | The ID of the Creator Group the transaction belongs to. |
| `attributionGroupName` | string | The name of that Creator Group. |
| `transaction` | object | The processed transaction, described below. |

### Transaction fields

These fields are always present.

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | The Nexus ID for this transaction. |
| `memberId` | string | The Nexus ID of the creator credited with the transaction. |
| `transactionId` | string | Your ID for the transaction, as you sent it. |
| `transactionDate` | RFC3339 string | When the purchase happened. |
| `transactionStatus` | enum | `Normal`, or `Preorder` for a purchase you recorded as a pre-order. |
| `origin` | enum | Where the transaction came from: `API`, `WebshopCode`, `StorefrontCode`, or `Xsolla`. |
| `description` | string | The product description. |
| `playerName` | string | The player name you sent, or an empty string. |
| `currency` | enum | The ISO currency code of `subtotal`, such as `USD` or `JPY`. |
| `subtotal` | integer | The purchase subtotal in the smallest unit of `currency` (USD 19.99 → 1999). |
| `creatorPaid` | boolean | Whether Nexus has paid the creator their share. Nexus sends this event when it processes the transaction, before the creator is paid, so this is normally `false`. |

These fields can be absent or `null`.

| Field | Type | Notes |
| --- | --- | --- |
| `code` | string | The creator code used for the purchase. |
| `memberPlayerId` | string | The player ID you linked to this creator's membership in your program. Absent if the creator has not linked their Nexus account. |
| `memberPlayerMetadata` | object | Details stored with that link. Contains `displayName`. |
| `skuId` | string | The SKU ID you sent. |
| `platform` | string | The platform you sent. |
| `playerId` | string | Your ID for the player who made the purchase, or an empty string if you did not send one. |
| `total` | integer | The purchase total in the smallest unit of `totalCurrency`. |
| `totalCurrency` | enum | The ISO currency code of `total`. |
| `memberSharePercent` | number | The creator's revenue share rate for this transaction, as a percentage before fees (`20` means 20%). |
| `memberShareAmount` | number | The creator's share of this transaction in US dollars, after fees and any agency share, whatever the transaction's currency (`2.7986` means $2.7986). |
| `metrics` | object | The player metrics you sent. See [Performance metrics](/creator-code-api/attributions/performance-metrics/). |
| `playerJoinDate` | RFC3339 string | Present only if your request used the legacy top-level `playerJoinDate` field. If your request did not set `metrics.joinDate`, Nexus copies this value there. |
| `playerLastPurchase` | RFC3339 string | Present only if your request used the legacy top-level `playerLastPurchase` field. If your request did not set `metrics.conversion.lastPurchase.date`, Nexus copies this value there. |

<Aside type="note" title="Subtotal and total use the smallest currency unit">
`subtotal` and `total` are in the smallest unit of their currency, even if you sent decimal amounts with the [floating decimal](/creator-code-api/attributions/making-your-first-requests/#floating-decimal) option.
For zero-decimal currencies such as JPY, they are whole units.
`memberShareAmount` is the exception: it is in US dollars.
See [Currency and totals](/creator-code-api/attributions/making-your-first-requests/#currency-and-totals).
</Aside>

<LinkCard title="Webhooks guide" description="The notification envelope, signature verification, and duplicate handling." href="/additional-features/webhooks/" />
<LinkCard title="Event types" description="All webhook event types Nexus sends." href="/additional-features/webhooks/event-types/" />
