INVO Network API Overview

Core API Endpoints

Player history reads

Server-to-server, authenticated with X-Game-Secret-Key, read-only. Each returns only what your title is a party to. In the SDKs: getPlayerActivity / iteratePlayerActivity and platformCommerce.getPurchaseHistory / iteratePurchaseHistory in the web SDK from 3.22.0; get_player_activity / iterate_player_activity and platform_commerce.get_purchase_history / iterate_purchase_history in the Python SDK from 3.20.0.

GET /api/sdk/players/activity

Query parameters:

• • player_email (required): the player in your title.
• • types (optional): a comma list of currency_purchase, item_purchase, platform_commerce, send, transfer. Default: all five. An unknown type is 400 INVALID_INPUT.
• • limit (optional): 1 to 100, default 50. Values outside the range are clamped.
• • cursor (optional): the previous page's next_cursor.

GET /api/sdk/players/activity?player_email=bo@example.com&types=send,transfer&limit=2
X-Game-Secret-Key: <your game secret>

200 OK   (Cache-Control: no-store)
{
  "player_email": "bo@example.com",
  "game_id": "123456789012",
  "types": ["send", "transfer"],
  "activity": [
    {
      "id": "TXN_1760000000_AB12CD",
      "type": "transfer",
      "direction": "in",
      "amount": "90.00",
      "amount_unit": "currency",
      "currency": { "currency_id": 7, "currency_name": "Gems" },
      "status": "verified",
      "status_detail": "pending_claim",
      "expiry_reason": null,
      "counterparty_game": { "game_id": "123456789012", "game_name": "Example Game" },
      "created_at": "2026-10-09T14:02:11+00:00",
      "completed_at": null,
      "order_id": "ORD_...",
      "gross_amount": "100.00",
      "fee_amount": "10.00"
    }
  ],
  "limit": 2,
  "has_more": true,
  "next_cursor": "<opaque>"
}

Pagination. Newest first. While has_more is true, pass next_cursor as cursor. A cursor is opaque and valid only for the same player and the same types; a mismatched or malformed one is 400 INVALID_CURSOR.

Errors (the code is in the body's code field): 400 INVALID_INPUT (missing player_email, an unknown type, a non-integer limit), 400 INVALID_CURSOR, 401 INVALID_GAME_SECRET, 404 PLAYER_NOT_FOUND, 500 PLAYER_ACTIVITY_FAILED (retry).

GET /api/platform-commerce/purchase-history

For platform titles. Query: player_email (required), limit (1 to 100, default 50), cursor. Newest first. Each entry carries exactly the fields of GET /api/platform-commerce/purchase-status/<order_id>, so the two never disagree.

200 OK
{
  "player_email": "bo@example.com",
  "game_id": "123456789012",
  "purchases": [
    {
      "order_id": "ORD_...",
      "status": "completed",
      "game_currency_amount": "50.00",
      "usd_amount": "5.00",
      "payment_method": "card",          // or "network_currency" for the balance leg
      "created_at": "2026-10-09T14:02:11+00:00",
      "invo_fee_usd": "0.33",            // everything INVO kept on the sale, tax excluded
      "partner_share_usd": "4.67"        // your earnings from the sale
    }
  ],
  "limit": 50,
  "has_more": false,
  "next_cursor": null
}

invo_fee_usd is everything INVO kept on the sale, tax excluded: the card fee plus any international card fee on a card sale, the platform fee on a balance sale. partner_share_usd is your earnings from the sale. Both are null until the sale has settled (additive).

On a Merchant of Record card sale an entry also carries receipt_number and receipt_url once the receipt is issued. Errors (the code is in error_code): 400 INVALID_INPUT, 400 INVALID_CURSOR, 404 PLAYER_NOT_FOUND, plus the same authentication and platform errors as purchase-status. See Platform Commerce.

Withdrawals before identity verification

You can submit a withdrawal request before your identity verification has been approved. It is accepted and held rather than refused. The request is created, the amount is set aside against your available balance, and it counts toward your pending-request limit exactly like any other pending request. Nobody at INVO can approve it while the hold is on. Once your verification is approved it moves into the normal review queue on its own, with no action from you.

What a held request does and does not do

• • It reserves the money. The amount is deducted from what you can request next, the same as any pending request.
• • It counts toward the pending limit. A held request occupies one of your pending slots.
• • It cannot be approved. No administrator can approve it, from any door, until your verification passes.
• • It can still be rejected. An administrator can reject it at any time, which releases the reserved amount back to your available balance.
• • It never expires. It waits as long as it needs to, including while you fix and resubmit a verification that was rejected or revoked.

The response fields, all additive

Every key POST /api/withdrawals/request returned before is unchanged, including status, which is still "pending_review". There is no new status to learn. Three keys were added:

POST /api/withdrawals/request

Response 201:
{
  "success": true,
  "withdrawal_id": "WDL_20260917120000000000_ab12cd",
  "status": "pending_review",
  "requested_amount": "100",
  "net_payout_amount": "99.00",
  "processing_fee": "1.00",
  "offboarding_fee_pct": "1",
  "offboarding_fee_cap_usd": "500.00",
  "initiated_by": "on_demand",
  "fee_reason": "on_demand",
  "total_pending_withdrawals": 1,
  "kyc_hold": true,
  "kyc_hold_reason": "KYC_IN_REVIEW",
  "next_steps": "Your withdrawal request is on hold until your identity verification is approved. ..."
}

The same fields on the reads

• • GET /api/withdrawals/history carries kyc_hold, kyc_hold_reason and next_steps at the top level, describing the developer now, plus kyc_hold on each row so you can badge the individual requests that are waiting.
• • GET /api/dev/withdrawals/summary carries the same three at the top level and kyc_hold on each pending row. A held request still counts in the pending total and still reduces what is requestable, because the money really is reserved.
• • GET /api/dev/overview/attention gains an item under the withdrawals_kyc component with the code WITHDRAWAL_AWAITING_KYC, carrying count (how many requests are held), amount_usd (their combined requested amount) and reason. Its severity is info while a verification submission is actually in review, because there is nothing for the developer to do, and blocker otherwise, because there is. It is absent once verification is approved and absent when nothing is held.

All of this applies to production. Sandbox does not require identity verification to withdraw, so nothing is held there and kyc_hold is never true.

Withdrawable balance: reserve, dispute holds and payouts in flight

available_balance on GET /api/withdrawals/available-balance, and available_balance_usd and requestable_usd on GET /api/dev/withdrawals/summary, are what you can withdraw now. These are subtracted before you see them, and the reads carry fields that explain them (additive):

• • Partner payouts INVO has approved and is sending, on every tier: in_flight_payouts_usd. Almost always "0.00". While a payout is in flight the balance can drop by a little more than the payout, and the difference returns when it completes.
• • The Merchant of Record chargeback reserve: reserve_held_usd, reserve_next_release_at, reserve_release_schedule, reserve_terms and balance_before_reserve_usd. On Open there is no reserve. See the reserve.
• • Amounts held for open disputes, on every tier: dispute_holds_usd (the total held, already deducted from available_balance) and disputes_on_hold (how many disputes are holding money), on GET /api/withdrawals/available-balance. A hold is released when the dispute is won, or when its loss is booked. See dispute holds.

If the reserve cannot be read these fields are null; show nothing then, never $0.00. A withdrawal request refused for insufficient balance while something is held carries the same fields, and its message gains a sentence naming the held amount. Read the fields, not the message.

Account reserves and account holds

On either tier, INVO can apply a reserve to an account, or hold its payouts, under account standing. Both reads carry these fields (additive):

• • account_reserve_held_usd: the total held by account reserves now, already deducted from the available balance. "0.00" with no account reserve, and null if it cannot be read (show nothing then).
• • account_reserves: the active account reserves, each with kind (rolling_pct, a percentage of your earnings over a number of days; fixed, an amount; or full, the whole balance), pct, amount_usd, days, starts_at, ends_at (null while it has no end date), source, held_usd (what it holds now) and status. [] with no account reserve.
• • account_hold: null while the account can be paid out, otherwise {code, message} saying why not. code is ACCOUNT_SUSPENDED, PAYMENTS_PAUSED or ACCOUNT_UNDER_REVIEW (payouts are held while INVO reviews the account); message is safe to show the account owner.

While account_hold is set, can_withdraw on GET /api/withdrawals/available-balance is false, requestable_usd on GET /api/dev/withdrawals/summary is "0.00", and each pending row there carries account_hold: true. A new POST /api/withdrawals/request is refused with 403 and the same error_code. A pending request is held, not canceled.

Idempotency on writes

Every write endpoint accepts a client_request_id in the body. Generate a UUID per logical action; replay the same id on retry. A duplicate never applies twice. On item purchases, transfers and sends it answers 409 Conflict with a message only, so keep your own record of the ids the first success returned (or read the order back); a partner payout request returns 200 with the payout already created.

// Client generates a fresh UUID per checkout button click
const clientRequestId = crypto.randomUUID();

const r = await fetch('https://invo.network/api/item-purchases/purchase-item', {
  method: 'POST',
  headers: {
    'X-Game-Secret-Key': SDK_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    client_request_id: clientRequestId,
    player_email: 'player@example.com',
    player_name: 'PlayerOne',
    item_id: 'sword_001',
    item_name: 'Iron Sword',
    item_quantity: 1,
    unit_price: '100.00',
    total_price: '100.00'
  })
});

// On 5xx or network failure: retry the SAME request body with the same
// client_request_id. If the first attempt went through, the retry answers
// 409 { "message": "Duplicate client_request_id. ..." } and nothing is charged twice.

Quick Integration Path