# Overview (https://dev.cosmospay.lat/docs/sdk/server/overview/)

> What the SDK is, its server and browser entry points, the three-step payment flow, and the key facts you must know.

This is the mental model for the whole SDK, so read it first. It explains why there are two entry points (server and browser) and how a single payment moves through three steps.

`@cosmosapp/pay_sdk` is the object-oriented JavaScript/TypeScript SDK for the
**Cosmos Pay** Payments API — Stellar **SEP-7 payment intents**, **webhooks**,
**products**, **customers** and **analytics**.

## Two entry points

| Import | Runs in | Purpose |
| ------ | ------- | ------- |
| `@cosmosapp/pay_sdk` | server (Node ≥ 18) | Create & manage intents, webhooks, products, customers, analytics — anything that needs your secret API key. |
| `@cosmosapp/pay_sdk/web` | browser | *Complete* an intent: auto-detect the user's Stellar wallet (Freighter, xBull, Rabet, LOBSTR, Albedo), build the transaction, sign and submit. Provider-agnostic. |

## Mental model

A payment has two halves:

1. **Server** creates an intent with your secret key (`client.paymentIntents.createPay`/`createTx`)
   and returns the payload (`uri`, `qr`, and for `tx` intents an unsigned `xdr`) to your frontend.
2. **Browser** completes it with the user's wallet (`new WebClient().pay(intent)`),
   producing an on-chain `txHash`.
3. **Server** finalizes by validating that hash (`intent.validate(txHash)`), which
   updates the status and fires a webhook.

## Design

- **Atomic** — one `Client`; one manager per resource (`client.paymentIntents`,
  `client.webhooks`, `client.products`, `client.customers`, `client.analytics`,
  `client.health`).
- **Self-acting structures** — returned objects act on themselves:
  `intent.validate()`, `endpoint.rotateSecret()`, `product.deactivate()`.
- **Zero runtime dependencies** — native `fetch` + `node:crypto`. The Stellar SDK
  is an *optional* peer dep, only needed by the browser web client.
- **Fully typed** — works in both CJS and ESM.

## Key facts for correct integration

- The **network is chosen by the API key type**: `dv_` → testnet, `prod_` → mainnet.
  You never pass a network on the server.
- **Amounts are decimal strings** (e.g. `'10'`, `'120.1234567'`), max 7 decimals.
- The **webhook secret (`whsec_…`) is shown only once** on `create`/`rotateSecret`.
- The **gateway URL is pre-configured**; a normal integration only sets `apiKey`.
- Default gateway: `https://api.cosmospay.lat/cosmos-api`. Requires Node ≥ 18.

## References

- [Client](https://dev.cosmospay.lat/docs/sdk/definitions/server/client/): The main entry point of the SDK — a single, atomic client that exposes every resource through its own manager — an atomic, single-client design.
- [WebClient](https://dev.cosmospay.lat/docs/sdk/definitions/web/web-client/): The browser wallet client that detects the user's Stellar wallet, then builds, signs and submits the transaction
