API blockchain para pagos de comercio electrónico
Cómo una tienda online acepta y paga cripto mediante una API blockchain: una dirección por pedido, webhooks, confirmaciones, reembolsos y pruebas en testnet.
Revisado por Maurice Sobiera
Una API blockchain para comercio electrónico es una interfaz REST que permite a una tienda online crear direcciones de pago, detectar pagos cripto entrantes y enviar reembolsos o pagos sin ejecutar nodos propios. La tienda se comunica por HTTPS y recibe webhooks cuando llega un pago. Las claves y las reglas de confirmación siguen bajo su control.
¿Cómo acepta una tienda online pagos cripto a través de una API?
Asigne a cada pedido su propia dirección de depósito, vígilela con un webhook y marque el pedido como pagado cuando el importe confirmado coincida. El flujo tiene cinco pasos:
- Cree una dirección para el pedido con
POST /api/v2/{blockchain}/addresses. - Registre un webhook para esa dirección con
POST /api/v2/{blockchain}/webhookse introduzca el ID de su pedido en el camporeference. - Muestre al cliente la dirección, el importe y una hora de caducidad.
- Cuando llegue el webhook, verifique la cabecera
X-Signaturey compruebe el importe y el token en la cadena. - Entregue la mercancía tras el número de confirmaciones que haya decidido.
Una dirección por pedido elimina las conjeturas: cualquier pago a esa dirección pertenece a ese pedido. La guía de webhooks de pago muestra el código del receptor, y el tutorial de Laravel muestra el mismo flujo en un framework PHP.
¿Qué debe guardar el registro del pedido?
Guarde datos suficientes para decidir por su cuenta si un pago está completo. El webhook le indica que algo ha ocurrido. El registro del pedido le indica lo que debería haber ocurrido.
| Campo | Finalidad |
|---|---|
| ID del pedido | Se envía también como reference del webhook, para poder asociar el evento |
| Red y token | La cadena y el contrato que el cliente debe usar |
| Dirección de depósito | La dirección creada para este pedido |
| Importe esperado | Convertido desde el precio de la tienda cuando se emitió la factura |
| Caducidad de la factura | Momento a partir del cual el precio ya no es válido |
| Confirmaciones necesarias | La regla que ha elegido para esta red y el tamaño del pedido |
| Estado | Pendiente, pagado parcialmente, pagado, caducado o reembolsado |
Con estos campos, el manejador del webhook es una comparación corta. Busque el pedido por reference, compruebe que coinciden la red y el token, sume el importe a lo recibido hasta ese momento y actualice el estado. Un pago del token equivocado a la dirección correcta es un caso normal que el manejador debe detectar, porque una dirección puede recibir cualquier token de su red.
¿Cuántas confirmaciones debe esperar una tienda?
Depende de la red y del valor del pedido. La documentación para desarrolladores de Bitcoin sobre procesamiento de pagos indica que una transacción con cero confirmaciones no debe fiarse sin un análisis de riesgo, y que el software que maneja transacciones de alto valor debería esperar al menos seis confirmaciones, lo que tarda aproximadamente una hora. En TRON, un bloque se solidifica cuando al menos 19 de los 27 Super Representatives han construido sobre él, lo que la documentación de consenso de TRON sitúa en torno a un minuto en condiciones normales.
Elija una regla por red y por tamaño de pedido, anótela y aplíquela en el código. Un artículo digital de bajo valor puede enviarse tras una confirmación. Un artículo físico de alto valor debería esperar más.
¿Qué hacer con los cambios de precio?
Fije el precio en su propia moneda, conviértalo al emitir la factura y deje que la factura caduque. La documentación de Bitcoin señala que los tipos de cambio varían, que las facturas referenciadas a moneda fiduciaria deben caducar y que la mayoría de los sistemas de pago hacen caducar las facturas a los 10 o 20 minutos. Un plazo más corto reduce el riesgo del tipo de cambio, pero aumenta la probabilidad de que el cliente pague tarde.
Decida de antemano qué ocurre con un pago tardío o parcial. La mayoría de las tiendas lo reembolsan, o piden al cliente que pague la diferencia a la misma dirección.
¿Cómo funcionan los reembolsos y los pagos?
Envíelos como transacciones ordinarias desde una dirección que usted controle. Use POST /api/v2/{blockchain}/transactions para la moneda nativa, y los endpoints de tokens, como transactions/erc20, transactions/bep20 o transactions/trc20, para los tokens. Un reembolso necesita la dirección de devolución del cliente, que debe pedir por separado, porque el remitente de un pago no siempre es el monedero que debe recibir el dinero de vuelta, por ejemplo cuando el pago procede de un exchange.
Mantenga corta la vida de los fondos de una dirección de pedido. Traslade los pagos entrantes a un monedero que tenga sin conexión, y use las direcciones de pedido solo para cobrar. Nuestros consejos de seguridad explican cómo guardar las claves.
¿Cómo controla las comisiones de red?
Prevea las comisiones en el lado del envío. Mover tokens fuera de una dirección de pedido cuesta gas en las redes EVM, y Energy o Bandwidth en TRON, y la dirección del pedido necesita suficiente moneda nativa para ello. En TRON, patrocinar o alquilar energy reduce el coste de las transferencias TRC-20. Nuestra documentación sobre TronFuel y el Paymaster obsoleto explica la opción actual. TronFuel es un servicio independiente con su propia documentación.
¿Cómo prueba la integración antes del lanzamiento?
Use las testnets. Añada la cabecera X-Network: testnet a cualquier solicitud y la misma llamada se ejecuta en una red de pruebas sin fondos reales. Pruebe un pedido completo, un pago insuficiente, un pago excesivo, un pago tardío y un webhook que no llegue a su servidor. Los webhooks fallidos no se reintentan automáticamente. Aparecen en GET /webhooks/notifications/failed y pueden reenviarse, así que su tienda debe revisar esa lista.
¿Necesita verificar a sus clientes?
Depende de su jurisdicción y de su modelo de negocio, y la API no lo decide por usted. Chaingateway no es custodio. Lea nuestro artículo sobre KYC para pagos cripto antes de decidir qué comprobaciones se aplican a su tienda.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.