# Getting started (https://dev.cosmospay.lat/docs/getting-started/)

> Everything you need before your first Cosmos Pay payment, including what it is, how a payment flows, and the two ways to integrate.

**Cosmos Pay** lets you accept payments on [Stellar](https://stellar.org),
[Solana](https://solana.com) and [Monad](https://monad.xyz) using **payment intents**: you
describe a payment, the payer completes it from their own wallet, and you confirm it on-chain.
Around that core you also get **swaps** (on each chain and between them), **webhooks**,
**products**, **customers** and **analytics**.

There are two ways to integrate, and most apps use both together:

- [Use the SDK (recommended)](https://dev.cosmospay.lat/docs/sdk/server/overview/): @cosmosapp/pay_sdk: a typed JavaScript/TypeScript client that handles auth, requests and wallet signing for you.
- [Call the REST API directly](https://dev.cosmospay.lat/docs/api/): The Payments REST API (OpenAPI) if you're not on JavaScript or want full control over requests.

## How a payment works

Every payment moves through the same three steps (shown here with the SDK, on Stellar):

1. **Your server creates an intent** with your secret API key, e.g. `client.paymentIntents.createPay({ ... })`. You get back a SEP-7 `uri` and a `qr` to show the payer.
2. **The payer completes it** in their Stellar wallet (Freighter, xBull, Rabet, LOBSTR or Albedo). In the browser this is one call: `new WebClient().pay(intent)`, which returns an on-chain `txHash`.
3. **Your server validates** that hash with `intent.validate(txHash)`, which updates the payment's status and fires a webhook to your endpoints.

On Solana and Monad, pass `chain`, with the SDK (`createPay({ chain: 'solana', ... })`, from version 2.2) or the [REST API](https://dev.cosmospay.lat/docs/api/payment-intents/):
you get a Solana Pay or EIP-681 link instead of a SEP-7 one, the payer pays it from any wallet on
that chain, and the Payments API detects the payment on-chain and fires the same webhooks.

> **Testnet vs mainnet**
>
> You never choose the network in code; it's decided by your **API key prefix**: `dv_` keys run
> on **testnet**, `prod_` keys run on **mainnet**. Develop with a `dv_` key, then swap in a
> `prod_` key to go live.

## Before you start

1. **Get an API key**: sign in to the developer platform and mint one. See [Get your API key](https://dev.cosmospay.lat/docs/api-keys/).
2. **Install the SDK**: `npm install @cosmosapp/pay_sdk` (Node.js ≥ 18). See [Installation](https://dev.cosmospay.lat/docs/sdk/server/installation/).
3. **Keep the key on your server.** It's a secret; the browser web client never needs it.

## Your first payment

```ts
import { Client, Assets } from '@cosmosapp/pay_sdk';

const client = new Client({ apiKey: process.env.COSMOS_PAY_API_KEY });

const intent = await client.paymentIntents.createPay({
  destination: 'G...YOUR_MERCHANT_ACCOUNT',
  amount: '10',
  asset: Assets.XLM,
  msg: 'Order #1001',
});

console.log(intent.uri); // show as a link / button
console.log(intent.qr);  // render this data: URL as an <img>
```

## Next steps

- [Get your API key](https://dev.cosmospay.lat/docs/api-keys/): Sign in, choose an environment, and mint a key in the dashboard.
- [Quickstart](https://dev.cosmospay.lat/docs/sdk/server/quickstart/): The full server-creates / browser-completes example.
- [Webhooks](https://dev.cosmospay.lat/docs/sdk/server/webhooks/): Get notified the moment a payment succeeds.
- [API reference](https://dev.cosmospay.lat/docs/api/): Every endpoint, with schemas and a request playground.
