Cómo aceptar USDC en Stellar con enlaces SEP-7
Con Cosmos Pay, un enlace de pago en Stellar es una solicitud SEP-7: tu cliente escanea su código QR o lo abre en una wallet como Freighter, LOBSTR o xBull y aprueba ahí el pago en USDC. Los USDC van directo a tu cuenta de Stellar, y Cosmos Pay marca el enlace como pagado cuando encuentra el pago por el memo del enlace. Para recibirlos, tu cuenta ya debe tener una trustline hacia USDC.
Qué contiene un enlace SEP-7
SEP-7 es el estándar de Stellar para solicitudes de pago: un enlace web+stellar:pay, o su código QR, con tu dirección, el monto, el activo y su emisor, y un memo numérico.
Cosmos Pay crea un memo para cada enlace y lo busca entre los pagos que recibe tu cuenta. Acepta un pago con ese memo, a tu dirección, en el activo del enlace y, cuando el enlace fija un monto, por exactamente ese monto, hecho después de que se creó el enlace.
Prepara tu cuenta
- Tu cuenta de Stellar debe existir en la red y tener una trustline hacia USDC antes de poder recibirlo. Cosmos Pay no lo comprueba cuando agregas la cuenta, y un pago a una cuenta sin la trustline falla después de que tu cliente firma.
- Agrega la cuenta a tu organización en el dashboard y firma lo que te pide: así demuestras que la cuenta es tuya.
- Para las pruebas, haz lo mismo en Testnet. Friendbot, el faucet de Testnet, envía XLM de prueba a una cuenta, y ahí los enlaces pueden cobrar en XLM.
Qué necesita tu cliente
- Una wallet de Stellar que abra enlaces SEP-7, como Cosmos Pay Wallet, Freighter, LOBSTR, xBull, Albedo o Rabet, con los USDC y algo de XLM para la comisión de red. No necesita una cuenta en Cosmos Pay.
- Un pago directo en USDC. Una wallet que convierte otro activo en USDC por el camino (un path payment) no liquida el enlace.
- En Testnet, la wallet configurada en Testnet antes de pagar: el enlace no indica la red, y una wallet que sigue SEP-7 asume entonces la principal.
Acepta tu primer pago en USDC en Stellar
Cambia a Sandbox
Inicia sesión en el dashboard y elige Sandbox en la parte superior. Los enlaces que crees ahí funcionan en Stellar Testnet y no mueven dinero real.
Agrega tu cuenta de Stellar
Asegúrate de que la cuenta exista y tenga una trustline hacia USDC, luego agrégala en los ajustes de tu organización y firma lo que te pide el dashboard.
Crea el enlace
En Pagos, elige Crear enlace de pago, selecciona Stellar, el monto (o ninguno) y USDC, y luego tu cuenta y, si quieres, un mensaje.
Págalo desde una wallet
Abre la página de pago y escanea su código QR con una wallet de Stellar configurada en la misma red, o abre el enlace en el mismo dispositivo. Aprueba el pago, y el checkout pasa a Pagado cuando Cosmos Pay lo encuentra.
Confírmalo en tu servidor
Agrega un endpoint de webhook en el dashboard. Cuando el pago se confirma, Cosmos Pay envía PAYMENT_INTENT_SUCCEEDED, firmado con HMAC-SHA256. Entrega el pedido cuando llegue ese evento.
Cambia a Producción
Elige Producción y crea una clave de API de producción (empieza con prod_). Los enlaces ahora funcionan en la red principal de Stellar, donde el USDC de Circle es la opción predefinida.
Crea el enlace desde tu servidor
Llama a POST /v1/payment-intents/pay con tu cuenta como destino, el monto y, para USDC, el código de activo con su emisor, o usa client.paymentIntents.createPay en el SDK de TypeScript: Stellar es el valor por defecto de chain. La respuesta trae el enlace (su uri empieza con web+stellar:pay) y su código QR.
Cuando conoces la cuenta de tu cliente, un intento de transacción (POST /v1/payment-intents/tx, o createTx en el SDK) devuelve en cambio una transacción sin firmar para que la firme. Debe firmarse en un plazo de cinco minutos.
Si defines tu propio memo, úsalo para un solo pago: el mismo memo con condiciones distintas se rechaza.
Para tener en cuenta
- Puedes dejar el monto vacío para que tu cliente lo elija. Un mensaje de hasta 300 caracteres se muestra en la wallet de tu cliente.
- Con tu propia comisión en el pago, el checkout le pide a tu cliente su cuenta y construye una sola transacción que te paga a ti y a tu wallet de comisiones.
- En el dashboard, un enlace de Stellar pendiente tiene una verificación que lo liquida a partir del hash de una transacción.
- Un pago que llega después de que venció el enlace se liquida enviando el hash de su transacción a POST /v1/payment-intents/:id/validate.
- La wallet de tu cliente cubre la comisión de red de Stellar, en XLM. Los pagos privados, que ocultan el monto en la cadena, funcionan en Stellar en XLM, por ahora en Testnet.
Precios y calculadora de comisionesStellar vs Solana vs Monad
¿Por qué falló un pago a mi cuenta?
La causa más común es que a la cuenta que recibe le falta la trustline de USDC. Agrega la trustline, luego crea un enlace nuevo y vuelve a enviarlo.
¿Qué wallets pueden pagar un enlace SEP-7?
Cualquier wallet de Stellar que abra enlaces SEP-7, como Cosmos Pay Wallet, Freighter, LOBSTR, xBull, Albedo o Rabet.
¿Mi cliente puede pagar un enlace en USDC con XLM?
No. Solo lo liquida un pago directo en USDC: un pago que convierte XLM en USDC por el camino no lo liquida.
¿Puedo probar sin dinero real?
Sí. En Sandbox y con claves de prueba (dv_), los enlaces funcionan en Stellar Testnet, donde USDC está predefinido y Friendbot envía XLM de prueba.
