Invalid return URL — missing session_id.
;\r\n\r\n return (\r\n{error}
}\r\n \r\n \r\n );\r\n}\r\n```\r\n\r\n**`useStripeReturn`** — poll payment status and render your own UI:\r\n\r\n```tsx\r\nimport { useStripeReturn } from '@0gfoundation/0g-pay-sdk';\r\n\r\nfunction MyReturnPage({ sessionId, sessionToken }) {\r\n const { status, creditedMicros, availableMicrosAfter } = useStripeReturn(sessionId, {\r\n network: 'testnet',\r\n sessionToken,\r\n });\r\n\r\n if (status === 'loading') returnPayment received — balance updating soon.
;\r\n\r\n const creditedUsd = creditedMicros / 1_000_000;\r\n return✓ ${creditedUsd.toFixed(2)} credited to your account.
;\r\n}\r\n```\r\n\r\n---\r\n\r\n## Stripe Client (Node.js / server-side)\r\n\r\n`StripeClient` is a headless client with no React or browser dependencies. Use it in Node.js servers, serverless functions, scripts, or any environment where you need to drive the 0G Pay API programmatically.\r\n\r\nRequires **Node.js 18+** (native `fetch` and `AbortSignal.timeout`).\r\n\r\n### Import\r\n\r\n```ts\r\n// In a React project (react already installed):\r\nimport { StripeClient } from '@0gfoundation/0g-pay-sdk';\r\n\r\n// In a pure Node.js project (no React needed):\r\nimport { StripeClient } from '@0gfoundation/0g-pay-sdk/server';\r\n```\r\n\r\n### Setup\r\n\r\n```ts\r\nconst client = new StripeClient({\r\n network: 'testnet', // 'testnet' | 'mainnet' — defaults to 'testnet'\r\n sessionToken: '...', // session token from exchangeSession()\r\n});\r\n```\r\n\r\nUse `baseUrl` to point at your own proxy or a host other than the two network defaults:\r\n\r\n```ts\r\nconst client = new StripeClient({\r\n baseUrl: 'https://your-pay-backend.example.com', // overrides network\r\n sessionToken: '...',\r\n});\r\n```\r\n\r\n### Exchange session token\r\n\r\nExchange a Privy access token for a 0G Pay session token. The returned `token` is used as `sessionToken` for all other methods.\r\n\r\n```ts\r\nconst { token, account_id } = await client.exchangeSession(privyAccessToken);\r\n```\r\n\r\n### Get balance\r\n\r\n```ts\r\nconst { available_micros } = await client.getBalance();\r\nconst usd = available_micros / 1_000_000;\r\n```\r\n\r\n### Create a checkout session\r\n\r\n```ts\r\nconst { session_id, url } = await client.createCheckoutSession({\r\n amountUsd: 50, // or use amountMicros: 50_000_000\r\n successUrl: 'https://yourapp.com/return',\r\n cancelUrl: 'https://yourapp.com/cancel',\r\n email: 'user@example.com', // optional — pre-fills Stripe checkout\r\n});\r\n// url is the Stripe hosted checkout page — redirect the user there\r\n```\r\n\r\n`amountUsd` and `amountMicros` are mutually exclusive; exactly one must be provided.\r\n\r\n### Poll payment status\r\n\r\n```ts\r\nimport { StripeClient, StripeAuthError, StripePollingTimeoutError } from '@0gfoundation/0g-pay-sdk/server';\r\n\r\ntry {\r\n const result = await client.pollCheckoutStatus(session_id, {\r\n maxAttempts: 6, // default 6\r\n intervalMs: 3_000, // default 3000 ms\r\n });\r\n if (result.paid) {\r\n console.log(`Credited $${result.credited_micros / 1_000_000}`);\r\n } else {\r\n // All attempts returned paid: false — payment not yet confirmed.\r\n // This is a normal result for reconcile calls (e.g. page load checks).\r\n }\r\n} catch (err) {\r\n if (err instanceof StripeAuthError) {\r\n // 401 or 403 — session token is invalid or expired. Refresh and retry.\r\n console.error(`Auth failed (${err.status}): ${err.message}`);\r\n } else if (err instanceof StripePollingTimeoutError) {\r\n // Never received a clean response in maxAttempts tries (network/server error).\r\n // err.cause holds the underlying error.\r\n console.warn(`No response after ${err.attempts} attempts`, err.cause);\r\n } else {\r\n throw err;\r\n }\r\n}\r\n```\r\n\r\n**Polling behaviour:**\r\n- Returns immediately when `paid: true`.\r\n- If all attempts return `paid: false`, resolves with the last status — not an error. This makes single-attempt reconcile calls (`maxAttempts: 1`) work naturally.\r\n- Throws `StripeAuthError` immediately on 401/403 — no retries.\r\n- Throws `StripePollingTimeoutError` (with `.cause`) only when no clean HTTP response was received at all.\r\n\r\n### List topup history\r\n\r\n```ts\r\nconst { topups, next_before } = await client.listTopups({ limit: 20 });\r\n// paginate: pass next_before as `before` on the next call\r\nconst page2 = await client.listTopups({ limit: 20, before: next_before });\r\n```\r\n\r\nPass `source` to filter by payment origin. This is important when checking whether a topup is a user's first real deposit — the backend may return credit-type rows before any Stripe or on-chain topup, causing a naïve \"first row\" check to misfire:\r\n\r\n```ts\r\n// Only stripe and on-chain topups — correct for \"is first topup\" checks\r\nconst { topups } = await client.listTopups({ limit: 1, source: 'stripe,chain' });\r\nconst isFirstTopup = topups.length === 0;\r\n```\r\n\r\n### Get usage\r\n\r\n```ts\r\nconst { items, cursor } = await client.getUsage({ limit: 50 });\r\nconst page2 = await client.getUsage({ limit: 50, cursor });\r\n```\r\n\r\n### Get credits\r\n\r\nLists the account's credit lots — promotional bonuses, staking rewards and team grants — in spend order (soonest expiry first).\r\n\r\nA page at a time, so walk it to the end before deriving any money figure from it:\r\n\r\n```ts\r\nconst LIMIT = 500; // the backend's ceiling\r\n\r\nconst MAX_PAGES = 20; // a bound, not an expectation\r\n\r\n// `extra` picks WHICH lots — leave it off to walk every lot, pass\r\n// { state: 'granted' } for only the spendable ones. It deliberately cannot\r\n// carry `limit` or `cursor`: the walk owns those, and a caller who lowered\r\n// `limit` would make the completeness test below read a full page as short.\r\nasync function walkCreditLots(\r\n extra: Pick![\"Pay\"](\"/pay-icon.svg\"){kind=icon}
\r\n