Lo que necesitas
| Campo | Que hace |
|---|---|
| Access token | Nos permite llamar a Square para crear el enlace del carrito. Secreto. |
| Webhook signature key | Confirma que un webhook realmente proviene de Square. Secreto. |
| Location ID | La ubicacion de Square que recibe el pago. Establece la moneda. |
| Success URL / Cancel URL | Donde llega el cliente despues de pagar o retroceder. |
Por que pedimos cada campo
Access token
Autoriza la creacion del enlace del carrito, para que el cobro se ejecute a traves de tu cuenta.
Webhook signature key
Comprueba que un webhook entrante viene genuinamente de Square, para que nadie pueda falsificar un evento de "pagado". Es un valor separado del token de acceso.
Location ID
Le dice a Square cual ubicacion recibe el dinero y establece la moneda del carrito. No es secreto.
Success and Cancel URL
Configuracion simple: donde llega el cliente despues de pagar o retroceder. No es secreto.
Configurar
- Abre el panel de desarrolladores de Square
Inicia sesion en developer.squareup.com. Cada aplicacion tiene sus propias credenciales, y se crea un Sandbox gratuito junto con ella para las pruebas. Esta guia recorre el Sandbox; el flujo en vivo es identico, solo cambia el selector de Sandbox / Production y usa tus credenciales de produccion. Para crear una nueva aplicacion, haz clic en el mosaico + en la pantalla de Aplicaciones.
Square Developer → Applications - Nombra tu aplicacion
Dale a la aplicacion un nombre que reconozcas (por ejemplo "Coin Moebius"), luego haz clic en Next.
Square → Name your application - Copia tu token de acceso
Abre la aplicacion y ve a Credentials. Confirma que el selector Sandbox / Production en la parte superior coincida con el entorno que estas configurando. Haz clic en el icono de copia junto al Access token y apartalo.
Square → Credentials El token de acceso es secreto, tratalo como una contrasena. Sandbox y Production tienen tokens separados, asi que no los mezcles.
- Copia tu Location ID
En el menu de la izquierda, abre Locations. Copia el Location ID de la ubicacion que debe recibir los pagos. Establece la moneda del carrito, asi que elige la cuya moneda quieres cobrar.
Square → Locations - Abre Webhooks → Subscriptions
Square llama a un endpoint de webhook una "suscripcion". En el menu de la izquierda, expande Webhooks, abre Subscriptions y haz clic en Add subscription.
Square → Webhooks → Subscriptions → Add subscription - Anade la suscripcion y selecciona eventos
Dale un nombre (como "coin-moebius"). En Notification URL, pega la direccion del webhook de tu proyecto para Square (abajo). Luego, en Events, busca y marca los eventos que Coin Moebius escucha, y haz clic en Save.
- Pagos puntuales: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Suscripciones (solo si las vendes): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Si no cobras recurrentemente, omite estos.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription Tu ID de proyecto esta bajo el nombre del proyecto en el panel de Coin Moebius; insertalo en la direccion anterior. Los eventos adicionales son inofensivos, ignoramos lo que no usamos. La tarjeta del proveedor conectado (ultimo paso) muestra la misma URL como referencia.
- Abre la suscripcion que acabas de crear
Square guarda la suscripcion y la enumera bajo Webhooks con estado Enabled. Haz clic en su nombre para abrir el panel de detalles donde vive la clave de firma.
Square → Webhooks → your subscription (Enabled) - Copia la clave de firma
En el panel Properties de la suscripcion, haz clic en el icono de copia junto a Signature key. Este es el valor que Coin Moebius usa para confirmar que cada webhook realmente proviene de Square. Solo existe una vez que se crea la suscripcion, es por eso que el webhook vino antes del paso de conexion.
Square → your subscription → Signature key - De vuelta en Coin Moebius: Anade proveedor → Square
En tu proyecto, abre la pestana Providers, haz clic en Add provider, elige Connect a service y elige Square. Establece tu Success URL y Cancel URL. En la pestana Live, pega tu Access token, Webhook signature key y Location ID, luego haz clic en Save. ¿Configurando primero con credenciales de sandbox? Pegalas en la pestana Test en su lugar, luego anade las credenciales en vivo mas tarde desde Edit.
Coin Moebius → Add provider → Square - Estasconectado
Square ahora aparece en tu pestana Providers con la fecha en que se conecto. La tarjeta muestra la misma URL de webhook que pegaste en Square, mas Edit y Disconnect. Usa el selector Test mode para ejecutar un pedido de sandbox de principio a fin antes de pasar a produccion.
Coin Moebius → Providers → Square (connected) Las tarjetas de Sandbox nunca cobran una tarjeta real. Usa la tarjeta 4111 1111 1111 1111, CVV 111, cualquier vencimiento futuro, cualquier codigo postal valido (por ejemplo 94103).
Despues que conectes
Ejecuta un pago de prueba antes de pasar a produccion:
- Crea un producto y establece su Environment a Testing. Eso ejecuta el producto en tus credenciales de sandbox, para que puedas hacer un pedido completo sin mover dinero. (Si omitiste el conjunto de sandbox, un producto Testing retrocede a en vivo, asi que anadelo primero.)
- Coloca el boton de compra en una pagina (funciona un archivo HTML local).
- Completa el carrito con la tarjeta de prueba de sandbox anterior.
- Abre la pestana Transactions. Aparece una nueva fila, etiquetada Testing. Cuando su estado alcance succeeded, tus credenciales y webhook funcionan correctamente de principio a fin.
Cambia el Environment del producto a Live cuando estes listo para pagos reales.
Resolucion de problemas
Comienza con Verify. En el panel, haz clic en Verify (o Verify test credentials) para revisar tu token de acceso y ubicacion.
Verify falla.
Vuelve a copiar el token de acceso y el Location ID. Production y Sandbox tienen tokens separados, asi que no los mezcles.
Falla la verificacion de firma, o el pedido permanece pendiente.
Square firma sobre la URL de notificacion exacta mas el cuerpo. La URL que registres en Square debe coincidir con tu URL de webhook caracter por caracter, sin barra diagonal al final ni cadena de consulta adicional. Luego vuelve a copiar la clave de firma de ese mismo endpoint.
Confirmalo de principio a fin.
Square Developer Console → Webhooks → your subscription → Send Test Event, luego observa la actualizacion del pedido.
Bueno saber
La moneda sigue la ubicacion. El carrito cobra en la moneda de la ubicacion cuyo id proporcionas.
Rotacion de secretos. Cambia el token de acceso o la clave de firma en cualquier momento, luego pega el nuevo valor. Los campos secretos permanecen en blanco en edicion.
Preguntas Join our Discord