Limva Documentation

Quickstart

Your game server creates a checkout session with your API key. The response contains a pay_url — send the player there, or open the widget with the session id. Anything you pass in metadata (player id, order id) comes back in the webhook, so your backend knows exactly what to credit.

curl -X POST https://api.limva.io/sessions \
  -H "Authorization: Bearer lk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1.00",
    "item": "10 Gems",
    "metadata": { "player_id": "p_123", "order_id": "ord_1" }
  }'

{
  "session_id": "sess_9f2ab8c1d4e5f607",
  "status": "pending",
  "amount": "1.00",
  "asset": "USDC",
  "pay_url": "https://pay.limva.io/?session=sess_9f2ab8c1d4e5f607"
}

Widget

One script tag turns the hosted checkout into a bottom sheet on mobile and a modal on desktop — the game page never reloads.

onCheckoutClosed is the only client callback, and it fires once when the sheet closes. Its paid flag is a UI hint, not authorisation — a client event can be forged by intercepting traffic. Grant items on your server, from the signed webhook, and only there.

<script src="https://pay.limva.io/limva.js"></script>
<script>
  Limva.open({
    sessionId: "sess_9f2ab8c1d4e5f607",
 
    // Fires once, when the sheet closes. UI only:
    // { sessionId, paid } is a hint, not authorisation.
    // Grant items server-side from the signed webhook.
    onCheckoutClosed: ({ paid }) => ui.refreshBalance(),
  });
</script>

Webhooks

After the payment settles on the network, Limva calls your webhook URL with a payment.completed event. The body is signed with your webhook secret (HMAC-SHA256 in the X-Limva-Signature header) and delivery retries automatically. Credit items only after the signature check, once per session_id.

{
  "type": "payment.completed",
  "session_id": "sess_9f2ab8c1d4e5f607",
  "status": "paid",
  "item": "10 Gems",
  "amount": "1.00",
  "asset": "USDC",
  "tx_hash": "0x91c9ca9b13e5ee3a…",
  "metadata": { "player_id": "p_123", "order_id": "ord_1" }
}

import hashlib, hmac
 
expected = "sha256=" + hmac.new(
    webhook_secret, raw_body, hashlib.sha256
).hexdigest()
 
assert hmac.compare_digest(
    expected, headers["X-Limva-Signature"]
)

Sessions

A session is one purchase attempt: item, amount, payout configuration, and status. With an API key the payout split comes from your onboarding configuration — requests only carry the item, amount, and metadata (up to 1 KB). Status moves from pending to paid; the checkout page polls it, and your server can too.

curl https://api.limva.io/sessions/sess_9f2ab8c1d4e5f607
 
# status: "pending" -> "paid"