Currency Purchase

1. Create a checkout session (server-side)

usd_amount is the price you list, and it is what the player pays (plus tax where INVO collects it). Do not add a fee: the card fee is charged to you, not the player.

POST https://invo.network/api/checkout/sessions
Headers:
  X-Game-Secret-Key: ivsdk_<your_sdk_key>
  Content-Type: application/json

Body:
{
  "player_email": "player@example.com",
  "usd_amount": "10.00",
  "rail": "platform",
  "success_url": "https://yourgame.com/store/success",
  "cancel_url":  "https://yourgame.com/store/cancel",
  "metadata": { "your_user_id": "u_42", "coin_pack": "starter" }
}

Response 201:
{
  "session_id":   "<jti>",
  "checkout_url": "https://invo.network/checkout?session=<jwt>",
  "expires_at":   "2026-09-23T12:49:56Z",
  "expires_in_seconds": 900
}

checkout_url carries a 15-minute signed token and is single-use: reusing it after a successful payment returns 409 SESSION_ALREADY_CONSUMED. usd_amount must be above 0 and within the card amount limits, and on the card rail at least the minimum card purchase of $2.99 from 2026-10-27 (400 BELOW_CARD_MINIMUM), and never below the $0.50 card floor at any date (the same code, with min_usd: "0.50" and no enforced_from; /complete and create-intent refuse it the same way). Until 2026-10-27 a smaller card session is created and the 201 also carries min_purchase_warning: { "code": "BELOW_CARD_MINIMUM", "min_usd": "2.99", "enforced_from": "2026-10-27", "message": "..." }. In sandbox the checkout_url host is sandbox.invo.network (the page is at /checkout, no /sandbox prefix); validate that origin in your iframe postMessage listener.

"warnings": [{
  "code":    "ITEM_METADATA_ON_CURRENCY_SESSION",
  "message": "This checkout session sells game currency: the buyer receives coins, and metadata item_id is only echoed back. To sell an item, use POST /api/platform-commerce/purchase.",
  "fields":  ["item_id"]
}]

2. Open the URL

• • WebView or full-page redirect (works everywhere): on success the page redirects to your success_url.
• • Embedded <iframe>: set iframe.src = checkout_url (any https site may frame the page). When embedded, the page does not redirect your top window; listen for the INVO_CHECKOUT_COMPLETE postMessage. You can ask INVO to restrict framing to your own origins.

// Web (WebGL build / browser)
const iframe = document.createElement('iframe');
iframe.src = checkoutUrl;
iframe.style.cssText = 'width:480px; height:720px; border:0;';
document.body.appendChild(iframe);

// Mobile (Unity, Unreal, native): open checkout_url in your WebView.

What the player sees before paying: Subtotal (your price), Tax and Total, plus the coins they will receive. No processing fee is added. For a $10.00 pack on the Open tier that is $10.00 + $0.00 tax = $10.00, for 100 coins. Your card fee on it is $0.50 (plus $0.15 if the card was issued outside the US).

3. Listen for completion

Browser postMessage (a UX hint only)

window.addEventListener('message', (event) => {
  if (event.data?.type === 'INVO_CHECKOUT_COMPLETE') {
    const { status, new_balance, currency_name, transaction_id } = event.data.data;
    if (status === 'completed') {   // the success value is 'completed', not 'success'
      updatePlayerBalance(new_balance);
    }
  }
});

On success, data.status is "completed" (not "success"). postMessage is not signed. Use it to refresh the balance optimistically. For your records, rely on the webhook or re-read the balance from the API.

Server-to-server webhook (authoritative)

POST <your_webhook_url>
Headers:
  X-Invo-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256>
  X-Invo-Event-Id:  <uuid>            # unique per delivery (same on retries, new on a replay)
  X-Invo-Idempotency-Key: <stable id> # dedupe on THIS

Body (a $10.00 pack bought on hosted checkout):
{
  "event_id":   "evt_01HX...",
  "event_type": "purchase.completed",
  "created_at": "2026-09-23T12:34:56Z",
  "tenant_id":  "<your game_id>",
  "data": {
    "transaction_id":   "txn_...",
    "order_id":         "ord_...",
    "player_email":     "player@example.com",
    "identity_id":      "f3a1b8c0d4e5...",
    "usd_amount":       "10.00",       // on hosted checkout: the amount charged
    "currency_amount":  "100",         // coins credited, priced from the $10.00 list price
    "currency_name":    "Gold Coins",
    "charge_total_usd": "10.00",       // what the card was charged, tax included
    "subtotal_usd":     "10.00",       // that total less tax
    "partner_fee_usd":  "0.50",        // the card fee charged to you
    "international_card_fee_usd": "0.00",  // the extra 1.5% on a card issued outside the US
    "tax_usd":          "0.00",
    "tax_jurisdiction": null,
    "tax_rate_pct":     null,
    "tax_treatment":    "partner_responsible",   // Open tier: you are the seller
    "metadata":         { "your_user_id": "u_42", "coin_pack": "starter" }
  }
}

Grant nothing extra on this event: the coins are already in the player's balance. Reconcile a card statement against charge_total_usd. usd_amount keeps the meaning it has always had on each route (the charged amount on hosted checkout, the amount you sent on the direct route), so read charge_total_usd when you want the charge.partner_fee_usd is the card fee charged to you for this purchase and international_card_fee_usd the extra fee when the card was issued outside the US ("0.00" otherwise). Both are additive; read them rather than recomputing. If you need your list price back, put your pack id in metadata. Verify the HMAC-SHA256 signature with your webhook signing secret, dedupe on X-Invo-Idempotency-Key (not X-Invo-Event-Id, which changes on a replay), and reject timestamps older than 5 minutes.

tax_treatment reads "partner_responsible" on the Open tier: your business is the seller and INVO charged no tax, so tax_usd is 0.00 and tax_rate_pct is null. tax_jurisdiction carries the buyer's place when it is known and is null otherwise. On the Merchant of Record tier it says how INVO handled the tax (for example "collected"), and the event also carries receipt_number and receipt_url for the receipt INVO issued to the buyer. Those two keys are absent on every other sale. See Tiers.

4. Ask what happened to the purchase

A buyer must always be able to find out what happened to money they paid. Poll this read from the moment the payment step hands back control, and keep your modal open until it says the purchase is finished.

GET https://invo.network/api/checkout/sessions/<session_id>
Headers:
  Authorization: Bearer <the session JWT>

Response 200 (a $200.00 pack):
{
  "status":             "credited",
  "terminal":           true,
  "order_id":           "ORD_1758000000_ABCD1234",
  "session_id":         "<jti>",
  "coins_credited":     "2000.00",
  "transaction_id":     "TXN_...",
  "new_balance":        "12000.00",
  "reason_code":        null,
  "message":            null,
  "amount_charged_usd": "200.00",
  "listed_usd":         "200.00",
  "currency_name":      "Credits"
}

listed_usd is your price. amount_charged_usd is what the player is billed: the price plus any tax, which is zero on the Open tier. No card fee is added; the $7.15 card fee on this pack is charged to you. The 2,000 coins come from the listed price. Before any payment exists, amount_charged_usd is what this checkout will charge. On a Merchant of Record account, a credited read also carries receipt_number and receipt_url once INVO has issued the buyer's receipt.

The id in the path is not a credential; the session token is. Send it in the Authorization header so it never lands in an access log. X-Checkout-Session-Token and a JSON body { "token": "..." } are accepted as alternatives. In sandbox: https://sandbox.invo.network/sandbox/api/checkout/sessions/<session_id>. A token for a different session is 403 SESSION_MISMATCH; a card-saving token is 401 WRONG_SESSION_PURPOSE; a token that expired within the last 24 hours still answers, past that it is 410 SESSION_EXPIRED. Rate limit: 600 requests per minute per IP.

The six statuses

status is a closed set.

The reason codes

On PAYMENT_DECLINED and PAYMENT_CANCELLED nothing was charged, so offer Try again beside Contact support. On the others, do not: a second charge is the last thing the buyer needs. Treat an unrecognised code as a generic refusal and still render message.

Where your logo appears

A small Secured by INVO line stays at the bottom of every checkout page, with or without your logo, because INVO processes the payment. Your logo's alt text is your game's name, and with a custom logo the checkout tab is titled Checkout · <your game name>. If the image cannot load, the page shows the INVO logo instead.

Image requirements

• • PNG, JPEG or WebP, up to 1 MB (1,000,000 bytes). SVG and GIF are not accepted.
• • Recommended: a transparent, wide PNG, about 4:1, for example 640 x 160 px.
• • It is shown at up to 40 px tall and 200 px wide, scaled to fit and never cropped, so the payment form always stays on the first screen.

1. Quote the total

Moves no money and creates nothing, so it is safe to call on every price render (300 requests per hour per player email). Same authentication as the purchase call.

POST https://invo.network/api/currency-purchases/quote
Headers:
  X-Game-Secret-Key: ivsdk_<your_sdk_key>
  Content-Type: application/json

Body:
{
  "player_email": "player@example.com",
  "usd_amount":   "10.00",     // your list price
  "country":      "US",        // optional: buyer's billing country, ISO 3166-1 alpha-2
  "subdivision":  "CA"         // optional: US state or Canadian province
}

Response 200:
{
  "total_usd":          "10.00",    // listed price + tax: show this, then send it back
  "amount_cents":       1000,
  "subtotal_usd":       "10.00",
  "processing_fee_usd": "0.00",     // the player pays no card fee
  "partner_fee_usd":    "0.50",     // the card fee you will be charged (Open, $10.00)
  "international_card_fee_usd": null,  // always null on a quote: no card is known yet
  "fee_taken_from":     "partner",
  "coins":              "100.00",
  "currency_name":      "Gold Coins",
  "breakdown": {
    "subtotal_usd": "10.00", "tax_usd": "0.00", "tax_rate_pct": null,
    "tax_jurisdiction": null, "tax_treatment": "partner_responsible",
    "tax_note": "No tax is charged on this purchase.",
    "processing_fee_usd": "0.00", "processing_fee_note": "",
    "total_usd": "10.00", "coins": "100.00", "currency_name": "Gold Coins"
  },
  "if_unacknowledged": {            // what happens if you skip step 3's acknowledgement
    "charge_total_usd":   "10.00",
    "processing_fee_usd": "0.00",
    "coins":              "100.00",
    "fee_taken_from":     "partner",
    "partner_fee_usd":    "0.50"
  }
}

total_usd is both the figure to display and the figure to send back. The breakdown gives you each line for your own price screen. processing_fee_usd reads "0.00": the player pays no card fee, and the card fee is charged to you, previewed as partner_fee_usd. international_card_fee_usd is always null on a quote, because the card is not known yet; the purchase response carries the figure. An amount of zero or above the card maximum is 400 INVALID_INPUT. Below the minimum card purchase, the quote carries min_purchase_warning until 2026-10-27 and is refused with 400 BELOW_CARD_MINIMUM from then on. The example is an Open-tier account, where tax_treatment is "partner_responsible" and no tax is added; on Merchant of Record tax on the listed price is added where INVO is registered, so total_usd can be higher than the price.

2. Show the player the total

Put total_usd on your confirm screen, with the tax as its own line where there is any ("$10.00 + $0.80 tax = $10.80"). This is the number the player agrees to. There is no processing fee line to show.

3. Purchase, acknowledging the total

POST https://invo.network/api/currency-purchases/purchase-currency
Headers:
  X-Game-Secret-Key: ivsdk_<your_sdk_key>
  Content-Type: application/json

Body:
{
  "player_email":           "player@example.com",
  "usd_amount":             "10.00",     // the same list price you quoted
  "acknowledged_total_usd": "10.00",     // total_usd from /quote
  "payment_method_id":      "<tokenised_card_id_from_your_card_collector>",
  "purchase_reference":     "<uuid_v4>", // REQUIRED, see Idempotency below
  "country":                "US",        // optional: the country you quoted with
  "subdivision":            "CA",        // optional: the state or province you quoted with
  "metadata":               { "your_user_id": "u_42" }
}

Response 200:
{
  "status":             "success",
  "transaction_id":     "txn_...",
  "order_id":           "ORD_...",
  "new_balance":        "100.00",
  "previous_balance":   "0.00",
  "currency_name":      "Gold Coins",
  "charge_total_usd":   "10.00",     // what the card was charged
  "processing_fee_usd": "0.00",      // the player paid no card fee
  "partner_fee_usd":    "0.50",      // the card fee charged to you
  "international_card_fee_usd": "0.00",
  "fee_taken_from":     "partner",   // the fee is charged to you, not the player
  "coins_credited":     "100.00",
  "exchange_rate":      "...",
  "purchase_details":   { "usd_charged": "10.00", "currency_received": "100.00", ... },
  ...
}

The card is charged the price (+ tax where applicable), never more than the total you acknowledged, and the player gets every coin you listed. Branch on status: requires_action is a normal 3-D Secure step, not a failure (see below).

Send the place you quoted with. country and subdivision are optional and take the same values you sent to /quote. On Merchant of Record, INVO uses them only when it cannot read the buyer's tax location from the card, so a buyer who was shown tax is charged it. Without them, such a purchase is refused with 409 TAX_PLACE_UNAVAILABLE and nothing is charged (see the errors below). On Open they change nothing.

If you do not acknowledge a total, or acknowledge an older one

Leave out acknowledged_total_usd and the card is charged exactly the usd_amount you send, never more, and the player gets every coin you listed. No tax is collected on an unacknowledged purchase.

An integration built when the player paid the card fee may still send the older, higher total that included the fee. That is accepted: the player is charged the current, lower total, and never more than the figure you acknowledged. Only an acknowledged total below the total INVO would charge is refused (QUOTE_STALE). In every case the card fee is charged to you.

Coins are shown at the default 10 per dollar. Add $0.15 to your card fee when the card was issued outside the US.

Errors specific to the total and the minimum

AMOUNT_BELOW_FEE is no longer returned: the card fee is not part of the player's charge, so no amount is too small to cover it. Keep handling it if your code already does; it is harmless.

Other responses from /purchase-currency

200, status:"success"                 purchase complete
200, status:"requires_action"         3-D Secure needed, see below
200, status:"success", duplicate:true replay of a completed purchase_reference
409, status:"pending", duplicate:true purchase already in flight for this purchase_reference
400, error_code:"MISSING_PURCHASE_REFERENCE"
400, error_code:"INVALID_PURCHASE_REFERENCE"   (over 255 characters)
400, error_code:"INVALID_SAVE_CARD"            (save_card is not a JSON boolean)
429, error:"spending_limit_exceeded"

Never treat a non-success response as a decline. Raw card fields are not accepted: tokenise the card client-side and send payment_method_id.