JAVASCRIPT SDKv0.3.20

Put payments in your game.

Use the same SDK in a browser, HTML5 game or host page. Keep purchase state stable while the service or wallet completes the request.

Install and load#

Browser SDKTerminal

npm install @playmos/sdk@0.3.20

Import Playmos from @playmos/sdk in your Vite, Phaser or other bundled app. The SDK uses viem; load it separately from the game where that improves first load on mobile. Never import @playmos/sdk/server in this bundle.

Wire the buy button#

Add the page elements and wire them to the helper:

Payment controlsHTML

<button id="buy">Buy an extra life · 0.01 test USDC</button>
<pre id="payment-status" aria-live="polite"></pre>

Save the helper as purchase.ts and import it into the page module. The example binds an existing button and output element. The purchase key is saved before the request, the button is disabled during submission, and a payment ID is retained even if server settlement times out.

Bind your page controlsTypeScript

import { bindSandboxPurchase } from './purchase';
 
const button = document.querySelector<HTMLButtonElement>('#buy')!;
const output = document.querySelector<HTMLElement>('#payment-status')!;
bindSandboxPurchase(button, output);

Make pending and recovery visible#

Show a pending state while the request runs. A timeout may contain error.detail.paymentId; keep it and call verify(id). Retry the same purchase with the original key if no ID was returned. Start a new key only for an intentional new purchase.

Choose the player experience#

The public sandbox’s settle: 'server' path uses test funds and does not ask the player to connect a wallet. For a wallet-funded payment, provide the host’s EIP-1193 provider and follow wallet and gas configuration. Server settlement is not a production wallet substitute.

Keep the grant on your backend#

The output is a display of the receipt. Send its ID to your backend, match your stored purchase and verify it under your studio before granting once. An iframe message, local receipt or disabled button is not an authorization boundary.

Use the playground to inspect actual SDK responses before wiring your game. The current portal iframe stage does not provide this payment bridge automatically.

Keep buildingYour first payment

import { Playmos } from '@playmos/sdk';
export function bindSandboxPurchase(button: HTMLButtonElement, output: HTMLElement) {
const client = new Playmos({ apiKey: 'pk_test_playmos_sandbox', settle: 'server' });
const storageKey = 'playmos-demo-purchase';
button.onclick = async () => {
button.disabled = true;
const key = sessionStorage.getItem(storageKey) || crypto.randomUUID();
sessionStorage.setItem(storageKey, key); // Persist BEFORE sending.
try {
const payment = await client.pay({
gameId: 'game_sandbox_iap', amount: '0.01',
sku: 'extra-life', playerId: 'sandbox-player', idempotencyKey: key,
});
sessionStorage.setItem(`${storageKey}:id`, payment.id);
const receipt = await client.verify(payment.id);
output.textContent = JSON.stringify(receipt, null, 2);
// Display only. Your backend owns verification and a single item grant.
} catch (error) {
const id = (error as { detail?: { paymentId?: unknown } }).detail?.paymentId;
if (typeof id === 'string') sessionStorage.setItem(`${storageKey}:id`, id);
output.textContent = error instanceof Error ? error.message : 'Request failed.';
// Once an ID exists, recover with client.verify(id), not another purchase.
} finally { button.disabled = false; }
};
// Reset the saved key and ID only when intentionally starting a NEW purchase.
}