Frequently Asked Questions

Every account starts on Open: your business is the seller and handles its own sales tax. Merchant of Record is by approval: INVO is the seller and handles consumption tax where it is registered. The card fee is 3.5% + $0.15 on Open and 5.0% + $0.15 on Merchant of Record, on coin purchases, Platform Commerce card sales and subscription charges. You pay it; the player pays the listed price. GET /api/dev/fee-schedule returns your tier and the rates in force for your account.

Detail: Tiers: Open and Merchant of Record.

Yes, on both tiers: 1.5% of the listed price (before tax) on top of the card fee, paid by you and reported as international_card_fee_usd. INVO charges in USD, so there is no separate currency conversion cost. See Tiers.

$2.99, enforced from 2026-10-27, on coin purchases and Platform Commerce card sales (not on subscriptions). Purchases through a storefront such as Steam keep the storefront's own terms. See the card fee.

• An item bought with coins (Item Purchase): 5%, 95% to you.
• A Platform Commerce item paid from the user's balance: 3.5%.
• A payout to your bank: free on INVO's payout schedule (the 1st and 16th of each month, $10 minimum). A payout you request on demand: 1% of the payout, capped at $500, deducted from the amount sent. See the payout fee.

A 10% network fee: 3.5% to the sending title, 3.5% to the receiving title and 3% to INVO. When both players are in the same title, that title keeps both shares (7%). Sends between players and transfers between titles use the same split. A player moves 100.00:

Read the figures from the response and the webhooks (fee_total on transfer.sent, amount_received on transfer.received) rather than recomputing them. See the worked example.

Yes. Custom and volume pricing is available on request at partners@invo.network. A negotiated rate appears in GET /api/dev/fee-schedule and in the fee fields of every response and webhook, so an integration that reads those fields needs no change. The transfer split is a network standard, the same for every title. See negotiated rates.

No. Platform Commerce is for platform tenants only; a game tenant calling it gets 403 NOT_A_PLATFORM_TENANT. A game sells coins with Currency Purchase and sells items for coins with Item Purchase. See tenant type below.

INVO pays your share to a bank account you have added and verified in the console: a developer withdrawal from the console, or a partner payout over the API (POST /api/partner-payouts/request with X-Game-Secret-Key). Payouts on INVO's schedule are free; an on-demand payout carries the 1% payout fee, capped at $500. See Partner Payouts. Platform partners can also have INVO verify and pay the creators they register, from the same owed balance: see Creator Payouts.

Players, no: they never withdraw from INVO. Creators, yes, if you register them: INVO verifies the creators you register and pays them directly, from the earnings INVO owes you, never from player balances (see Creator Payouts). Anyone else who earns money on your platform you pay from your own funds, on your own rails, under your own agreements. Revenue-share data INVO returns (revenue_share, the subscription attribution reports, which carry settled_by_invo: false) is attribution: it tells you who to pay, and no money has moved to anyone named in it. See Reporting & Attribution.

An approved identity verification (KYC, which includes your tax form) and a verified bank account. A withdrawal requested before identity verification is approved is accepted and held, not refused, and moves into review on its own once verification is approved. Neither is needed to build, test or go live. See API Overview (withdrawals) and going live.

Every title starts as a game. A platform tenant is a non-game app: a video, creator or social platform. Rates, tiers and tax are the same for both, and currency moves between games and platforms in both directions, the same as between two games. The type changes three things:

• Platform Commerce (item sales paid by balance or card) is for platforms only.
• Storefront payment routes (Steam and the game storefront rail) are for games only (RAIL_NOT_AVAILABLE_TO_PLATFORM). The card route is available to both.
• A loyalty campaign can admit games, platforms or both.

By design. Every tenant is addressed the same way: game_id, X-Game-Secret-Key, the /api/dev/games routes. A platform sends the same header, with the same key, on the same calls. See Platform Partners.

Switch yourself on the Platform & Keys page of the console, or with POST /api/dev/games/{game_id}/tenant-type. It is instant and works in either direction until the title's first live transaction; after that a switch between game and platform answers 409 TENANT_TYPE_LOCKED_AFTER_LIVE_TRANSACTION, and INVO makes the change after review. Changing between platform kinds (video, creator, social) is always allowed. Becoming a platform needs the title to be live or testing; no identity verification is needed (that is asked for only before a withdrawal). Switching to a platform resets a game-only storefront payment rail to the card rail. See Platform Partners.

From your server, call POST /api/sdk/players/phone (updatePlayerPhone in the Web SDK, update_player_phone in Python). Save the new number only after it succeeds, and switch to the new player token it returns. If the player has secured their account, it answers 409 PHONE_CHANGE_REQUIRES_VERIFICATION: create a change request (POST /api/sdk/players/phone/change-requests, requestPhoneChange). INVO emails the player, and the player confirms on INVO's page. Your game never sees the code or the link, so never ask for it. You hear the result on player.phone_changed. See Player Identity.

The player already exists in your game with a different phone; the token is for the phone INVO holds and the one you sent was ignored. If the player changed their number in your game, update it as above. If they did not, the number was changed through INVO and INVO's number is current: never push your stored number back. See Player Identity.

The limits, per game and per player, are on Rate Limits. Every call counts, including refused ones, so never retry a 409 in a loop: its code tells you what to do next. On a 429, Retry-After is the real number of seconds until the limit that fired resets. Wait that long.

Checkout pages, yes. Upload your game's logo in the console (Game settings, Checkout branding) and it replaces the INVO logo on the hosted checkout page, the hosted card page for subscriptions and the subscription payment confirmation page. A small “Secured by INVO” line stays at the bottom, because INVO processes the payment. The image must be PNG, JPEG or WebP, up to 1 MB. There is no API call for it. See Use your own logo on checkout.

Approval and claim pages, no. The pages where a player confirms something with INVO (approval, device approval, claim and collect, consent, phone change, guardian) and receipts always look like INVO. They name your title, and the device approval receipt also shows the titles' icons from your title settings, but they are not white-labelled and do not run on your domain. Keeping them identical everywhere teaches players what a genuine INVO approval looks like, so a fake page dressed up as a game is easier to spot. See Device Approval and Platform Step-Up.

Yes. A send is addressed by phone number, and nothing is bound to a player when it starts. When the recipient later has a player in your title with that phone (mint their token with email and phone; the player is created if needed), the send appears in their pending list (GET /api/sdk/transfers/pending) and they collect it with confirm-receipt, as long as the claim is still open. The match is on the player's current phone. Anything not collected in time returns to the sender automatically. See Collecting, Stage by Stage.

The sender can re-deliver it with POST /api/sdk/send/{transaction_id}/resend-claim (nothing new is minted). Usually simpler: once the recipient's player token carries the addressed phone, the send is already in their pending list and they collect it in your title. See Send Overview.

Whoever holds a send's claim link can use it to collect, so the send flow (initiate, approve, resend-claim) never returns it to your servers. It goes only to the recipient: INVO emails it when the recipient's email is already on file for that phone. In your title, use the in-app collect flow (the pending list plus confirm-receipt). See Collecting, Stage by Stage.

GET /api/sdk/players/activity with X-Game-Secret-Key and player_email: one newest-first, cursor-paged list of currency purchases, item purchases, Platform Commerce purchases, sends and transfers, both directions, filterable by types (getPlayerActivity / get_player_activity in the SDKs). Platform Commerce orders alone: GET /api/platform-commerce/purchase-history. See Player history reads.

From the fee and share fields on each response and webhook, the withdrawal and payout reads, and for subscriptions the attribution reports. On each Platform Commerce sale, invo_fee_usd (everything INVO kept, tax excluded) and partner_share_usd (your earnings) are on the purchase status read and in the purchase history, null until the sale has settled. Read the figures rather than recomputing them.

A send or transfer between two players of the same title delivers two copies to that title: one with direction: "outbound" (the sender's side) and one with direction: "inbound" (the recipient's side). Both carry the same transaction_id; each has its own event_id and idempotency key. Drive the recipient's UI from inbound only and the sender's from outbound only. See same-title moves.

On X-Invo-Idempotency-Key (also idempotency_key in the body). It is stable across retries and replays. Never on transaction_id, which would drop one copy of a same-title move, and not on X-Invo-Event-Id, which changes on a replay. Delivery is at least once. See Receiving Webhooks.

Return 2xx, log the raw body and move on. New event types and new fields are added without notice.

GET /api/dev/webhooks/games/{game_id}/deliveries lists delivery history; GET /api/dev/webhooks/deliveries/{delivery_id} returns the full payload and your endpoint's response; POST /api/dev/webhooks/deliveries/{delivery_id}/replay sends one again. Authenticate with X-Game-Secret-Key or your developer sign-in. The console's Webhooks page shows the same. See Webhook Management API.

Every endpoint's limits, and whether each is counted per game, per player or per calling IP, are on Rate Limits. On a 429, wait the Retry-After seconds (the time until the limit that fired resets) and match on error_code RATE_LIMITED, not the message. Refused calls count toward a limit. Every rate-limit refusal is a 429 with retry_after in the body and a Retry-After header; some send-safety checks also answer 429 with their own error value. In every case wait that long and retry, and never hard-code the limits in your client. Money flows also have business limits that answer with their own codes.

Open: you are the seller, so you bear it. While a dispute is open the disputed amount is held from your earnings. A lost dispute costs you what a refund of the same charge would; on a coin purchase, the value of coins the player had already spent is charged to you at the price paid. Card payments made on Open before October 21, 2026 keep the chargeback guarantee for fraud disputes; from that date a chargeback on an Open card payment is yours whatever the reason.

Merchant of Record: a fraud chargeback on a card payment (reason fraudulent or unrecognized: the cardholder says they did not authorize it) is covered by INVO's chargeback guarantee. Other disputes (for example product not received) are yours, as on Open: the disputed amount is held while the dispute is open, released if it is won, and recovered once if it is lost. INVO manages the dispute. The guarantee applies to card payments on INVO's hosted checkout only. See Chargebacks.

Dispute fee, both tiers: From October 21, 2026, on both the Open and Merchant of Record tiers, the card network's dispute fee is passed through to you at cost on every card dispute opened from that date, whatever the date of the sale. INVO adds no administrative fee. If the dispute is won and the network returns the fee, it is credited back to you. INVO's own card fees are not returned on a chargeback. No dispute fee is charged on a dispute covered by the chargeback guarantee. The closing purchase.disputed carries dispute_fee_usd and dispute_fee_charged_to_partner.

The purchase.disputed webhook fires when a dispute opens and again when it closes, with dispute_status won or lost. There is no separate purchase.dispute_lost event. Every dispute on your games is on the console's Disputes page and at GET /api/dev/disputes (filter by outcome: open, inquiry, won, lost, unknown), with its evidence_due_by. Add evidence before that date with POST /api/dev/disputes/{dispute_id}/evidence (a note, text and PDF, JPEG or PNG files), using your developer sign-in. INVO decides what to include and responds; you never contact the card processor. See Seeing disputes and adding evidence.

• Coin purchase: the coins the player still holds from that purchase are taken back, never below zero. The value of any coins the player had already spent is charged to your earnings at the price the player paid per coin (before tax), reported as spent_coins_charged_usd. INVO's card fee is not returned.
• Platform Commerce card sale: your share is reversed (netted from your next payout if it was already paid out), and the card fee stays charged, as on a card refund.
• Subscription charge: that period is reversed as if it had been refunded in full. The subscription is not cancelled.
• Steam: a Steam chargeback arrives once, as purchase.disputed with dispute_status: "lost", and takes the coins back. Storefront purchases have no disputes in the console.

While a dispute you are responsible for is open, the disputed amount is held from your earnings so it cannot be paid out: your share of a Platform Commerce card sale or subscription charge, or on a coin purchase the price paid before tax, less anything already refunded and never more than the disputed amount. Your withdrawable balance already excludes it; GET /api/withdrawals/available-balance reports the total as dispute_holds_usd and the count as disputes_on_hold. Won: the hold is released. Lost: the hold is released as the loss is booked, so the amount is taken only once. See Held while a dispute is open.

• Currency steps (buy currency, transfer, send, spend coins, subscribe) complete from INVO's own records of those payments. You report nothing.
• Gameplay steps complete from events your game server reports: POST /api/sdk/loyalty/server-events with X-Game-Secret-Key.
• Client-reported events (POST /api/sdk/loyalty/events with the player token) show progress, but never unlock a real-value reward.

There is no endpoint to mark a step complete. See Reporting game events.

No. Call the two event routes over HTTP. The SDKs wrap the card, the vault, redeem, the hosted rewards page and the server progress read (getPlayerRewards / get_player_rewards).

In the developer console, inside an INVO campaign your games are enrolled in: pick the steps, the reward, the window and the card text, preview the card and submit it. INVO reviews programs before they go live. Every program you build includes at least one currency purchase, transfer to another game, or currency send. A campaign may admit games, platforms or both, and only titles of an admitted type can enrol. A step that asks the player to watch a video is not available. See Console Programs.

It runs the same code and reports the same fees. What differs: its own base URL and /sandbox prefix (https://sandbox.invo.network/sandbox/api/...), its own game ids and keys, test cards with no real money, test tools that settle approvals without a real device or passkey, platform status without identity verification, and smaller capacity (do not load-test it). See Sandbox Testing.

You don't rebuild it. Once your sandbox account is linked to production (automatic on a verified email match), every sandbox title is copied to production once, with new keys and a new game id; no key, id or player data crosses. If a copy was refused or failed, ask again with Copy to production in the sandbox console. Then set up the production webhook and swap your base URL to https://invo.network/api. See Sandbox Testing.

No. Going live is self-serve: set the title's status to live in the console. Identity verification, your tax form and a verified bank account are needed to be paid, not to go live. Merchant of Record is a separate application, and nothing in your integration changes either way. See Quick Start and Merchant of Record approval.