Wallets y cobros
Wallet exclusiva para depósitos — recomendada
Recomendado para depósitos de miembros: sin monto previo ni cuenta regresiva, con acreditación del monto recibido. Incluye operación del panel, vinculación por API, consultas y callbacks.
Ver el video03:46 · Audio y subtítulos en español
Mira el video en pantalla completa o elige un capítulo. Para recibir o enviar fondos, usa los datos de tu propio panel.
Guía paso a paso
Sigue los pasos en tu propio panel. Haz clic en una imagen para ampliarla.
Para recargar el saldo de miembros, recomendamos una wallet exclusiva. Asigna una dirección a cada miembro para que pueda usarla varias veces. No hay que indicar un monto por adelantado ni existe una cuenta regresiva de pago. Así evitas problemas por montos distintos o pedidos vencidos. La red, la moneda y las confirmaciones siguen siendo necesarias.
Paso 1 · Haz clic para ampliar Abre Wallets, pulsa Crear wallet, elige la moneda y la red y selecciona Wallet exclusiva. Si el miembro envía USDT por TRON, selecciona TRC20-USDT. La red siempre debe coincidir con la del envío. TRC20-USDT · BEP20-USDT · BEP20-USDC · SPL-USDC.
Paso 2 · Haz clic para ampliar En la información de vinculación, escribe un identificador estable y único del miembro. Corresponde a bindKey en la API, no al UID del comercio. Para acreditar el saldo automáticamente, indica la URL de callback de tu servidor. Si la dejas vacía, se usa la configuración predeterminada. Revisa el cupo antes de crear la wallet. Por ejemplo, MEMBER_10001 identifica al miembro. notifyUrl debe ser una URL HTTPS pública. No entregues al miembro la dirección de recarga de comisiones.
Paso 3 · Haz clic para ampliar Filtra la lista por Wallet exclusiva y comprueba la moneda y la dirección del miembro. Aquí también aparecen las wallets creadas por API. Para el mismo miembro, red y moneda, reutiliza la vinculación existente. No necesitas una wallet nueva para cada depósito.
Paso 4 · Haz clic para ampliar Abre el checkout desde la fila de la wallet. No verás un campo de monto ni una cuenta regresiva. Entrega la dirección completa o el enlace al miembro correspondiente. El miembro decide cuánto enviar y tu sistema acredita el monto que realmente recibe. Mantén la wallet habilitada para recibir depósitos. Antes de desactivarla, avisa al miembro que deje de enviar fondos a esa dirección.
Paso 5 · Haz clic para ampliar Para integrar la API, abre la herramienta oficial y selecciona Crear wallet exclusiva. Completa la moneda, el identificador del miembro y la URL de callback. No se necesitan monto, vencimiento ni número de pedido del comercio. El pedido de cobro se genera al detectar el depósito. POST /openapi/payin/exclusive-bindings · chainCode · tokenSymbol · bindKey · label? · notifyUrl?
Paso 6 · Haz clic para ampliar Autentica desde tu servidor con Merchant UID + API Key y los encabezados x-api-key, x-merchant-uid, x-timestamp, x-nonce y x-signature. El mensaje de firma HMAC-SHA256 tiene siete líneas: UID, timestamp en milisegundos, nonce, método HTTP en mayúsculas, ruta sin query, query normalizada y body normalizado. Usa el SDK oficial o el código del depurador y genera un timestamp y nonce nuevos en cada solicitud. Revisa los datos antes de crear una vinculación real.
Paso 7 · Haz clic para ampliar Guarda bindingId, addressId, address, bindKey, chainCode, tokenSymbol y status; el estado debe ser active. La misma combinación de comercio + red + moneda + bindKey devuelve la vinculación existente. Repetir la creación no reemplaza label ni notifyUrl. La respuesta no incluye cashierUrl: muestra address en tu página de depósitos o copia el enlace del checkout desde el panel.
Consulta con GET /openapi/payin/exclusive-bindings/{bindKey}?chainCode=TRON&tokenSymbol=USDT&recentLimit=10. Codifica bindKey para usarlo en la URL. GET no lleva body, pero la query participa en la firma. La respuesta contiene stats, recentOrders y recentTransactions. recentLimit admite de 1 a 20 y no sustituye el historial contable completo. Para una orden concreta, usa GET /openapi/payin/orders/{orderNo}.
Después de procesar el depósito, la plataforma envía el callback a notifyUrl de la wallet, o a la configuración predeterminada si está vacío. Verifica rawBody con la API Key correspondiente al pedido y comprueba comercio, red, moneda, bindKey y status=completed. Acredita paidAmount, el monto realmente recibido. Usa (merchantUid, orderNo) como clave única y guarda la deduplicación y el aumento del saldo en una misma transacción de base de datos. Devuelve HTTP 2xx tras el éxito. Confirma duplicados sin acreditar otra vez. No dedupliques solo por bindKey: eso descartaría el siguiente depósito del miembro.
Paso 10 · Haz clic para ampliar En los pedidos de cobro, filtra por dirección, etiqueta o identificador de vinculación. Revisa monto, estado y hash. La API también permite consultar las operaciones recientes de una vinculación y luego un pedido concreto. La guía escrita incluye las rutas y los ejemplos. Concilia el resultado con el registro de la wallet y el saldo de tu miembro. El botón Callback reenvía una notificación; no abre una consulta. Asegura la deduplicación antes de usarlo.
Paso 11 · Haz clic para ampliar Si el saldo del miembro no cambia, revisa la red, la moneda y las confirmaciones. Después comprueba el pedido, la URL de callback y los registros de tu servidor. Si falla la firma, revisa la normalización, el reloj y nonce. Si no aparece la vinculación, revisa comercio, red, moneda y bindKey. También comprueba el estado de la cuenta, el cupo de direcciones y el saldo de comisiones.
Asigna un identificador distinto a cada miembro y reutiliza su vinculación para la misma red y moneda. Acredita el monto realmente recibido después de verificar el callback y evita duplicados por pedido.
Flujo de depósito de un miembro
El miembro inicia sesión y elige red y moneda
→ El servidor obtiene el bindKey estable del miembro
→ Crea o consulta la vinculación exclusiva y reutiliza su dirección
→ El miembro elige cuánto enviar a esa dirección
→ La plataforma detecta y confirma el depósito y genera un pedido exclusivo
→ Verifica el callback completed y acredita paidAmount una sola vez por pedido
→ Concilia pedidos y registros del panel con los abonos del miembroNode.js: crear o reutilizar una vinculación (crea una wallet real)
import { UUGateClient } from 'uugate-openapi-sdk';
const client = new UUGateClient({
baseUrl: 'https://api.uugate.com',
merchantUid: process.env.UUGATE_MERCHANT_UID,
apiKey: process.env.UUGATE_API_KEY,
});
const binding = await client.createExclusiveBinding({
chainCode: 'TRON',
tokenSymbol: 'USDT',
bindKey: 'MEMBER_10001',
label: 'MEMBER_10001',
notifyUrl: 'https://merchant.example.com/uugate/notify',
});Node.js: consultar una vinculación y sus depósitos recientes (reutiliza client)
const bindKey = 'MEMBER_10001';
const detail = await client.request('GET',
'/openapi/payin/exclusive-bindings/' + encodeURIComponent(bindKey), {
query: { chainCode: 'TRON', tokenSymbol: 'USDT', recentLimit: 10 },
});Lógica de acreditación por callback (pseudocódigo; usa una transacción de base de datos)
Conserva el cuerpo HTTP original como rawBody
Verifica x-callback-signature con la API Key asociada al pedido:
HMAC-SHA256(apiKey, timestamp + "." + nonce + "." + rawBody)
Valida timestamp, protección contra repetición y campos del negocio
Exige el merchantUid correcto y status == "completed"
Busca al miembro por bindKey + chainCode + tokenSymbol
Dentro de una misma transacción de base de datos:
Registra el depósito con clave única (merchantUid, orderNo)
Ya registrado → no vuelvas a acreditar
Primer registro → aumenta el saldo en paidAmount con aritmética decimal
Devuelve 2xx tras el éxito; en caso de fallo, devuelve un estado distinto de 2xx y registra el error
// bindKey identifica al miembro; orderNo identifica un depósito. No los intercambies.