Integración de pagos en Polygon: guía para desarrolladores

Ilustración de una wallet que envía un pago por un camino hasta una blockchain de bloques enlazados

Una integración de pagos en Polygon es el conjunto de componentes que permite a su aplicación aceptar y enviar tokens en la red Polygon PoS: wallets, transferencias, verificación y notificaciones. Puede construir cada componente contra nodos en bruto, o llamar a una API REST que ofrece wallets, transferencias y webhooks. Esta guía cubre ambas vías.

Resumen

Polygon PoS tiene el chain ID 137 y usa POL para el gas. La testnet Amoy tiene el chain ID 80002.
Un pago solo está hecho cuando ha comprobado el estado de la transacción, el destinatario, el importe y el contrato del token. El hash por sí solo no es prueba.
Use webhooks, no consultas periódicas, para seguir los pagos. Verifique la firma y haga que su manejador sea idempotente.
Los webhooks de Chaingateway no se reintentan automáticamente, así que concilie con la lista de notificaciones.
Planifique el alcance legal, la custodia de las claves, los conflictos de nonce y las variaciones del gas antes del lanzamiento, no después.

Tabla de contenidos

¿Qué incluye una integración de pagos en Polygon?
¿Qué red y qué token debo elegir?
¿Cómo configuro las wallets y protejo las claves?
¿Cómo envío un pago en tokens en Polygon?
¿Cómo verifico que ha llegado un pago?
¿Cómo recibo notificaciones con webhooks?
¿Cómo debo diseñar el backend?
¿Qué debo comprobar antes del lanzamiento?
Preguntas frecuentes
Fuentes

¿Qué incluye una integración de pagos en Polygon?

Una integración de pagos es más que enviar tokens. Una pasarela que funciona gestiona las wallets de los usuarios, sigue el estado de cada transacción mediante webhooks y concilia los saldos en una base de datos. La cadena solo le dice lo que ha ocurrido. Su backend decide lo que significa para un pedido, una factura o un saldo.

En la práctica, construye cinco componentes:

Capa de wallets: direcciones para recibir fondos y claves para enviarlos.
Capa de transferencias: código que construye, firma y difunde transferencias de tokens.
Capa de verificación: comprobaciones de que una transferencia se produjo realmente como se esperaba.
Capa de notificaciones: webhooks que informan a su aplicación de los cambios de estado.
Libro mayor: su registro propio de lo que se debe, se paga y se liquida.

Los cuatro primeros son infraestructura de cadena. El quinto es su producto. Cuanto menos tiempo dedique a la infraestructura, antes lanzará la parte que ven sus clientes.

¿Necesito una licencia?

Determine dónde opera y qué normas se aplican antes de escribir código. En la UE, el Reglamento de Mercados de Criptoactivos (MiCA) regula a los proveedores de servicios de criptoactivos, tal como se describe en la página de MiCA de ESMA. En EE. UU., la guía de FinCEN sobre monedas virtuales describe cuándo administrar o intercambiar moneda virtual le convierte en transmisor de dinero.

Si su modelo activa alguna norma depende de si retiene o mueve fondos de terceros. Esa pregunta corresponde a un abogado que conozca los pagos, no a una revisión de código. Plantéela antes del lanzamiento, porque la respuesta puede cambiar si llegará a custodiar fondos.

¿Qué red y qué token debo elegir?

Para la mayoría de los productos de pago, elija Polygon PoS con una stablecoin como USDC o USDT. La documentación de Polygon enumera el chain ID 137 y POL como token de gas para la mainnet, y el chain ID 80002 para la testnet Amoy. Fije el chain ID en su código de firma, para que una transacción nunca pueda difundirse a la red equivocada.

Las comisiones son el motivo por el que los equipos eligen Polygon, pero varían con la congestión y con el precio de POL. Diseñe el manejo de comisiones en torno a rangos y lea el precio actual del gas en el momento del envío. Con Chaingateway, GET /api/v2/polygon/gasprice lo devuelve.

Ethereum es la alternativa para los clientes que prefieren su liquidez y su liquidación. Si necesita ambas, una API para varias cadenas le permite escribir el flujo de pago una sola vez. Consulte la API de Ethereum para el otro lado de esa configuración.

Sus wallets de envío necesitan POL para el gas, incluso cuando el activo enviado es una stablecoin. Cuando financie una wallet desde una plataforma de trading, elija Polygon como red de retirada y compruebe la etiqueta de red antes de confirmar. Una retirada en la red equivocada es una forma habitual de perder fondos durante la configuración.

Decisión	Elección habitual para pagos	Por qué
Red	Polygon PoS (chain ID 137)	Comisiones bajas
Token de pago	USDC o USDT (ERC-20)	Valor estable, conocido por los clientes
Token de gas	POL	Necesario en cada transacción
Notificaciones	Webhooks	Sin consultas periódicas

¿Cómo configuro las wallets y protejo las claves?

Hay dos patrones habituales:

Una dirección por cliente o factura. Cada pago tiene su propia dirección de depósito. Asociar una transferencia entrante a un pedido resulta entonces trivial, porque la dirección del destinatario lo identifica. El coste es gestionar más direcciones y, más adelante, traspasar los fondos a una wallet de tesorería.
Una dirección compartida con referencias. Es más sencilla de operar, pero una transferencia de token simple no tiene campo de referencia. Acaba emparejando por importe y momento, lo que falla cuando dos clientes pagan la misma cantidad.

Para la mayoría de los flujos comerciales, las direcciones por pedido son el diseño más limpio. Elija lo que elija, mantenga estos hábitos:

No guarde nunca las claves privadas en el control de versiones, en los logs ni en el código del cliente.
Separe las wallets de recepción de la tesorería que guarda su saldo, para que el compromiso de una no exponga la otra.
Limite quién y qué puede disparar una transferencia saliente, y registre cada petición.
Haga copias de seguridad del material de claves de forma que sobreviva a la pérdida de una persona o de un servidor.

Chaingateway es no custodial. POST /api/v2/polygon/addresses crea una wallet. Si envía una password, la clave privada se guarda cifrada con ella, y usa la contraseña en lugar de la clave al enviar una transacción. Chaingateway no almacena la contraseña y no puede restaurar una wallet si la pierde. Consulte crear una wallet cripto con una API para el flujo de llamadas.

¿Cómo envío un pago en tokens en Polygon?

Polygon PoS es compatible con EVM, así que las transferencias de tokens siguen el estándar ERC-20. La especificación ERC-20 define dos patrones de pago:

Pago directo: el pagador llama a transfer(recipient, amount), que emite un evento Transfer.
Pago por cobro mediado por contrato: el pagador llama primero a approve(spender, amount), y después el contrato autorizado llama a transferFrom(sender, recipient, amount).

Para un checkout sencillo, basta una transferencia directa. Las aprobaciones importan cuando un contrato inteligente cobra el dinero, como en suscripciones o depósitos en garantía. Mantenga las aprobaciones acotadas: apruebe el importe que necesita, no una asignación ilimitada.

¿Cómo envío con código contra el nodo?

Enviar directamente significa construir la transacción, estimar el gas, fijar el nonce, firmar, difundir y vigilar su inclusión. Eso es manejable en un prototipo. En producción, además necesita un proveedor RPC fiable, lógica de reintentos y una forma de reemplazar las transacciones bloqueadas. Nuestra guía sobre cómo enviar tokens ERC-20 compara los métodos con wallet, con código y con API.

¿Cómo envío con una sola llamada REST?

Con Chaingateway, una transferencia de token es una única petición autenticada. Indica el remitente, el contrato del token, el destinatario y el importe. Los campos de gas son opcionales. La definición OpenAPI marca como obligatorios from, contractaddress, to y amount.

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xSenderAddress",
    "contractaddress": "0xTokenContract",
    "to": "0xRecipientAddress",
    "amount": 25.5,
    "password": "wallet-password"
  }'

X-Network: testnet ejecuta la petición en Amoy. Omita la cabecera para la mainnet. El mismo patrón funciona en las demás cadenas EVM, así que añadir una segunda cadena más adelante cambia la ruta, no el flujo. Consulte la página de la API de Polygon y el archivo OpenAPI para la lista completa de endpoints.

¿Cómo verifico que ha llegado un pago?

Un hash de transacción solo demuestra que la transacción se envió. Antes de marcar un pedido como pagado, compruebe el estado de la transacción, el destinatario, el importe de la transferencia del token y el contrato del token. Las transferencias ERC-20 se registran en logs de eventos Transfer, tal como define la especificación ERC-20, así que el log es donde se lee la transferencia real.

La comprobación del contrato es la que suelen olvidar los equipos. Cualquiera puede desplegar un token llamado «USDC» que no vale nada. Compare la dirección del contrato en el log con la dirección que tiene en su lista blanca. Su rutina de verificación debe confirmar todo esto:

La transacción se completó con éxito, no solo que fue minada.
El evento Transfer procede de su contrato de token esperado.
El destinatario coincide con la dirección que emitió para este pedido.
El importe es al menos lo facturado, en la unidad más pequeña del token.
Han pasado suficientes bloques según su tolerancia al riesgo antes de liberar mercancía.

Leer logs en bruto significa decodificar los topics y los datos a mano. Nuestra explicación sobre el evento Transfer de ERC-20 muestra la estructura. Chaingateway también devuelve transacciones decodificadas con GET /api/v2/polygon/transactions/{txid}/decoded.

¿Cómo recibo notificaciones con webhooks?

Consultar una dirección cada pocos segundos desperdicia peticiones y aun así va con retraso. Con un webhook, el servicio llama a su endpoint cuando se detecta una transacción que coincide. Créelo con POST /api/v2/polygon/webhooks. El campo url es obligatorio, y filtra por to, from o contractaddress. Consulte webhooks de Polygon para la mecánica.

¿Cómo construyo el receptor de forma segura?

Estas reglas se aplican a cualquier proveedor:

Verifique la firma. Chaingateway añade una cabecera X-Signature una vez que fija un secreto personal. Es un HMAC-SHA256 del ID de la transacción, codificado en Base64 y firmado con su secreto. Consulte verificar las firmas de los webhooks.
Compare en tiempo constante. Use la función de comparación segura de su lenguaje, no ==.
Responda rápido. Devuelva de inmediato un estado 2xx y haga el trabajo pesado en una cola.
Espere duplicados. Puede recibir el mismo evento dos veces, por ejemplo tras reenviar una notificación. Guarde el ID de la transacción e ignore las repeticiones.
Espere eventos perdidos. Chaingateway no reintenta automáticamente las notificaciones fallidas. Listelas con GET /api/v2/polygon/webhooks/notifications/failed y reenvíe cada una con POST /api/v2/polygon/webhooks/notifications/{id}/retry.

¿Qué estados de pago debo guardar?

Mantenga los estados de pago pequeños y explícitos: awaiting_payment, pending, confirmed, failed, expired. Cada webhook corresponde a lo sumo a una transición. Si llega un evento de fallo para un pago que ya está confirmado, regístrelo y avise a una persona, en lugar de sobrescribir el estado.

¿Cómo debo diseñar el backend?

Mantenga el código específico de cada cadena en los extremos. Ponga una interfaz interna delante de la cadena, con métodos como createDepositAddress, sendPayment y getPaymentStatus, y mantenga la lógica de pedidos al otro lado. Añadir una cadena significa entonces añadir una implementación de esa interfaz, no reescribir el núcleo.

El libro mayor debe ser suyo. Nunca trate la cadena ni el panel de un proveedor como su libro de registro. Guarde cada pago esperado, cada transferencia observada y la relación entre ambos, para poder conciliar al final del día y explicar cualquier diferencia.

¿Qué debo comprobar antes del lanzamiento?

Pruebe tres cosas en particular: transacciones fallidas, conflictos de nonce y cambios en el precio del gas.

Antes del lanzamiento

Ejecute el flujo completo en la testnet Amoy: cree una dirección, págueles, reciba el webhook y marque el pedido como pagado.
Reproduzca cada webhook dos veces y confirme que la segunda entrega no cambia nada.
Envíe un pago en un token equivocado, con un importe incorrecto (por defecto y por exceso) y a un pedido caducado. Decida y pruebe qué ocurre en cada caso.
Rompa su endpoint a propósito con un error 500 y un tiempo de espera, y después liste las notificaciones fallidas y reenvíelas.
Dispare dos transferencias desde la misma wallet a la vez para exponer conflictos de nonce.

En el lanzamiento

Empiece con límites bajos y un solo token.
Configure alertas para cualquier transferencia que siga pendiente más allá de su umbral.
Vigile el saldo de la wallet de gas, porque un saldo de POL vacío detiene todos los pagos salientes.
Renueve su secreto personal según un calendario y actualice a la vez su receptor.

Errores habituales

Confiar en el hash en lugar del log de eventos.
Confiar en un webhook antes de verificar la firma.
Fijar el precio del gas en el código.
Omitir la comprobación del contrato del token.
Guardar juntas las claves de la wallet caliente y las de la tesorería.

Los planes empiezan en 49 € al mes (490 € al año), con una prueba gratuita de 7 días que no requiere tarjeta. Consulte la página de precios.

Preguntas frecuentes

¿Qué token debo aceptar para pagos en Polygon?

La mayoría de los productos de pago aceptan una stablecoin como USDC o USDT, porque el precio no oscila entre la factura y el pago. Aun así, necesita un pequeño saldo de POL en cualquier wallet que envíe transacciones, ya que POL paga el gas. Ponga en lista blanca las direcciones exactas de los contratos de los tokens que acepta y rechace el resto.

¿Necesito ejecutar mi propio nodo de Polygon?

No. Puede usar un proveedor RPC alojado o una API blockchain que gestione el acceso a los nodos por usted. Ejecutar un nodo propio solo tiene sentido si tiene requisitos concretos de latencia, privacidad o cumplimiento y el equipo para mantenerlo.

¿Cómo evito acreditar dos veces el mismo pago?

Guarde un ID de transacción único para cada pago que procese, y compruébelo antes de cambiar el estado de cualquier pedido. Un manejador idempotente convierte un evento repetido en una operación sin efecto.

¿Es mejor Polygon o Ethereum para pagos?

Depende de lo que valore. Polygon PoS suele costar menos por transacción que la mainnet de Ethereum. Ethereum tiene una base de usuarios y una liquidez mayores. Muchos equipos admiten ambas y dejan que el cliente elija.