Platform Commerce

Request body

The card leg does not take a billing address. The buyer enters it on INVO's hosted checkout.

Card total limits

Balance response: settled (200)

{
  "status": "success",
  "funding_source": "balance",
  "order_id": 123,
  "transaction_id": "TXN_...",
  "new_balance": "45.00",
  "previous_balance": "50.00",
  "currency_name": "Gems",
  "financial_breakdown": {
    "total_paid": "5.00",
    "developer_revenue": "4.82",
    "platform_fee": "0.18"
  }
}

Card response: send the buyer to checkout (200)

{
  "status": "requires_payment",
  "funding_source": "card",
  "session_id": "<id>",
  "checkout_url": "https://invo.network/checkout?session=<token>",
  "expires_at": 1690000000,
  "amount_usd": "5.00"                  // the total_price you sent; what the buyer is charged
}

1. Your server calls POST /purchase with funding_source: "card" and gets a checkout_url.
2. Send the buyer to it: redirect (window.location = checkout_url) or embed it in an iframe.
3. The buyer enters card and billing address on INVO's hosted checkout and pays your price. The page shows the INVO logo, or your game's own logo if you set one in the console (see Use your own logo on checkout).
4. INVO verifies the payment, records the sale and the fee split, and fires platform_commerce.purchased.
5. The buyer returns to your success_url (or cancel_url). Fulfil on the webhook, not on the browser return.

window.addEventListener('message', (e) => {
  if (e.data && e.data.type === 'INVO_CHECKOUT_COMPLETE') {
    // Show a confirmation, but still fulfil on the webhook.
  }
});

A fallback to the webhook for card purchases:

{
  "order_id": 123,
  "status": "completed",          // completed | pending_payment | refunded
  "game_currency_amount": "5.00", // balance leg
  "usd_amount": "5.00",           // card leg
  "payment_method": "card",       // card | network_currency
  "created_at": "2026-07-20T...",
  "invo_fee_usd": "0.33",         // everything INVO kept on the sale, tax excluded
  "partner_share_usd": "4.67"     // your earnings from the sale
}

INVO's fee on each sale: 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 in USD on either leg, and both are null until the sale has settled. They appear on this read and on every entry of the purchase history below.

One player's purchases: GET /api/platform-commerce/purchase-history?player_email=&limit=&cursor= lists them newest first, each entry with exactly these fields, invo_fee_usd and partner_share_usd included. limit is 1 to 100 (default 50); pass the previous page's next_cursor as cursor while has_more is true. An unknown player is 404 PLAYER_NOT_FOUND; a bad cursor is 400 INVALID_CURSOR. For every kind of money activity at once, see player history reads.

You can refund a completed purchase yourself. Body: { "order_id": 123 } or { "client_request_id": "..." }, plus an optional reason. A client_request_id finds card orders as well as balance orders.

{
  "status": "refunded",
  "funding_source": "card",
  "order_id": 123,
  "transaction_id": "TXN_...",
  "refunded_amount_usd": "5.00",
  "tax_refunded_usd": "0.00",
  "processor_refund_reference": "<opaque id>",
  "fee_retained": true,
  "developer_revenue_reversed_usd": "4.67",
  "card_fee_charged_to_partner_usd": "0.33",  // the card fee is not returned
  "partner_debited_usd": "5.00"                // 4.67 + 0.33: what the refund takes from you
}
// balance leg: "refunded_amount", "new_balance", "developer_revenue_reversed"

{
  "status": "refunded",
  "funding_source": "card",
  "order_id": 123,
  "refunded_amount_usd": "2.00",       // this refund
  ...
  "partial_refund": true,
  "adopted": true,                     // an existing refund was recorded; no new money moved
  "refunded_total_usd": "2.00",        // refunded so far
  "charge_total_usd": "5.00",          // the whole charge
  "remaining_usd": "3.00"              // still refundable
}

platform_commerce.purchased (card, $5.00)

{
  "event": "platform_commerce.purchased",
  "data": {
    "transaction_id": "TXN_...",
    "order_id": 123,
    "funding_source": "card",
    "player_email": "buyer@example.com",
    "identity_id": "...",
    "client_request_id": "...",
    "item_id": "sticker_pack_01",
    "item_name": "Sticker Pack",
    "item_quantity": 1,
    "total_price_usd": "5.00",           // what the buyer was charged
    "item_price_usd": "5.00",            // the sale, less any tax
    "tax_usd": "0.00",
    "tax_jurisdiction": null,
    "fee_breakdown": {
      "total_paid": "5.00", "platform_fee": "0.33", "developer_revenue": "4.67",
      "international_card_fee_usd": "0.00"
    },
    "international_card_fee_usd": "0.00", // already inside platform_fee
    "metadata": { "cart_id": "c_9" }       // what you sent; {} when none
  }
}
// balance leg: "unit_price", "total_price", "currency_name", "new_balance" instead of the USD
// fields, plus "client_request_id" and "approval_id" (null unless the buyer approved it)

fee_breakdown describes the sale the fee is taken on. platform_fee is INVO's whole fee and includes the international card fee, so platform_fee + developer_revenue = total_paid. The international card fee is also reported on its own as international_card_fee_usd (top level and in fee_breakdown; "0.00" on a US card and on the balance leg), so the card rate part is platform_fee - international_card_fee_usd. Do not add it to platform_fee again. On a $5.00 sale on a card issued outside the US, platform_fee is 0.41 (the card rate part, 3.5% of 5.00 plus 0.15 = 0.325, rounds to 0.33; the international part, 1.5% of 5.00 = 0.075, rounds to 0.08, each to the nearest cent), international_card_fee_usd is 0.08 and developer_revenue is 4.59. Reconcile your revenue on developer_revenue and a card statement on total_price_usd. On a Merchant of Record card sale the event also carries receipt_number and receipt_url, as does GET /api/platform-commerce/purchase-status/<order_id> once the receipt is issued; on platform_commerce.refunded they are the refund receipt's. Absent otherwise.

platform_commerce.declined (opt-in)

{
  "event": "platform_commerce.declined",
  "data": {
    "approval_id": "PCA20261023120000000000ABC123",
    "client_request_id": "wc_1001",
    "funding_source": "balance",
    "status": "declined",              // declined | expired | cancelled | failed
    "reason": "declined",              // see Buyer-approved balance purchases
    "total_price": "20.00",
    "currency_name": "Gems",
    "item_id": "sku_1",
    "item_quantity": 1,
    "metadata": { "wc_order": "1001" }
  }
}

A buyer-approved purchase that ended without a sale. Nothing was debited. This event is opt-in: a subscription to all events (*) does not receive it. Add platform_commerce.declined to your subscription by name. It fires once per request.

platform_commerce.refunded

{
  "event": "platform_commerce.refunded",
  "data": {
    "order_id": 123,
    "funding_source": "card",
    "player_email": "buyer@example.com",
    "identity_id": "...",
    "refunded_amount": "5.00",
    "amount_unit": "usd",                // "usd" (card) or "currency" (balance)
    "fee_retained": true,
    "developer_revenue_reversed": "4.67",
    "tax_refunded_usd": "0.00",
    "tax_jurisdiction": null,
    "card_fee_charged_to_partner_usd": "0.33",  // card refunds only
    "partner_debited_usd": "5.00",               // card refunds only
    "metadata": { "cart_id": "c_9" }             // the purchase's; {} when none
  }
}

For a card sale refunded in parts, every platform_commerce.refunded event also carries partial_refund, refunded_total_usd and charge_total_usd, and refunded_amount is that refund's own amount. A sale refunded in one go sends none of the three, exactly as before.