Dale a cada usuario una dirección de depósito cripto única

Por qué una dirección compartida no funciona

Toda plataforma que acepta cripto choca con el mismo muro y en el mismo orden, normalmente tras el primer ticket de soporte por un pago que nadie encuentra.

• Una única dirección te da un importe y un remitente, nunca a cuál de tus usuarios pertenece. Cuadrar por importe se rompe la primera vez que dos personas envían la misma cifra.
• El apaño habitual es juntarlo todo y pagar después, lo que convierte una función de pagos en custodiar el dinero de otros: lo más pesado que puede asumir una plataforma.
• Pedir a los usuarios que peguen un memo o una referencia funciona hasta que alguien lo olvida, y entonces hay una persona cuadrando una blockchain a mano.

Una llamada por usuario, una sola vez

Tú envías tu propio identificador de usuario. Recibes direcciones que nunca cambian, así que la llamada ocurre en el registro y nunca más.

1. 01

   Crea el cliente con tu propio id

   Pasa el id que ya usas para ese usuario en `external_ref`. Unheld no acuña un identificador que luego tengas que guardar y mapear: la ficha se indexa por el id que tu base de datos ya utiliza.

2. 02

   Guarda las direcciones que recibes

   La respuesta trae las direcciones de depósito de ese usuario, derivadas de tu propio monedero. Son permanentes: puedes mostrarlas, ponerlas en un código QR o dejar que el usuario las guarde y envíe desde donde quiera.

3. 03

   Abona la cuenta cuando llegue el webhook

   Un pago a esa dirección se atribuye al cliente al que pertenece, y la notificación te devuelve tu propio `externalRef`. Tu aplicación abona un id de usuario que ya conoce, sin cuadrar importes ni leer una cadena.

La llamada real

Solicitud

curl -X POST https://api.unheld.io/api/v1/customers \
  -H "Authorization: Bearer $UNHELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "user_8412",
    "label": "Ada Lovelace",
    "supported_assets": ["ETH", "USDC"],
    "evm": true
  }'

Respuesta

{
  "id": "c7f1…",
  "external_ref": "user_8412",
  "label": "Ada Lovelace",
  "evm_address": "0x…",
  "supported_assets": ["ETH", "USDC"],
  "receive_method": "auto"
}

Requiere una API key con el scope `customers:write`; volver a leerlas necesita `customers:read`. Las direcciones de cada cadena en la que un usuario puede pagar están en `GET /api/v1/customers/:id/addresses`.

Cómo un pago encuentra a su usuario

Las facturas también pueden vincularse a un cliente con `customerId`, de forma que un cobro puntual y una dirección de depósito fija se atribuyen al mismo usuario, tanto en tu panel como en tus webhooks.

Dónde está realmente el dinero

Lo que eso no te dice es si tu plataforma está custodiando fondos de tus usuarios. Probablemente sí, si los pagos llegan a direcciones que controlas y les debes ese valor a tus usuarios. Esa es una cuestión de tu propio montaje y tu jurisdicción, y no es una que podamos responder por ti: busca asesoramiento. Nosotros solo podemos afirmar nuestra parte: el dinero nunca pasa por Unheld.

Diseñar sobre esto

Cada uno de estos puntos es más fácil de prever ahora que de descubrir en producción.

• Todas las direcciones de usuario derivan de un solo monedero: el tuyo. Eso te deja una única frase de recuperación que proteger, no una por usuario, y significa que los fondos no están segregados por usuario mediante claves.
• Una dirección permanente se reutiliza por diseño, y eso es lo que hace posible la atribución. También implica que el historial de pagos de un usuario hacia ti es enlazable en cadena por cualquiera que conozca su dirección.
• La dirección de un usuario es fija por familia de cadenas: la misma dirección EVM recibe en todas las redes EVM que tengas habilitadas. Habilitar una cadena nueva no obliga a reemitir direcciones.
• Borrar un cliente detiene la vigilancia de su dirección; no mueve —ni puede mover— lo ya enviado allí. El dinero que llegue después del borrado sigue siendo tuyo, pero nada te avisará de él.

Preguntas