Cómo integrar stablecoins a tu producto vía API

Noviembre 2026 por Equipo Koywe

Para integrar stablecoins vía API, tu empresa completa la verificación (KYB) con el proveedor, prueba el flujo en un entorno de pruebas, conecta los endpoints de cotización, on-ramp y off-ramp, y escucha webhooks para conciliar cada operación. En LATAM, la clave es que la API se conecte con los rieles de pago locales, como SPEI o Pix.

La oferta de stablecoins llegó a unos USD 308.000 millones a fines de 2025, según analistas de JPMorgan, liderada por USDT y USDC. Para un equipo de producto, la pregunta práctica es cómo integrarlas sin construir toda la infraestructura financiera.

Esta guía recorre los pasos, los endpoints y los puntos de cumplimiento de una integración con un proveedor regulado, con ejemplos de la documentación pública de la API de Koywe.

Si todavía estás comparando proveedores, empieza por las mejores APIs de pagos cripto en LATAM. Si quieres entender el concepto, lee qué es una API de pagos, y para el contexto general, qué son las stablecoins y cómo usarlas en tu empresa.

¿Qué necesita una fintech para integrar stablecoins vía API?

• Una cuenta como partner del proveedor. Según la documentación de Koywe, para conectarte por API te registras como partner y recibes dos parámetros: un Client Id y un Secret. Si solo necesitas on-ramp, existe además un widget que se integra sin credenciales.
• La verificación de tu empresa (KYB). Es el paso previo con cualquier proveedor regulado. Puedes ver qué piden en nuestra guía de qué es KYB.
• Un modelo de KYC para tus usuarios. Hay dos alternativas: haces tu propio KYC y compartes los datos por API, tras la revisión del equipo de compliance del proveedor, o usas el proceso del proveedor mediante una URL.
• Un backend que reciba webhooks y guarde el estado de cada orden.
• Decisiones de producto: países y monedas, token y red, y si el flujo es de entrada (on-ramp), de salida (off-ramp) o ambos.

¿Cuáles son los pasos de integración?

1. KYB y credenciales. Completas la verificación, te registras como partner y recibes tu Client Id y tu Secret.
2. Entorno de pruebas (sandbox). Creas usuarios de prueba, generas tokens JWT, pides cotizaciones ejecutables y creas órdenes. Hay limitaciones que conviene conocer: las transferencias bancarias no se pueden probar y se pide al soporte que simule una exitosa, mientras que otros medios de pago devuelven un link pagable; algunos tokens no existen en las redes de prueba, y los límites de monto son distintos a los de producción.
3. Flujo básico de endpoints. Autenticación, pares disponibles, cotización, orden y seguimiento (más abajo el detalle).
4. Webhooks. Configuras una URL para recibir los eventos de cada orden y validas su firma.
5. Producción. Empiezas con montos pequeños, monitoreas los estados y defines qué hace tu producto cuando una orden se rechaza o vence.

¿Qué endpoints mínimos necesitas?

El flujo básico de la API funciona igual para comprar (on-ramp) y para vender (off-ramp):

• POST /auth: te autentica con tu Client Id y tu Secret. Se recomienda incluir el correo del usuario para que el JWT quede asociado a él.
• GET /rest/currency-tokens y GET /rest/token-currencies: devuelven los pares disponibles para on-ramp y para off-ramp, para que los muestres a tu usuario.
• /payment-providers (on-ramp): lista los medios de pago disponibles por país y, en las transferencias, los datos para pagar.
• /bank-accounts (off-ramp): registra la cuenta bancaria donde se enviará el dinero. Es obligatorio antes de crear la orden.
• POST /quotes: calcula cuánto pagará y cuánto recibirá el usuario. Con un JWT y executable: true devuelve un quoteId, que dura 5 minutos.
• POST /orders: confirma la operación con el quoteId, la dirección de destino (una wallet o el id de la cuenta bancaria) y el número de documento del usuario. Devuelve un orderId, el detalle de pago (un link o los datos de transferencia) y la información para seguir el proceso.
• GET /orders/{orderId}: consulta el estado de una orden, como respaldo de los webhooks.

Un ejemplo de cotización, tomado de la documentación:

curl --location --request POST 'https://api.koywe.com/rest/quotes' \

--header 'Content-Type: application/json' \

--data-raw '{

"amountIn": 1000,

"symbolIn": "USDC Polygon",

"symbolOut": "CLP",

"executable": false

}'

Para un off-ramp, solo cambia el orden de los símbolos: en un on-ramp, symbolOut es un token; en un off-ramp, una moneda local.

¿Cómo se conecta con SPEI, Pix y otros rieles locales?

La API se encarga de conectarse con los sistemas de pago de cada país: tu producto solo elige el par de monedas y el medio de pago.

En un on-ramp, el usuario paga en su moneda con un medio local, y la API devuelve un link de pago, un código QR o los datos de la transferencia. Según la documentación, esos medios incluyen SPEI en México, Pix en Brasil, transferencias bancarias y Khipu en Chile, transferencias y códigos QR en Perú, transferencias en Argentina y códigos QR interoperables en Bolivia.

En un off-ramp, registras la cuenta bancaria de tu usuario y la API envía el dinero por las redes de transferencia locales del país.

La disponibilidad varía por país: Argentina, Brasil, Chile, Colombia, México y Perú tienen on-ramp y off-ramp; Bolivia, solo on-ramp; Estados Unidos, solo off-ramp. Cada país usa también su propio documento de identidad en el KYC, por ejemplo RUT en Chile, CURP o RFC en México, y DNI o CUIT en Argentina. Consulta la lista actualizada en la documentación de monedas y medios de pago.

En cuanto a tokens, la documentación indica que se soportan USDC y USDT en las redes principales, como Ethereum, Solana, Polygon, Base, Tron y Stellar, entre otras. Para elegir la red según tu caso, lee nuestra guía de redes blockchain para pagos.

¿Cómo se concilian las operaciones con webhooks?

Cada orden sigue un camino casi lineal: se crea, se paga y se entrega. Los estados posibles son:

• WAITING: la orden se creó y espera el pago
• PENDING: se pagó y está en cola de ejecución
• EXECUTING: se está enviando a la blockchain o al banco
• IN_PROGRESS: los fondos van en camino
• DELIVERED: los fondos se entregaron
• REJECTED: el usuario o el procesador rechazó la orden
• INVALID_WITHDRAWALS_DETAILS: solo en off-ramp; el banco rechazó la transferencia por datos incorrectos

Cada cambio dispara un evento a tu URL, como payment_received, crypto_delivered (on-ramp) o fiat_delivered (off-ramp). Para conciliar con orden:

• Guarda el orderId y asócialo a tu usuario. Si lo necesitas, usa también el campo metadata o un externalId propio para identificar la orden en tu sistema.
• Valida la firma. Si defines un secret, Koywe firma cada solicitud con un hash, que puedes verificar así:

const signature = crypto

.createHmac('sha256', secret)

.update(JSON.stringify(payload))

.digest('hex');

• Procesa cada evento una sola vez. Un evento puede llegar repetido, así que usa el orderId y el estado para no duplicar acreditaciones.

• Usa GET /orders/{orderId} como respaldo, por si un webhook no llegó.

Un detalle: según la documentación, en los off-ramps de Argentina el estado de la orden no pasa a entregado hasta que hayan transcurrido 4 días desde el depósito de las criptomonedas, aunque la operación suele ser efectiva de inmediato. Considera este plazo en tu conciliación.

¿Conviene construir in-house o integrar un proveedor regulado?

Construir in-house

• Tiempo: más largo, porque debes construir la conexión con rieles, custodia y monitoreo

• Licencias: tu empresa necesita las autorizaciones de cada país donde opere
• Custodia: gestionas tú las claves y la seguridad
• Rieles locales: debes integrarte con bancos y sistemas de pago de cada país
• Costo: inversión inicial y mantenimiento propios

Integrar un proveedor regulado

• Tiempo: menor, porque consumes una API ya conectada
• Licencias: parte de la carga regulatoria recae en el proveedor, aunque conviene validar tu caso
• Custodia: la gestiona el proveedor
• Rieles locales: ya están conectados
• Costo: costos por operación en lugar de una inversión inicial

Para ver el estado regulatorio de cada país, lee nuestra guía de regulación de criptoactivos en LATAM.

¿Qué riesgos y requisitos de cumplimiento hay?

• KYC y AML. Según la documentación de Koywe, el proveedor identifica al usuario, verifica que el dinero en moneda local salga de o llegue a una cuenta a su nombre, revisa que las wallets no estén en listas de sanciones y monitorea las transacciones. Puede rechazar operaciones si algo no cuadra, así que tu producto debe manejar ese caso.
• Red equivocada. Enviar un token por una red que no corresponde puede significar perder los fondos. Define las redes permitidas y valida la dirección antes de confirmar.
• Irreversibilidad. Una transferencia en blockchain no se revierte. En off-ramp, si el banco rechaza la transferencia por datos incorrectos, existe un flujo de corrección y de reembolso en cripto.
• Cotización vencida. La cotización dura 5 minutos: si el usuario tarda más, hay que generar una nueva.
• Datos del usuario. Los documentos de identidad y de cuenta deben coincidir con los del titular.

¿Cuánto tarda la integración?

El plazo depende de varios factores, y conviene confirmarlo con el equipo técnico del proveedor:

• El alcance: solo on-ramp con widget, o API completa con on-ramp y off-ramp
• El modelo de KYC: si usas el del proveedor o haces el tuyo
• Los países: cada país suma medios de pago, documentos y condiciones propias
• Tu interfaz: cuánto del flujo (cotización, pago, seguimiento) debes construir
• La conciliación: cómo procesas los webhooks y los casos de rechazo

Una forma ordenada de avanzar es empezar por un solo país y un solo sentido (por ejemplo, on-ramp), probarlo en sandbox y escalar de ahí.

Preguntas frecuentes

Para empezar, revisa la documentación de la API o conoce la infraestructura de stablecoins de Koywe. Si quieres conversar sobre tu caso, agenda una reunión con el equipo.