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, Solana and Monad 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)
@cosmosapp/pay_sdk: a typed JavaScript/TypeScript client that handles auth, requests and wallet signing for you.
Call the REST API directly
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):
- Your server creates an intent with your secret API key, e.g.
client.paymentIntents.createPay({ ... }). You get back a SEP-7uriand aqrto show the payer. - 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-chaintxHash. - 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:
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
- Get an API key: sign in to the developer platform and mint one. See Get your API key.
- Install the SDK:
npm install @cosmosapp/pay_sdk(Node.js ≥ 18). See Installation. - Keep the key on your server. It's a secret; the browser web client never needs it.
Your first payment
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>