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:

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: 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.
  2. Install the SDK: npm install @cosmosapp/pay_sdk (Node.js ≥ 18). See Installation.
  3. 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>

Next steps

On this page