API Reference
The Oncade Server API lets you manage account linking, products, wallets and purchases from your game servers. All requests require HTTPS and include authentication headers.
NOTE: we also provide the Oncade API Test Dashboard. You can try out requests live at Oncade API Test Dashboard.
Common headers
Every request must include the Authorization header with Bearer <your_api_key> and X-Oncade-API-Version (defaults to v1). Game endpoints require X-Game-Id with a server API key. Campaign endpoints (/v1/campaign/...) require X-Campaign-Id with a campaign API key. For POST and PUT requests, supply an Idempotency-Key to safely retry requests without creating duplicates.
Get GameGET
/v1/game
Fetch game information for the game associated with the server API key. Returns public game details including name, description, images, and visibility settings.
curl -X GET https://oncade.gg/api/v1/game \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"gameId": "test-game",
"name": "Test Game",
"description": "An awesome test game",
"imageUrl": "https://example.com/image.png",
"smallImageUrl": "https://example.com/small.png",
"storeImageUrl": "https://example.com/store.png",
"demoUrl": "https://example.com/demo",
"steamAppId": "12345",
"discordUrl": "https://discord.gg/test",
"screenshots": [
"https://example.com/ss1.png",
"https://example.com/ss2.png"
],
"status": "approved",
"environment": "test",
"affiliateRate": 10,
"enableTip": true,
"isVisible": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-02T00:00:00.000Z"
}Initiate Account LinkPOST
/v1/users/link/initiate
Begin linking a player account. Email is optional - if not provided, the player will sign in or sign up during the linking flow. Retries rely on the Idempotency-Key header. Returns 201 Created with a Location header to the confirmation URL when a new session is created (200 if an active session already exists) and dispatches the User.Account.Link.Started webhook for new sessions.
curl -X POST https://oncade.gg/api/v1/users/link/initiate \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: b4634f2b-ddea-4bd4-8c77-2f7ff584e2c8" \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com"
}'Example Response
{
"url": "https://oncade.gg/link?session=session_abc123",
"sessionKey": "session_abc123"
}Initiate Account Link (GET)GET
/v1/users/link/initiate
Begin linking a player account without requiring an email upfront. Creates a new linking session that the player can join by signing in or signing up. Returns 201 Created with a Location header to the confirmation URL and dispatches the User.Account.Link.Started webhook. This method is equivalent to POST without an email parameter.
curl -X GET https://oncade.gg/api/v1/users/link/initiate \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"url": "https://oncade.gg/link?session=session_abc123",
"sessionKey": "session_abc123"
}Create Virtual CurrencyPOST
/v1/vc/currencies
Define a virtual currency for your game, including display name, pricing ratio, and treasury wallet. Requires an Idempotency-Key header.
curl -X POST https://oncade.gg/api/v1/vc/currencies \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: cc167c82-1fb1-404a-8e0b-c25890efb2f3" \
-H "Content-Type: application/json" \
-d '{
"code": "GEM",
"name": "Gems",
"baseUnitsPerVcUnit": "100",
"centralWalletAddress": "wallet-placeholder"
}'Example Response
{
"currency": {
"_id": "cur_123",
"code": "GEM",
"name": "Gems",
"status": "active",
"baseUnitsPerVcUnit": "100",
"centralWalletAddress": "wallet-placeholder"
}
}List Virtual CurrenciesGET
/v1/vc/currencies
Return paginated virtual currencies owned by the authenticated server key.
curl -X GET https://oncade.gg/api/v1/vc/currencies?page=1&limit=20 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "cur_123",
"code": "GEM",
"name": "Gems",
"status": "active",
"baseUnitsPerVcUnit": "100",
"centralWalletAddress": "wallet-placeholder"
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Update Virtual CurrencyPATCH
/v1/vc/currencies/{currencyId}
Adjust mutable currency fields such as name, status, conversion ratio, or treasury wallet.
curl -X PATCH https://oncade.gg/api/v1/vc/currencies/ \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Get User BalanceGET
/v1/vc/balances
Fetch a player balance for the specified currency. Returns current balance and last update timestamp.
curl -X GET https://oncade.gg/api/v1/vc/balances?currencyId=cur_123&userRef=link_usr_abc \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"currencyId": "cur_123",
"userRef": "link_usr_abc",
"balanceUnits": "500",
"updatedAt": "2024-05-01T00:00:00.000Z"
}List Journal EntriesGET
/v1/vc/journals
Return paginated ledger entries for a player and currency. Results are sorted newest-first.
curl -X GET https://oncade.gg/api/v1/vc/journals?currencyId=cur_123&userRef=link_usr_abc \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "jrnl_001",
"type": "credit",
"postings": [
{
"account": {
"type": "pool",
"address": "wallet-placeholder"
},
"deltaUnits": "-500"
},
{
"account": {
"type": "user",
"userRef": "link_usr_abc"
},
"deltaUnits": "500"
}
],
"createdAt": "2024-05-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Credit Player BalancePOST
/v1/vc/credits
Move units from the treasury wallet into a player balance and record a journal entry. Returns 201 Created with Location header.
curl -X POST https://oncade.gg/api/v1/vc/credits \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 8f52eee8-bc02-4a73-8294-13922cd016b7" \
-H "Content-Type: application/json" \
-d '{
"currencyId": "cur_123",
"userRef": "link_usr_abc",
"amountUnits": "500",
"orderId": "order-123"
}'Example Response
{
"journalId": "jrnl_002",
"newBalanceUnits": "1500",
"breakdown": [
{
"participant": "pool",
"direction": "debit",
"amountUnits": "500",
"description": "Credit to user"
},
{
"participant": "user",
"direction": "credit",
"userRef": "link_usr_abc",
"amountUnits": "500",
"description": "Credit to user"
}
]
}Debit Player BalancePOST
/v1/vc/debits
Remove units from a player balance and return them to the treasury wallet. Supports refund and adjustment transaction types. Returns 201 Created with Location header.
curl -X POST https://oncade.gg/api/v1/vc/debits \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 6abc90b2-6d19-49f4-8e3c-0bf25797a909" \
-H "Content-Type: application/json" \
-d '{
"currencyId": "cur_123",
"userRef": "link_usr_abc",
"amountUnits": "250",
"reason": "refund"
}'Example Response
{
"journalId": "jrnl_003",
"newBalanceUnits": "1250",
"breakdown": [
{
"participant": "user",
"direction": "debit",
"userRef": "link_usr_abc",
"amountUnits": "250",
"description": "Refund"
},
{
"participant": "pool",
"direction": "credit",
"amountUnits": "250",
"description": "Refund"
}
]
}Batch Debit with DistributionPOST
/v1/vc/batch-debits
Atomically deduct units from one player and distribute them to multiple recipients (other players or pool). All operations succeed or fail together. Source userRef must have enough balance to cover the total debit amount. The total debit amount is automatically calculated as the sum of all recipient amounts.
curl -X POST https://oncade.gg/api/v1/vc/batch-debits \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: f4192e07-5ee3-4bca-8321-1f2b44f1f3ab" \
-H "Content-Type: application/json" \
-d '{
"currencyId": "cur_123",
"sourceUserRef": "link_usr_player1",
"recipients": "[\n {\n \"userRef\": \"link_usr_winner1\",\n \"amountUnits\": \"100\",\n \"description\": \"First place\"\n },\n {\n \"userRef\": \"link_usr_winner2\",\n \"amountUnits\": \"50\",\n \"description\": \"Second place\"\n },\n {\n \"toPool\": true,\n \"amountUnits\": \"25\",\n \"description\": \"Pool contribution\"\n },\n {\n \"toPool\": true,\n \"amountUnits\": \"25\",\n \"description\": \"Game wallet fee\"\n }\n]"
}'Example Response
{
"journalId": "jrnl_batch_001",
"newBalanceUnits": "800",
"breakdown": [
{
"participant": "user",
"direction": "debit",
"userRef": "link_usr_player1",
"amountUnits": "200",
"description": "Batch transaction debit"
},
{
"participant": "user",
"direction": "credit",
"userRef": "link_usr_winner1",
"amountUnits": "100",
"description": "First place"
},
{
"participant": "user",
"direction": "credit",
"userRef": "link_usr_winner2",
"amountUnits": "50",
"description": "Second place"
},
{
"participant": "pool",
"direction": "credit",
"amountUnits": "25",
"description": "Pool contribution"
},
{
"participant": "pool",
"direction": "credit",
"amountUnits": "25",
"description": "Game wallet fee"
}
]
}Create Cashout RequestPOST
/v1/vc/cashouts
Stage a conversion request for manual review. Validates user has sufficient balance before creating the request. The balance is untouched until approval. Returns 201 Created with Location header.
curl -X POST https://oncade.gg/api/v1/vc/cashouts \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 624e3e89-585a-47e3-ad91-374792f4565e" \
-H "Content-Type: application/json" \
-d '{
"currencyId": "cur_123",
"userRef": "link_usr_abc",
"units": "2000"
}'Example Response
{
"cashoutRequestId": "co_001"
}List Cashout RequestsGET
/v1/vc/cashouts
Return pending or historical cashout requests with pagination.
curl -X GET https://oncade.gg/api/v1/vc/cashouts?currencyId=cur_123&status=pendingReview&page=1&limit=20 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"items": [
{
"_id": "co_001",
"userRef": "link_usr_abc",
"unitsRequested": "2000",
"status": "pendingReview",
"requestedRate": {
"baseUnitsPerVcUnit": "100",
"capturedAt": "2024-05-01T00:00:00.000Z"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Approve Cashout RequestPOST
/v1/vc/cashouts/{cashoutRequestId}/approve
Burn the requested units, record a conversion transaction, and return the conversion snapshot.
curl -X POST https://oncade.gg/api/v1/vc/cashouts/co_001/approve \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: cc8956c6-a48e-4ee7-94c2-e31ca790e5cd"Example Response
{
"transactionId": "jrnl_convert_1",
"usedBaseUnitsPerVcUnit": "100",
"convertedBaseUnits": "200000"
}Reject Cashout RequestPOST
/v1/vc/cashouts/{cashoutRequestId}/reject
Move a pending request to a rejected state with an optional reason. Returns 204 No Content on success.
curl -X POST https://oncade.gg/api/v1/vc/cashouts/co_001/reject \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: cbeaef05-2b80-4055-bfed-756b2a7938bd" \
-H "Content-Type: application/json" \
-d '{
"reason": "KYC pending"
}'Get CampaignGET
/v1/campaign/{campaignId}
Fetch campaign details, current status and balances.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"campaign": {
"id": "cmp_demo",
"name": "My Campaign",
"environment": "test",
"status": "started",
"businessId": "65fa1234abcdef5678901234",
"address": "0xabcDEFabcDEFabcDEFabcDEFabcDEFabcDEFabcd",
"createdAt": "2025-09-01T12:34:56.789Z",
"updatedAt": "2025-09-01T12:34:56.789Z",
"totalAmountFunded": 0,
"totalAmountPaidOut": 0,
"availableToWithdraw": 0
}
}Start CampaignPUT
/v1/campaign/{campaignId}/start
Activate the campaign. Returns 202 Accepted and enqueues a background job.
curl -X PUT https://oncade.gg/api/v1/campaign/cmp_demo/start \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 0554db10-7402-4022-8707-408e2b330cb3"Example Response
{
"success": true,
"message": "Start enqueued"
}Stop CampaignPUT
/v1/campaign/{campaignId}/stop
Freeze/stop the campaign. Returns 202 Accepted and enqueues a background job.
curl -X PUT https://oncade.gg/api/v1/campaign/cmp_demo/stop \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 0d201722-5972-4711-ac4c-021f15e51bf0"Example Response
{
"success": true,
"message": "Stop enqueued"
}Enqueue Campaign EventPOST
/v1/campaign/{campaignId}/events
Record a campaign event for a linked user. Returns 202 Accepted when enqueued.
curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/events \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 6cc7a2bd-0f43-425c-99fb-5ec7722a0f61" \
-H "Content-Type: application/json" \
-d '{
"eventCode": "quest_complete",
"userRef": "link_usr_123"
}'Example Response
{
"success": true,
"message": "Event enqueued"
}List Campaign EventsGET
/v1/campaign/{campaignId}/events
Return configured campaign events (code, name, payoutAmount).
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/events \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"events": [
{
"code": "quest_complete",
"name": "Quest Complete",
"payoutAmount": 1000
}
]
}Withdraw Campaign FundsPOST
/v1/campaign/{campaignId}/withdraw
Withdraw all remaining funds from a stopped campaign. Returns 202 Accepted and enqueues a background job.
curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/withdraw \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: b300347d-be57-446f-8a53-4dd05a6e4db3"Example Response
{
"success": true,
"message": "Withdrawal enqueued"
}Get Campaign User DetailsGET
/v1/campaign/{campaignId}/user/{userId}
Get user-specific campaign details including current status.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/user/user_123 \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"data": {
"campaignId": "cmp_demo",
"userId": "user_123",
"status": "started",
"environment": "test"
}
}Get Campaign User EventsGET
/v1/campaign/{campaignId}/user/{userId}/events
Retrieve paginated event history (transactions) for a specific user in a campaign. Returns all events triggered by the user with payout details and transaction hashes.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/user/user_123/events?limit=10&offset=0 \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"success": true,
"data": {
"campaignId": "cmp_demo",
"userId": "user_123",
"environment": "test",
"transactions": [
{
"id": "507f1f77bcf86cd799439011",
"campaignId": "cmp_demo",
"userRef": "user_123",
"eventCode": "quest_complete",
"eventName": "Quest Complete",
"payoutAmount": 1000,
"transactionHash": "0xabc123def456...",
"createdAt": "2025-10-01T14:30:00.000Z"
}
],
"pagination": {
"limit": 10,
"offset": 0,
"total": 1,
"hasMore": false
}
}
}Get Link StatusGET
/v1/users/link/details
Return metadata for an account link session, including the namespace type (game or campaign), the prefilled email, and the userRef once the session is approved. When set, the payload also includes the spendPermission request.
curl -X GET https://oncade.gg/api/v1/users/link/details?session=session_abc123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"namespaceType": "game",
"gameId": "game_123",
"gameName": "Demo Game",
"prefilledEmail": "player@example.com",
"userRef": "user_123",
"spendPermission": {
"tenantId": "0xbadd768a99ec4b5c0fbc3771b8bd077ebe590f0648f913dc38fee0ce7a1dde6b",
"tenantName": "Demo Game",
"tokenAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"allowanceUSDC": "250",
"periodSeconds": 604800,
"durationSeconds": 7776000,
"tenantModuleAddress": "0x4042Ff8Edc9A60C0B5B15B34c57660E2Bae45dBC",
"networkKey": "base-sepolia"
}
}Initiate Campaign Account LinkPOST
/v1/campaign/{campaignId}/users/link/initiate
Send a linking email scoped to a campaign. Requires the campaign API key and an Idempotency-Key header. Returns 201 Created with a Location header to the approval URL and a JSON body { url, sessionKey } while dispatching User.Account.Link.Started for new sessions. If a pending unexpired session already exists, returns 200 with the same body.
curl -X POST https://oncade.gg/api/v1/campaign/cmp_demo/users/link/initiate \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: aa103756-2bdb-4a39-ae83-c6248ba2b862" \
-H "Content-Type: application/json" \
-d '{
"email": "player@example.com"
}'Example Response
{
"url": "https://oncade.gg/link?session=session_abc123",
"sessionKey": "session_abc123"
}Campaign Link StatusGET
/v1/campaign/{campaignId}/users/link/details
Fetch the status of a campaign-scoped account link session and return the userRef when approved. When set, the campaign payload also includes the spendPermission request.
curl -X GET https://oncade.gg/api/v1/campaign/cmp_demo/users/link/details?session=session_abc123 \
-H "Authorization: Bearer CAMPAIGN_API_KEY" \
-H "X-Campaign-Id: CAMPAIGN_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"campaignId": "cmp_demo",
"campaignName": "Demo Campaign",
"prefilledEmail": "player@example.com",
"status": "approved",
"userRef": "user_123",
"spendPermission": {
"tenantId": "0xbadd768a99ec4b5c0fbc3771b8bd077ebe590f0648f913dc38fee0ce7a1dde6b",
"tenantName": "Demo Campaign",
"tokenAddress": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"allowanceUSDC": "250",
"periodSeconds": 604800,
"durationSeconds": 7776000,
"tenantModuleAddress": "0x4042Ff8Edc9A60C0B5B15B34c57660E2Bae45dBC",
"networkKey": "base-sepolia"
}
}Get User PurchasesGET
/v1/users/{userRef}/purchases
List purchase history for a user. Supports pagination and filtering while returning the populated purchase item.
curl -X GET https://oncade.gg/api/v1/users/user_123/purchases?limit=10&offset=20&type=subscription \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
[
{
"itemId": "507f1f77bcf86cd799439011",
"gameId": "game_123",
"createdAt": "2024-03-10T14:12:01.123Z",
"item": {
"name": "Founders Pass",
"type": "subscription",
"price": 1299
}
}
]Get User InfoGET
/v1/users/{userRef}
Fetch profile information for a user. Returns email, optional profile image, and all subscriptions (game-scoped only).
curl -X GET https://oncade.gg/api/v1/users/user_123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"userRef": "user_123",
"email": "player@example.com",
"profileImageUrl": "https://cdn.example.com/u/123.png",
"subscriptions": [
{
"itemId": "item_456",
"status": "Active",
"subscriptionId": "sub_123",
"planCode": "PREMIUM_MONTHLY",
"planId": "plan_abc"
}
]
}Get User SubscriptionsGET
/v1/users/{userRef}/subscriptions
Fetch all subscriptions for a user. Returns an array of subscription details including status, item ID, and plan information.
curl -X GET https://oncade.gg/api/v1/users/user_123/subscriptions \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"subscriptions": [
{
"itemId": "item_456",
"status": "Active",
"subscriptionId": "sub_123",
"planCode": "PREMIUM_MONTHLY",
"planId": "plan_abc"
},
{
"itemId": "item_789",
"status": "Canceled",
"subscriptionId": "sub_456",
"planCode": "BASIC_YEARLY",
"planId": "plan_xyz"
}
]
}Get Subscription by ItemGET
/v1/users/{userRef}/subscriptions/{itemId}
Fetch a specific subscription for a user by item ID. Returns the subscription details if the user has an active or inactive subscription for the given item.
curl -X GET https://oncade.gg/api/v1/users/user_123/subscriptions/item_456 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"itemId": "item_456",
"status": "Active",
"subscriptionId": "sub_123",
"planCode": "PREMIUM_MONTHLY",
"planId": "plan_abc"
}Approve Account LinkPOST
/v1/users/link/approve
Completes an account linking session for the authenticated player once they approve the link. On success we dispatch User.Account.Link.Succeeded; unexpected processing errors emit User.Account.Link.Failed with the same session key for observability. If the user does not have an email in their Privy account and no prefilledEmail exists in the session, an email must be provided in the request body for new user creation. Returns 400 with code EMAIL_REQUIRED when email is missing for new user creation, or code INVALID_EMAIL when the provided email format is invalid.
curl -X POST https://oncade.gg/api/v1/users/link/approve \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 5b804576-f41b-49ae-85a7-b8f608462e57" \
-H "Content-Type: application/json" \
-d '{
"sessionKey": "session_abc123",
"email": "user@example.com"
}'Example Response
{
"success": true
}Decline Account LinkPOST
/v1/users/link/decline
Declines an in-progress account linking session for the authenticated player.
curl -X POST https://oncade.gg/api/v1/users/link/decline \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 83b46b57-105f-4f82-9074-7d9f4006e71c" \
-H "Content-Type: application/json" \
-d '{
"sessionKey": "session_abc123"
}'Example Response
{
"success": true
}Remove Account LinkPOST
/v1/users/link/remove
Invalidates a previously approved link between a player and the current game.
curl -X POST https://oncade.gg/api/v1/users/link/remove \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: fb2ddaeb-bcb5-44c3-80e4-6b138ddb350b" \
-H "Content-Type: application/json" \
-d '{
"user_ref": "user_abc123"
}'Example Response
{
"success": true
}Cancel SubscriptionPOST
/v1/users/{userRef}/subscriptions/{itemId}/cancel
Cancels an active subscription for the provided user and item. Works for all users, including guest accounts that purchased without signing in. Dispatches a Subscription.Canceled webhook on success.
curl -X POST https://oncade.gg/api/v1/users/user_abc123/subscriptions/6565fade4f0d5f25af0a9ab3/cancel \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 5786b082-6255-428d-8b3d-8ea121af7327"Example Response
{
"success": true,
"subscriptionId": "sub_123"
}List ProductsGET
/v1/products
Retrieve a paginated list of products for the game. Filter by status, type, creator wallet or keyword search.
curl -X GET https://oncade.gg/api/v1/products?status=active&type=purchase&q=sword&page=1&limit=20 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"products": [
{
"_id": "64b10b1cec13f995e9000011",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Sword of Testing",
"description": "Legendary blade for QA heroes.",
"price": 100,
"fulfillmentType": "NONE",
"isVisible": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 1,
"totalPages": 1,
"hasNextPage": false,
"hasPrevPage": false
}
}Get ProductGET
/v1/product/{productId}
Fetch a single product by its identifier when it belongs to the requesting game and environment.
curl -X GET https://oncade.gg/api/v1/product/64b10b1cec13f995e9000011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"_id": "64b10b1cec13f995e9000011",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Sword of Testing",
"description": "Legendary blade for QA heroes.",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 100,
"fulfillmentType": "NONE",
"isVisible": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Create Product (SDK)POST
/v1/product
Create a new product directly from your game server. Supports USD and virtual currency pricing. Products are created as active and visible by default. Use GET /v1/vc/currencies to find available virtual currencies for your game. Multiple validation errors are returned as a semicolon-separated list. Returns 201 Created with Location header.
curl -X POST https://oncade.gg/api/v1/product \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: bd4a2391-8b35-4e03-a6af-e9ec52935cb3" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium Sword",
"type": "purchase",
"fulfillmentType": "WEBHOOK",
"description": "A legendary blade",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 1500,
"virtualCurrencyPrices": "[\n {\n \"currencyId\": \"cur_123\",\n \"amount\": 100\n }\n]",
"perUserLimit": 1,
"metadata": {
"rarity": "legendary"
}
}'Example Response
{
"_id": "65fa1234abcdef5678901234",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Premium Sword",
"description": "A legendary blade",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 1500,
"hasUsdPrice": true,
"virtualCurrencyPrices": [
{
"currencyId": "cur_123",
"amount": 100,
"currency": {
"code": "GEM",
"name": "Gems"
}
}
],
"fulfillmentType": "WEBHOOK",
"isVisible": true,
"isPriceVisible": true,
"forSale": true,
"perUserLimit": 1,
"status": "active",
"creatorType": "game",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Update Product (SDK)PATCH
/v1/product/{productId}
Update an existing product from your game server. All fields are optional. Supports USD and virtual currency pricing updates. Use GET /v1/vc/currencies to find available virtual currencies. Multiple validation errors are returned as a semicolon-separated list.
curl -X PATCH https://oncade.gg/api/v1/product/65fa1234abcdef5678901234 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-d '{
"name": "Premium Sword v2",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 1200,
"virtualCurrencyPrices": "[\n {\n \"currencyId\": \"cur_123\",\n \"amount\": 80\n }\n]",
"forSale": "true"
}'Example Response
{
"_id": "65fa1234abcdef5678901234",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Premium Sword v2",
"description": "A legendary blade",
"baseGameRequirementText": "Requires the free base game to play.",
"price": 1200,
"hasUsdPrice": true,
"virtualCurrencyPrices": [
{
"currencyId": "cur_123",
"amount": 80,
"currency": {
"code": "GEM",
"name": "Gems"
}
}
],
"fulfillmentType": "WEBHOOK",
"isVisible": true,
"isPriceVisible": true,
"forSale": true,
"perUserLimit": 1,
"status": "active",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-02T00:00:00.000Z"
}Create ProductPOST
/v1/products
Create a new product for the game. Returns 201 Created with Location header on success.
curl -X POST https://oncade.gg/api/v1/products \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 7eca4795-ec49-40a9-92c8-183bc39ba7ad" \
-H "Content-Type: application/json" \
-d '{
"name": "Test Weapon",
"type": "purchase",
"fulfillmentType": "WEBHOOK",
"description": "A test weapon created from the frontend",
"price": 1500,
"imageUrl": "https://cdn.example.com/items/test-weapon.png",
"perUserLimit": 2,
"purchaseDisplayInfo": "purchase_count",
"metadata": {
"rarity": "legendary"
}
}'Example Response
{
"_id": "65fa1234abcdef5678901234",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Test Weapon",
"description": "A test weapon created from the frontend",
"price": 1500,
"fulfillmentType": "WEBHOOK",
"isVisible": true,
"isPriceVisible": true,
"forSale": true,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Update Product Sale StatePUT
/v1/products
Enable or disable sales for an existing product.
curl -X PUT https://oncade.gg/api/v1/products \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 47fc8a25-9e33-43a1-90fd-90ef068c9a94" \
-H "Content-Type: application/json" \
-d '{
"productId": "507f1f77bcf86cd799439011",
"forSale": "true"
}'Example Response
{
"_id": "507f1f77bcf86cd799439011",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"name": "Sword of Dawn",
"price": 1500,
"forSale": true,
"fulfillmentType": "WEBHOOK"
}Create UGC ProductPOST
/v1/products/{userRef}
Create a user-generated content product for a specific user. New listings are created as drafts with sales disabled until promoted, hidden by default. Returns 201 Created with Location header on success.
curl -X POST https://oncade.gg/api/v1/products/link_usr_123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 48b76ab3-bb77-4c38-81f2-83880c4cc679" \
-H "Content-Type: application/json" \
-d '{
"name": "User Created Armor",
"type": "purchase",
"fulfillmentType": "WEBHOOK",
"description": "Custom armor created by user",
"price": 2000,
"metadata": {
"rarity": "legendary"
},
"imageUrl": "https://cdn.example.com/items/ugc-armor.png",
"perUserLimit": 1
}'Example Response
{
"_id": "65fa1234abcdef5678901234",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"creatorType": "ugc",
"status": "draft",
"name": "User Created Armor",
"description": "Custom armor created by user",
"price": 2000,
"imageUrl": "https://cdn.example.com/items/ugc-armor.png",
"metadata": {
"rarity": "legendary",
"idempotencyKey": "ugc-armor-20240501"
},
"perUserLimit": 1,
"isVisible": false,
"isPriceVisible": true,
"forSale": false,
"createdAt": "2024-04-22T18:07:43.123Z",
"updatedAt": "2024-04-22T18:07:43.123Z",
"fulfillmentType": "WEBHOOK"
}Submit Product for ReviewPOST
/v1/products/{userRef}/{productId}/submit
Submit a user-generated product for admin review.
curl -X POST https://oncade.gg/api/v1/products/user_123/product_1/submit \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 51f7f8ae-de70-49f9-ae38-7d4082adbf73"Review ProductPOST
/v1/products/{userRef}/{productId}/review
Approve or decline a submitted product ('approve', 'decline', or 'decline_final'). When approving, you can optionally override display/sale controls and pricing fields. Multiple validation errors are returned as a semicolon-separated list.
curl -X POST https://oncade.gg/api/v1/products/user_123/product_1/review \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 2b1f567e-94c6-4b0e-b09b-2bc1efafb859" \
-H "Content-Type: application/json" \
-d '{
"decision": "approve",
"isVisible": "true",
"forSale": "true",
"price": 1500,
"virtualCurrencyPrices": "[\n {\n \"currencyId\": \"cur_123\",\n \"amount\": 100\n }\n]"
}'Example Response
{
"_id": "65fa1234abcdef5678901234",
"gameId": "game_123",
"environment": "test",
"type": "purchase",
"creatorType": "ugc",
"status": "active",
"name": "User Created Armor",
"description": "Custom armor created by user",
"price": 1500,
"hasUsdPrice": true,
"virtualCurrencyPrices": [
{
"currencyId": "cur_123",
"amount": 100
}
],
"virtualCurrencyDetails": [
{
"_id": "cur_123",
"code": "GEM",
"name": "Gems"
}
],
"imageUrl": "https://cdn.example.com/items/ugc-armor.png",
"metadata": {
"rarity": "legendary",
"idempotencyKey": "ugc-armor-20240501"
},
"perUserLimit": 1,
"isVisible": true,
"isPriceVisible": true,
"forSale": true,
"fulfillmentType": "WEBHOOK",
"createdAt": "2024-04-22T18:07:43.123Z",
"updatedAt": "2024-04-22T18:07:43.123Z"
}List Creator ProductsGET
/v1/products/{userRef}
List products created by a specific user.
curl -X GET https://oncade.gg/api/v1/products/user_123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Get User BalancePOST
/v1/wallet/balance
Return the linked wallet address and current balance for the requested user. Requires an Idempotency-Key header.
curl -X POST https://oncade.gg/api/v1/wallet/balance \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 0e35d10a-f6dd-45d7-a94f-ba65a1594d53" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_123"
}'Example Response
{
"address": "0xabcDEFabcDEFabcDEFabcDEFabcDEFabcDEFabcd",
"balance": "1500000"
}Get Manage Wallet LinkPOST
/v1/wallet/manage
Generate a link for the user to manage their profile and wallet. Requires an Idempotency-Key header.
curl -X POST https://oncade.gg/api/v1/wallet/manage \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 02c98952-afd6-40db-be5b-34c59b116c72" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_123"
}'Example Response
{
"linkUrl": "https://oncade.gg/dashboard/profile"
}Get Wallet PurchaseGET
/v1/wallet/purchase/{purchaseId}
Retrieve status and payout information for a wallet purchase.
curl -X GET https://oncade.gg/api/v1/wallet/purchase/purchase_abc123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"data": {
"_id": "purchase_abc123",
"itemId": "65fa1234abcdef5678901234",
"userId": "507f1f77bcf86cd799439011",
"gameId": "game_123",
"environment": "test",
"status": "pending",
"fulfillmentStatus": "pending",
"priceInCents": 1000,
"taxAmountInCents": 0,
"feeRate": {
"percentage": 10,
"flat": 0
},
"feeName": "walletFee",
"payouts": [
{
"recipient": "creator",
"recipientAddress": "0xCreatorAddress",
"amount": 700
},
{
"recipient": "platform",
"recipientAddress": "0xPlatformAddress",
"amount": 300
}
],
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}Initiate Virtual Currency PurchasePOST
/v1/vc/purchases
Start a virtual currency purchase. Creates a pending purchase and validates the item can be purchased with the specified currency. Optionally include a deal code to apply special virtual currency pricing. Returns 201 Created with a Location header pointing to the complete endpoint.
curl -X POST https://oncade.gg/api/v1/vc/purchases \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 8f01b9d9-ea8c-42b8-bfb8-82d01c8e327f" \
-H "Content-Type: application/json" \
-d '{
"userId": "link_usr_123",
"itemId": "65fa1234abcdef5678901234",
"currencyId": "cur_abc123",
"affiliateCode": "STREAMER123",
"dealCode": "GEMS_SALE",
"metadata": {
"campaign": "spring"
}
}'Example Response
{
"data": {
"purchaseId": "purchase_abc123",
"currencyId": "cur_abc123",
"amountUnits": "800"
}
}Complete Virtual Currency PurchasePOST
/v1/vc/purchases/{purchaseId}
Complete a virtual currency purchase by debiting the user's balance and fulfilling the purchase. Idempotent via Idempotency-Key header.
curl -X POST https://oncade.gg/api/v1/vc/purchases/purchase_abc123 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 03a5a123-f4d9-4320-a595-f099c13d473d"Example Response
{
"data": {
"purchaseId": "purchase_abc123",
"journalId": "txn_xyz789",
"newBalanceUnits": "9000",
"purchase": {
"_id": "purchase_abc123",
"status": "completed",
"isPaid": true,
"fulfillmentStatus": "completed"
}
}
}Create Affiliate LinkPOST
/v1/affiliate-links
Creates or returns an affiliate short code for the supplied user (and optional item). Uses idempotency key for duplicate prevention.
curl -X POST https://oncade.gg/api/v1/affiliate-links \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 3e5ce1bb-3274-4dd3-9de4-8d14471e57a3" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_abc123",
"itemId": "65fa1234abcdef5678901234"
}'Example Response
{
"shortCode": "abc123"
}Get Checkout ThemeGET
/v1/checkout/theme
Returns the resolved checkout theme for the requested game. If available, the game checkout theme is returned first, with store theme colors as a fallback.
curl -X GET https://oncade.gg/api/v1/checkout/theme?gameId=test-game&itemId=65fa1234abcdef5678901234 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"primaryButtonColor": "#3B82F6",
"secondaryButtonColor": "#22C55E",
"notifyButtonColor": "#374151",
"backgroundColor": "#1F2937",
"borderColor": "#374151",
"priceOverrideColor": "#4ade80",
"logoUrl": "https://cdn.oncade.com/logos/game.png"
}Get Store Checkout URLGET
/v1/checkout/redirect
Validates the item id for the supplied game and returns a client-facing Oncade storefront item URL for checkout. By default, the user is shown all available payment options. Use checkoutMethod to auto-select a specific payment method after authentication (useful for items with only USD pricing). Optionally include a deal code to apply special pricing. Returns 200 with { url } on success. Returns 400 if deal code is invalid or inactive. Returns 410 if the item is not visible or not for sale.
curl -X GET https://oncade.gg/api/v1/checkout/redirect?gameId=test-game&itemId=65fa1234abcdef5678901234&checkoutmethod=credit \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"status": 200,
"headers": {
"Location": "https://oncade.gg/games/test-game/items/65fa1234abcdef5678901234?mode=api&checkoutmethod=credit"
},
"body": {
"url": "https://oncade.gg/games/test-game/items/65fa1234abcdef5678901234?mode=api&checkoutmethod=credit"
}
}Create Checkout GrantPOST
/v1/checkout/grants
Creates a signed checkout grant for external checkout flows. Use this when you want to initiate purchases for users from your game server without requiring them to authenticate on Oncade first. Returns a checkout URL with embedded grant credentials that users can use to complete their purchase. The grant includes a stable user reference (userRef) for tracking purchases in your system. If no userRef is provided, one is generated (or looked up if the email matches an existing account). The same email always resolves to the same userRef for a given game. Grants expire after 2 hours and can only be used once. When the player opens the checkout URL, they can complete purchase as a guest (without signing in) by entering their email; the storefront sends this as the guestEmail parameter when creating the checkout session. For grant flows the grant's email is used when guestEmail is not provided. For non-grant guest checkout, guestEmail is required and the item must be guest-eligible (e.g. not a subscription or virtual-currency grant).
curl -X POST https://oncade.gg/api/v1/checkout/grants \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 7eed13bd-e62c-490f-a229-c7be2695776f" \
-H "Content-Type: application/json" \
-d '{
"itemId": "65fa1234abcdef5678901234",
"email": "player@example.com",
"checkoutMetadata": {
"orderId": "game-order-12345",
"playerId": "player-abc",
"source": "in-game-store"
},
"customMessage": "Thank you for your purchase! Your items will be delivered within 24 hours."
}'Example Response
{
"checkoutUrl": "https://oncade.gg/checkout/grant?checkoutGrantId=550e8400-e29b-41d4-a716-446655440000&sig=abc123...",
"userRef": "user_abc123def456"
}List Split TemplatesGET
/v1/split-templates
Retrieve all split templates for the authenticated game's business. Returns only non-archived templates, sorted by creation date (newest first).
curl -X GET https://oncade.gg/api/v1/split-templates \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"templates": [
{
"_id": "64b10b1cec13f995e9000011",
"name": "Team Revenue Split",
"description": "Default split for team revenue sharing",
"businessId": "64b10b1cec13f995e9000012",
"createdBy": "usr_123",
"recipients": [
{
"email": "dev1@example.com",
"name": "Developer 1",
"percentage": 50
},
{
"email": "dev2@example.com",
"name": "Developer 2",
"percentage": 30
},
{
"email": "dev3@example.com",
"name": "Developer 3",
"percentage": 20
}
],
"isArchived": false,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
],
"total": 1
}Create Split TemplatePOST
/v1/split-templates
Create a new split template for mass payouts. The template defines recipients and their percentage shares. Recipient percentages must sum to exactly 100%. Template names must be unique within a business. Returns 201 Created with Location header.
curl -X POST https://oncade.gg/api/v1/split-templates \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: 8ee4a0ab-5b87-43af-b35f-f7740ade7cf8" \
-H "Content-Type: application/json" \
-d '{
"name": "Team Revenue Split",
"description": "Default split for team revenue sharing",
"recipients": "[\n {\n \"email\": \"dev1@example.com\",\n \"name\": \"Developer 1\",\n \"percentage\": 50\n },\n {\n \"email\": \"dev2@example.com\",\n \"name\": \"Developer 2\",\n \"percentage\": 30\n },\n {\n \"email\": \"dev3@example.com\",\n \"name\": \"Developer 3\",\n \"percentage\": 20\n }\n]"
}'Example Response
{
"_id": "64b10b1cec13f995e9000011",
"name": "Team Revenue Split",
"description": "Default split for team revenue sharing",
"businessId": "64b10b1cec13f995e9000012",
"createdBy": "usr_123",
"recipients": [
{
"email": "dev1@example.com",
"name": "Developer 1",
"percentage": 50
},
{
"email": "dev2@example.com",
"name": "Developer 2",
"percentage": 30
},
{
"email": "dev3@example.com",
"name": "Developer 3",
"percentage": 20
}
],
"isArchived": false,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Get Split TemplateGET
/v1/split-templates/{templateId}
Fetch details of a specific split template by its identifier. The template must belong to the authenticated game's business.
curl -X GET https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"_id": "64b10b1cec13f995e9000011",
"name": "Team Revenue Split",
"description": "Default split for team revenue sharing",
"businessId": "64b10b1cec13f995e9000012",
"createdBy": "usr_123",
"recipients": [
{
"email": "dev1@example.com",
"name": "Developer 1",
"percentage": 50
},
{
"email": "dev2@example.com",
"name": "Developer 2",
"percentage": 30
},
{
"email": "dev3@example.com",
"name": "Developer 3",
"percentage": 20
}
],
"isArchived": false,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}Update Split TemplatePUT
/v1/split-templates/{templateId}
Update an existing split template. All fields are optional. If recipients are updated, their percentages must sum to exactly 100%. Template names must remain unique within the business.
curl -X PUT https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: ac501782-cda4-4440-b042-62e16a94cd0a" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Team Split",
"recipients": "[\n {\n \"email\": \"dev1@example.com\",\n \"name\": \"Developer 1\",\n \"percentage\": 60\n },\n {\n \"email\": \"dev2@example.com\",\n \"name\": \"Developer 2\",\n \"percentage\": 40\n }\n]"
}'Example Response
{
"_id": "64b10b1cec13f995e9000011",
"name": "Updated Team Split",
"description": "Default split for team revenue sharing",
"businessId": "64b10b1cec13f995e9000012",
"createdBy": "usr_123",
"recipients": [
{
"email": "dev1@example.com",
"name": "Developer 1",
"percentage": 60
},
{
"email": "dev2@example.com",
"name": "Developer 2",
"percentage": 40
}
],
"isArchived": false,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-02T00:00:00.000Z"
}Get Split Template Redirect URLGET
/v1/split-templates/{templateId}/redirect
Generates a redirect URL to the DevPortal distribution page with the template pre-loaded. This allows game servers to direct users to initiate a mass payout using a saved split template. Optionally accepts an amount query parameter to pre-fill the distribution amount.
curl -X GET https://oncade.gg/api/v1/split-templates/64b10b1cec13f995e9000011/redirect?amount=1000 \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"url": "https://dev.oncade.gg/dashboard/business/team-payouts/distribute?templateId=64b10b1cec13f995e9000011&amount=1000"
}Submit ComplaintPOST
/api/complaints
Submit a customer complaint related to card services. Complaints are classified server-side as executive (requiring immediate Bridge notification) or operational based on content and channel. Executive complaints include legal threats, regulatory issues, discrimination claims, or complaints from regulatory bodies (CFPB, BBB). Returns 201 Created with Location header pointing to the complaint resource. Automatically sends email notifications to complaints@oncade.xyz and the submitting customer.
curl -X POST https://oncade.gg/api/api/complaints \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1" \
-H "Idempotency-Key: e8a7f4e1-caa8-4cf2-ba88-d43a9ef59d65" \
-H "Content-Type: application/json" \
-d '{
"intakeChannel": "email",
"description": "Card transaction was declined incorrectly at merchant ABC. The card should have sufficient funds."
}'Example Response
{
"id": "65fa1234abcdef5678901234",
"userId": "user_abc123",
"userEmail": "customer@example.com",
"userName": "John Doe",
"intakeChannel": "email",
"dateReceived": "2024-02-25T20:00:00.000Z",
"description": "Card transaction was declined incorrectly at merchant ABC. The card should have sufficient funds.",
"complaintType": "operational",
"correctiveAction": [],
"status": "pending",
"bridgeNotified": false,
"createdAt": "2024-02-25T20:00:00.000Z",
"updatedAt": "2024-02-25T20:00:00.000Z"
}List User ComplaintsGET
/api/complaints
Retrieve all complaints submitted by the authenticated user. Returns up to 50 most recent complaints sorted by creation date (newest first). Internal admin notes are excluded from the response.
curl -X GET https://oncade.gg/api/api/complaints \
-H "Authorization: Bearer SERVER_API_KEY" \
-H "X-Game-Id: GAME_ID" \
-H "X-Oncade-API-Version: v1"Example Response
{
"complaints": [
{
"id": "65fa1234abcdef5678901234",
"userId": "user_abc123",
"userEmail": "customer@example.com",
"userName": "John Doe",
"intakeChannel": "email",
"dateReceived": "2024-02-25T20:00:00.000Z",
"initialResponseDate": "2024-02-26T10:00:00.000Z",
"description": "Card transaction was declined incorrectly.",
"complaintType": "operational",
"correctiveAction": [],
"status": "acknowledged",
"bridgeNotified": false,
"createdAt": "2024-02-25T20:00:00.000Z",
"updatedAt": "2024-02-26T10:00:00.000Z"
}
]
}