CosmosPay Integration
Use the public @cosmosapp/pay_sdk package. Keep the CosmosPay API key on the server and complete wallet approval in the browser.
Choose the flow
| Need | Read |
|---|---|
| Create and settle a Stellar checkout | references/payments.md |
| Connect Cosmos Wallet or another browser wallet | references/wallets.md |
| Use swaps, liquidity, ramps, KYC, or other managers | references/operations.md |
Install
npm install @cosmosapp/pay_sdk
Install @stellar/stellar-sdk beside it when the browser must build or submit a transaction:
npm install @cosmosapp/pay_sdk @stellar/stellar-sdk
Apply the security boundary
- Instantiate
Clientonly on the server withCOSMOS_PAY_API_KEY. - Send payment-intent payloads, never the API key, to the browser.
- Let a wallet display and approve the transaction before signing.
- Validate the resulting transaction hash on the server.
- Fulfil an order from a verified webhook or server-side validation result, never from a browser success message alone.
- Match assets by code and issuer. Use the package's network-specific asset constants.
- Treat all amounts as decimal strings with no more than seven fractional digits.
Verify before finishing
- Exercise the flow on testnet with a
dv_key. - Confirm that the connected wallet and intent use the same network.
- Confirm the rendered destination, asset, amount, memo, and fee.
- Reject a mismatched transaction during server-side validation.
- Verify webhook signatures and deduplicate stable event IDs.
- Run the consuming application's typecheck and tests.
Use the package documentation under node_modules/@cosmosapp/pay_sdk/llms/ as the version-matched source of truth when an API shape differs from this skill.