Resumen
Qué es el SDK, sus puntos de entrada de servidor y navegador, el flujo de pago de tres pasos, y los datos clave que debes conocer.
Este es el modelo mental de todo el SDK; léelo primero. Explica por qué hay dos puntos de entrada (servidor y navegador) y cómo un solo pago atraviesa tres pasos.
@cosmosapp/pay_sdk es el SDK orientado a objetos de JavaScript/TypeScript para la
API de pagos de Cosmos Pay: intenciones de pago SEP-7 de Stellar, webhooks,
productos, clientes y analíticas.
Dos puntos de entrada
| Importación | Se ejecuta en | Propósito |
|---|---|---|
@cosmosapp/pay_sdk | servidor (Node ≥ 18) | Crear y administrar intenciones, webhooks, productos, clientes, analíticas: todo lo que necesite tu clave de API secreta. |
@cosmosapp/pay_sdk/web | navegador | Completar una intención: autodetectar la billetera de Stellar del usuario (Freighter, xBull, Rabet, LOBSTR, Albedo), construir la transacción, firmar y enviar. Independiente del proveedor. |
Modelo mental
Un pago tiene dos mitades:
- El servidor crea una intención con tu clave secreta (
client.paymentIntents.createPay/createTx) y devuelve la carga útil (uri,qr, y para las intencionestxunxdrsin firmar) a tu frontend. - El navegador la completa con la billetera del usuario (
new WebClient().pay(intent)), produciendo untxHashen cadena. - El servidor finaliza validando ese hash (
intent.validate(txHash)), lo que actualiza el estado y dispara un webhook.
Diseño
- Atómico: un
Client; un administrador por recurso (client.paymentIntents,client.webhooks,client.products,client.customers,client.analytics,client.health). - Estructuras que actúan sobre sí mismas: los objetos devueltos actúan sobre sí mismos:
intent.validate(),endpoint.rotateSecret(),product.deactivate(). - Cero dependencias en tiempo de ejecución:
fetchnativo +node:crypto. El SDK de Stellar es una dependencia de par opcional, solo necesaria por el cliente web del navegador. - Totalmente tipado: funciona tanto en CJS como en ESM.
Datos clave para una integración correcta
- La red se elige según el tipo de clave de API:
dv_→ testnet,prod_→ mainnet. Nunca pasas una red en el servidor. - Los montos son cadenas decimales (p. ej.
'10','120.1234567'), máx. 7 decimales. - El secreto del webhook (
whsec_…) se muestra solo una vez encreate/rotateSecret. - La URL del gateway está preconfigurada; una integración normal solo establece
apiKey. - Gateway por defecto:
https://api.cosmospay.lat/cosmos-api. Requiere Node ≥ 18.
Referencias
LLMs e IA
Alimenta tu LLM o agente de programación con la documentación y el SDK de Cosmos Pay, con archivos llms.txt listos para usar, Markdown por página y "Abrir en ChatGPT/Claude".
Instalación
Instala @cosmosapp/pay_sdk, la dependencia de par opcional de Stellar y los estilos de importación ESM / CommonJS.