Grant-Based Checkout Guide

Grant-based checkout lets your server initiate a purchase on behalf of a consumer. Your server creates a checkout grant for a specific item and receives a URL. The consumer opens that URL, completes payment, and your server is notified via webhook.

This is ideal when you want to control what a user can buy from your own application while letting Oncade handle the checkout experience and payment processing.

How It Works

The grant checkout flow has three participants: your server, the Oncade API, and the consumer.

1. Your server creates a grant — Call POST /v1/checkout/grants with the item ID and optional parameters (email, metadata, custom message). A stable userRef is returned whether the email is new or belongs to an existing account.
2. Redirect the consumer — The response includes a checkoutUrl. Send the consumer to this URL (redirect, link, QR code, etc.).
3. Consumer completes checkout — They enter an email (if not pre-filled), choose a payment method, and pay. No account is required for eligible items.
4. Your server receives a webhook — The Purchases.Completed webhook includes grant_user_ref and any checkout_metadata you attached, so you can correlate the purchase back to your system.

Grant Lifecycle

Each grant moves through a defined set of states. Understanding the lifecycle helps you handle edge cases like cancellations and retries.

Step 1: Create a Checkout Grant

Your server calls POST /v1/checkout/grants to create a grant. Authentication uses your Server API Key (Bearer token) with the X-Game-Id and X-Oncade-API-Version: v1 headers.

Basic grant (anonymous)

The simplest form creates a grant with no pre-filled email. The consumer provides their email during checkout.

curl -s -X POST \
  -H "Authorization: Bearer $SERVER_API_KEY" \
  -H "X-Game-Id: $GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"<item_id>"}' \
  https://<host>/api/v1/checkout/grants

The response returns:

Grant with email (recommended)

When you know the consumer's email, include it in the grant. The email is pre-filled in the checkout form, reducing friction.

curl -s -X POST \
  -H "Authorization: Bearer $SERVER_API_KEY" \
  -H "X-Game-Id: $GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "<item_id>",
    "email": "buyer@example.com"
  }' \
  https://<host>/api/v1/checkout/grants

Grant with metadata and custom message

Attach server-side metadata to the grant for correlation. The metadata is echoed back in the Purchases.Completed webhook, making it easy to match purchases to your internal records. A custom message can also be displayed to the consumer above the checkout form.

curl -s -X POST \
  -H "Authorization: Bearer $SERVER_API_KEY" \
  -H "X-Game-Id: $GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "<item_id>",
    "email": "buyer@example.com",
    "checkoutMetadata": {
      "orderId": "ORD-12345",
      "source": "in-game-shop"
    },
    "customMessage": "Thanks for your purchase!"
  }' \
  https://<host>/api/v1/checkout/grants

Grant with existing user reference

If the consumer already has a userRef from a prior interaction (e.g., account linking), you can pass it to associate the grant with that user.

curl -s -X POST \
  -H "Authorization: Bearer $SERVER_API_KEY" \
  -H "X-Game-Id: $GAME_ID" \
  -H "X-Oncade-API-Version: v1" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "<item_id>",
    "userRef": "tuid_abc123"
  }' \
  https://<host>/api/v1/checkout/grants

Step 2: Consumer Checkout Experience

Once the consumer opens the checkoutUrl, they land on the Oncade checkout page for the specified item. The checkout supports two modes: guest checkout and authenticated checkout.

Guest checkout (no account required)

For eligible items, consumers can complete a purchase without creating an account. They only need to provide an email address (for receipt delivery) and a payment method.

If the grant was created with an email, it is pre-filled in the checkout form. The consumer can still change it before paying.

Authenticated checkout

Consumers can optionally sign in during checkout. If they authenticate, their guest account is automatically linked to their real account, giving them access to purchase history and fulfillment details.

Item eligibility

Grant-based checkout supports all item types that are marked for sale, including key delivery, webhook fulfillment, and other fulfillment types. The consumer can complete the purchase as a guest or choose to sign in.

Step 3: Fulfillment & Webhooks

After a successful payment, Oncade processes fulfillment according to the item's configuration (key delivery, webhook notification, etc.) and sends a Purchases.Completed webhook to your server.

Webhook payload

Grant-based purchases include additional fields in the webhook payload for correlation:

Example webhook payload

{
  "event": "Purchases.Completed",
  "data": {
    "purchaseId": "abc123",
    "itemId": "<item_id>",
    "gameId": "<game_id>",
    "amount": 999,
    "currency": "USD",
    "user_ref": "user_def456ghi789",
    "grant_user_ref": "user_abc123def456",
    "checkout_metadata": {
      "orderId": "ORD-12345",
      "source": "in-game-shop"
    }
  }
}

Metadata correlation flow

The checkoutMetadata field is designed for server-to-server correlation. Attach any data your system needs to reconcile the purchase (order IDs, session IDs, user IDs from your system, etc.), and it is returned verbatim in the webhook.

Purchase Webhooks

Grant-based checkouts emit the same purchase lifecycle webhooks as any other checkout. All webhook payloads include grant_user_ref and checkout_metadata when the purchase originated from a grant.

See the Webhooks Guide for full payload details and signature verification.

Error Handling

The grant creation endpoint returns structured error responses. Handle these in your server to provide appropriate feedback.

API Quick Reference

Request body

Required headers

Best Practices

• Always include an email when you know the consumer's email. This pre-fills the checkout form and reduces abandonment.
• Use checkoutMetadata for correlation rather than parsing the userRef. Metadata is designed for your internal identifiers and is echoed back verbatim in webhooks.
• Handle the 2-hour expiration by creating grants close to when the consumer is ready to purchase. If a grant expires, create a new one.
• Store the userRef on your side when the grant is created. This is your stable reference for matching webhook events to your users.
• Set up webhooks to receive Purchases.Completed events. This is the reliable way to know a purchase succeeded, rather than relying on redirect callbacks.

References

• API Reference
• Webhooks Guide
• Account Linking Guide
• Fulfillment