Purchase Fulfillment

Oncade supports three fulfillment types for purchases. Choose the one that matches your game's delivery model.

  • NONE: No automatic fulfillment. Use this for purely manual delivery or when your game server looks up purchases via the API and applies its own logic.
  • EMAIL_KEY: Oncade emails a unique key to the player. Upload your key pool in the item editor (CSV/TXT, one key per line).
  • GRANT_VIRTUAL_CURRENCY: When payment completes, Oncade automatically credits a configured virtual currency balance for the purchaser using the currency and amount you select on the item.

Email Key Fulfillment

For items using EMAIL_KEY fulfillment, Oncade pulls a single-use key from your uploaded pool and emails it directly to the player after payment completes. Each key is consumed when the email is sent, ensuring no duplicates are issued.

Uploading Keys

For EMAIL_KEY items, click Upload Keys in the item editor, select your file, and save. Keys are securely stored and distributed FIFO.

Grant Virtual Currency Fulfillment

Use GRANT_VIRTUAL_CURRENCY when a purchase should immediately grant in-game currency instead of an external key or manual entitlement. This is ideal for bundles, starter packs, or reward items that top up a player's balance.

To configure this in the dashboard, first create a virtual currency for your game under Games → Virtual Currency. Then, in the store item editor, set the item's fulfillment type to Grant Virtual Currency, choose the currency to grant, and specify the whole units to credit. When the purchase is marked paid, Oncade records a journal entry and credits the player's balance using the same ledger system as the virtual currency API.

If virtual currency features are disabled for your environment, items cannot use GRANT_VIRTUAL_CURRENCY. Enable the appropriate feature flags before testing this flow, and monitor the player's virtual currency balance and journal entries to verify that grants are applied as expected.

When updating store items via PUT /api/store/items/[id], to disable subscription VC top-up you must clear both grantVirtualCurrencyId and grantAmount together (e.g. grantVirtualCurrencyId: '' or null, grantAmount: null). Partial clears (only one field) are ignored. See Subscriptions for full details.

Game-level webhooks are still available for observability across all fulfillment types. For details on webhook payloads, event types, and signature verification, see the Integration Guides → Webhooks section of the docs.

Example: Purchase Complete Payload

Here is a sample payload for a completed purchase (as returned by the API):

Metadata Passthrough

The metadata block is echoed from whatever you pass when starting the purchase via the wallet or virtual currency APIs. This allows you to thread request context (e.g., platform, session ID, campaign tags) through to the completion event and any webhooks. Metadata must be a plain JSON object (max 4KB, max 5 levels deep) containing only strings, numbers, booleans, null, arrays, or nested objects.

{
  "_id": "65f1c2e4b7e1a2c3d4e5f678",
  "gameId": "game_123",
  "environment": "test",
  "itemId": "65f1c2e4b7e1a2c3d4e5f123",
  "amount": 499,
  "currency": "USD",
  "status": "completed",
  "fulfillmentType": "GRANT_VIRTUAL_CURRENCY",
  "fulfillmentStatus": "completed",
  "metadata": {
    "platform": "steam",
    "region": "NA"
  },
  "createdAt": "2024-05-14T12:34:56.000Z",
  "updatedAt": "2024-05-14T12:35:01.000Z"
}