API de cobros USDC: integración BEP20 y Solana

2026-07-11 · Actualizado 2026-10-01 · UUGate · 3 min de lectura

USDC puede servir a productos digitales, suscripciones y membresías con usuarios de BSC o Solana. Identifica primero sus redes disponibles. El mismo nombre de activo no permite pagar en cualquier red.

Elige la red y el modelo

Se admiten BSC-USDC (BEP20) y SOL-USDC (SPL), con chainCode=BSC y SOL respectivamente. Configura una wallet compatible y muestra red, dirección e importe juntos. TRON-USDC y redes futuras no están admitidas.

Parámetros y pasos de integración

Para compras de importe fijo usa POST /openapi/payin/orders. Guarda merchantOrderNo, orderNo, address, cashierUrl y expireAt antes de abrir el checkout devuelto. Para recargas continuas puedes usar una vinculación exclusiva.

Este cuerpo es ilustrativo: no se envía una solicitud ni incluye datos reales. La llamada completa requiere UID, API Key, timestamp, nonce y firma en el servidor. Envía importes como cadenas y usa aritmética exacta para la contabilidad.

{
  "chainCode": "BSC",
  "tokenSymbol": "USDC",
  "merchantOrderNo": "DEMO_PRODUCT_001",
  "amount": "10.00",
  "notifyUrl": "https://merchant.example.com/payments/notify"
}

Estados, callbacks y excepciones

La espera y las confirmaciones no significan entrega completada. El éxito de cobro es completed. Compensa callbacks ausentes con GET /openapi/payin/orders/{orderNo}. Revisa pagos insuficientes, activos o redes incorrectos y transferencias tardías sin prometer recuperación entre cadenas.

Si crear un cobro vence por timeout y no tienes orderNo, comprueba la operación original en el panel. No supongas que merchantOrderNo garantiza reintentos idempotentes. Con orderNo, consulta esa orden de plataforma. La deduplicación de callbacks es distinta del reintento de creación.

Usa la API Key de la orden original y el rawBody sin cambios. Verifica HMAC-SHA256(timestamp + "." + nonce + "." + rawBody) contra x-callback-signature. Después valida identidad, orden, activo, red e importe. Una transacción de base de datos y una restricción única evitan el doble abono. Devuelve HTTP 2xx tras persistir de forma fiable; una redirección no confirma el pago.

Caso ilustrativo de integración

Ejemplo: un producto cuesta 10.00 USDC. Crea la orden BSC y guarda su referencia. Verifica el callback completed y registra pago y permiso de descarga en una transacción. El callback repetido no vuelve a autorizar; un timeout exige consultar la orden original. Es una ilustración, no una operación de cliente.

Verificaciones antes del lanzamiento

La firma válida pasa; cambiar el cuerpo original invalida la firma.
Un callback duplicado abona una vez; el procesamiento interrumpido se recupera.
Consulta, callback, contabilidad y transacción en cadena coinciden.
Red incorrecta, importe anómalo, vencimiento o resultado desconocido requieren revisión.

Integración y referencias técnicas

Las fuentes explican estándares y métodos técnicos; no implican respaldo a UUGate. Los parámetros aplicables están en la documentación actual de UUGate.