Make your first payment.

Install the SDK, make a test payment and inspect a real receipt. No wallet is needed for the public sandbox IAP path.

1. Install the SDK#

InstallTerminal

npm install @playmos/sdk@0.3.20

Examples target SDK 0.3.20. For Node, use a runtime supported by the package’s engines; Node 22 is supported. The browser entry is @playmos/sdk. Webhook verification uses the server-only entry.

2. Create a payment#

Save the complete example as t0.mjs in your project. It saves a purchase key before calling pay(). The public sandbox key and settle: 'server' use the service’s Base Sepolia test signer.

Run the first paymentTerminal

node t0.mjs

The runner keeps .playmos-demo-purchase.json. After a payment ID exists, running it again verifies that same ID. Keep this file for recovery; intentionally use a new purchase file only for a new purchase.

3. Inspect the receipt#

Check the payment ID, status, transaction hash and verification source. If verification remains pending or degraded, retry the read; do not create another purchase.

Run this example

4. Connect your backend#

Continue with payment verification and signed webhooks. Sandbox requests are bounded and rate limited. Real testnet IAP is capped at 1.00 test USDC per request; the playground defaults to 0.01.

Keep buildingPayments & verification

t0.mjs · runnable Node exampleJavaScript

import { Playmos } from '@playmos/sdk';
import { randomUUID } from 'node:crypto';
import { readFile, writeFile } from 'node:fs/promises';
import { pathToFileURL } from 'node:url';
 
// A local demo purchase file holds no API secrets. Keep it for recovery.
export async function firstPayment(
  client = new Playmos({ apiKey: 'pk_test_playmos_sandbox', settle: 'server' }),
  purchaseFile = '.playmos-demo-purchase.json',
) {
  const mode = client.config.mock ? 'offline' : 'sandbox';
  let purchase;
  try {
    purchase = JSON.parse(await readFile(purchaseFile, 'utf8'));
    if (!purchase || typeof purchase.key !== 'string' || purchase.mode !== mode) {
      throw new Error('Invalid purchase file or mismatched mode. Keep the original for recovery.');
    }
  } catch (error) {
    if (error.code !== 'ENOENT') throw error;
    purchase = { key: randomUUID(), mode };
    await writeFile(purchaseFile, JSON.stringify(purchase), { flag: 'wx', mode: 0o600 });
  }
 
  if (!purchase.paymentId) {
    try {
      const payment = await client.pay({
        gameId: 'game_sandbox_iap', amount: '0.01',
        sku: 'extra-life', playerId: 'sandbox-player',
        idempotencyKey: purchase.key, settleTimeoutMs: 45_000,
      });
      purchase.paymentId = payment.id;
    } catch (error) {
      const id = error.detail?.paymentId;
      if (typeof id !== 'string') throw error;
      purchase.paymentId = id; // The service created it before the timeout.
    }
    await writeFile(purchaseFile, JSON.stringify(purchase), { mode: 0o600 });
  }
 
  // Rerunning with a saved ID verifies it; it does not create another purchase.
  const receipt = await client.verify(purchase.paymentId);
  return { mode, receipt };
}
 
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  try {
    const result = await firstPayment();
    console.log(JSON.stringify(result, null, 2));
    if (result.receipt.status !== 'confirmed' || result.receipt.verifiedVia !== 'chain') {
      console.error('Not chain-confirmed. Keep the purchase file and run again to verify this ID.');
      process.exitCode = 1;
    }
    // Demo display only. Your studio backend verifies and grants once.
  } catch (error) {
    console.error(error.message);
    process.exitCode = 1;
  }
}

IN THIS GUIDE1. Install the SDK 2. Create a payment 3. Inspect the receipt 4. Connect your backend Try it in the playground