# Integrar con IA · blockwallets > Añade pagos en cripto de blockwallets sin escribir código tú mismo: elige tu sitio y tu herramienta de IA, copia el prompt generado en Claude Code, Codex, Cursor o ChatGPT, y se integra a partir de la documentación y revisa su propio trabajo. > > HTML: https://blockwallets.io/docs/ai?lang=es · English: https://blockwallets.io/docs/ai.md?lang=en ## Prompt universal ```text Ayúdame a aceptar pagos en cripto en mi sitio web con blockwallets (los clientes pagan en USDT, USDC, BTC y más; a mí se me acredita en dólares estadounidenses). 1. Lee primero la documentación en lugar de adivinar la API: https://blockwallets.io/llms-full.txt (documentación completa) y https://blockwallets.io/agents.md (reglas de integración, errores comunes, lista de comprobación de aceptación). Dime si no puedes abrirlos. 2. Mira mi proyecto, dime con qué está hecho y cómo piensas integrarlo, y espera mi visto bueno. 3. Por defecto: “crear una factura y redirigir a la página de pago + webhook”. Verifica siempre las firmas de los webhooks y deduplica los webhooks, porque el mismo puede llegar dos veces. 4. Guarda el ID del merchant y la API key en variables de entorno, y haz que funcione primero con las credenciales de Test en testnets. 5. Al terminar, recorre la lista de comprobación de aceptación de agents.md punto por punto y dime cada resultado. No soy programador: en cada paso, dime qué cambiaste y qué tengo que hacer yo. ``` ## Cuéntanos sobre tu sitio. ¿No lo sabes? Elige “Otro / no lo sé” y la IA mirará primero tu proyecto. - Con qué está hecho tu sitio: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · Otro / no lo sé - Cómo quieres cobrar: - Redirigir a una página de pago: Crea una factura al pagar; cuando se paga, avisamos a tu servidor. Los pedidos se envían solos. - Una dirección de depósito fija por usuario: Cada usuario recibe una dirección permanente y recarga cualquier importe, cuando quiera. - Enlace de pago (sin código): Crea un enlace en el panel y compártelo. La IA solo añade un botón. Los enlaces de pago no necesitan código: panel → “Cobros › Enlaces de pago” → escribe un importe → crear, y comparte el enlace. La IA solo pone un botón en tu sitio. ## ¿Qué IA usas? - **Claude Code / Codex**: IA que edita tu código y ejecuta comandos. La más fácil. - Abre una terminal en la carpeta del proyecto de tu sitio y guarda las reglas de integración como AGENTS.md: - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md` - Codex lee AGENTS.md por sí solo. Para Claude Code, ejecuta además: - `echo '@AGENTS.md' >> CLAUDE.md` - Después pega el prompt del paso 3. - También puedes instalar el servidor MCP de blockwallets para que la IA busque en la documentación y cree facturas de prueba directamente. https://blockwallets.io/docs/mcp?lang=es - **Cursor / Windsurf / Copilot**: IA dentro de tu editor de código. - Pon también AGENTS.md en la raíz del proyecto (Cursor lo detecta automáticamente): - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md` - Cambia al modo Agent y pega el prompt. - También puedes instalar el servidor MCP de blockwallets para que la IA busque en la documentación y cree facturas de prueba directamente. https://blockwallets.io/docs/mcp?lang=es - **ChatGPT / Claude (web)**: Solo chat. Tú pegas el código en tu sitio. - Pega el prompt en un chat nuevo, o usa “Abrir en ChatGPT / Claude” más abajo. - Si dice que no puede abrir enlaces, abre https://blockwallets.io/llms-full.txt, selecciona todo, copia y pégalo también. - Te dará el código completo y dónde ponerlo; sigue los pasos uno a uno. Una herramienta que edita el código por ti (Claude Code, Codex, Cursor) ahorra mucho copiar y pegar. - **Otra IA**: Gemini, el chat de Copilot y otras. - Pega el prompt. Si no puede abrir páginas web, pega también el contenido de llms-full.txt. ## Copia el prompt. Se actualiza según lo que elijas arriba y lleva los enlaces a la documentación, los errores habituales y una lista de comprobación de aceptación. Ejemplo: Otro / no lo sé + redirigir a una página de pago + Claude Code / Codex ```text Eres mi desarrollador. Ayúdame a aceptar pagos en cripto en mi sitio web con blockwallets (los clientes pagan en USDT, USDC, BTC y otras 14 monedas; a mí se me acredita en dólares estadounidenses). ## Sobre mí - Mi sitio está hecho con: No estoy seguro. Mira primero mi proyecto, dime con qué está hecho y luego empieza. - Cómo quiero cobrar: Crea una factura al finalizar la compra y redirige al cliente a la página de pago de blockwallets; cuando llegue el dinero, blockwallets llamará a mi servidor y yo marcaré el pedido como pagado y lo enviaré. - No soy programador. En cada paso, dime qué archivos cambiaste y qué tengo que hacer yo (por ejemplo, dónde poner las variables de entorno). No cambies demasiado de una vez. - AGENTS.md en la raíz del proyecto contiene las reglas de integración de blockwallets; léelo primero, y lee https://blockwallets.io/llms-full.txt para los detalles. ## Lee primero la documentación; no adivines la API de memoria - Documentación de integración completa (Markdown): https://blockwallets.io/llms-full.txt - Reglas de integración y errores comunes: https://blockwallets.io/agents.md - Si el sitio ya usa Cryptomus, NOWPayments o Coinbase Commerce, cámbialo a la API compatible correspondiente en lugar de reescribirlo: https://blockwallets.io/docs/migrate.md?lang=en - Si no puedes abrir un enlace, dímelo y pegaré el contenido. ## Puntos clave (donde suelen fallar las integraciones) 1. Todos los endpoints son POST + JSON en https://blockwallets.io. Cabeceras: merchant = el UUID del merchant, sign = md5(base64(cuerpo de la petición) + API key). Firma exactamente la cadena JSON que envías; no la vuelvas a serializar después de firmar. 2. Crea una factura con POST /v1/payment. Obligatorios: amount (una cadena con hasta dos decimales, p. ej. "42.00"), currency ("USD"), order_id (mi número de pedido: letras, dígitos, - y _, hasta 100 caracteres). Pasa también url_callback (la URL del webhook) y url_success (a dónde vuelve el cliente tras pagar). Redirige al cliente a result.url. 3. Si se llama de nuevo con el mismo order_id se devuelve la misma factura, así que los reintentos son seguros y nunca crean una segunda factura. 4. Hay que verificar las firmas de los webhooks: analiza el JSON del webhook, quita el campo sign, vuelve a codificar el resto como lo hace json_encode de PHP (compacto, caracteres no ASCII sin escapar, / escapada como \/), y md5(base64(codificado) + API key) debe ser igual a sign. Olvidar escapar / es el error más común. 5. Marca el pedido como pagado solo cuando status sea paid o paid_over, usando payment_amount_usd. El mismo webhook puede llegar más de una vez: deduplica por uuid + status. Responde con un estado 2xx una vez procesado. 6. Guarda el ID del merchant y la API key en variables de entorno (p. ej. BW_MERCHANT, BW_API_KEY); nunca los escribas en el código ni los subas al repositorio. Antes, añade el dominio de la URL del webhook en “Dominios del sitio web”, dentro de “Desarrolladores › Integración y claves” del panel. 7. Haz que todo funcione primero con las credenciales de Test (testnets, sin dinero real); pasa a Live solo cuando yo lo confirme. ## Cuando termines, revisa cada punto y dime el resultado - [ ] Crear una factura de prueba con las credenciales de Test y obtener el enlace de la página de pago (result.url) - [ ] Abrir la página de pago y pulsar “Simular pago” → importe completo - [ ] Mi servidor recibe un webhook con status paid y la firma se verifica - [ ] El pedido correspondiente queda marcado como pagado - [ ] Si el mismo webhook llega otra vez (reenvíalo desde “Desarrolladores › Registro de webhooks” en el panel, o con POST /v1/payment/resend), no se envía dos veces Si algún punto falla, dime dónde se atasca y el mensaje de error exacto antes de cambiar nada más. ``` ### Cuando la IA termine, comprueba esto **Redirigir a una página de pago** 1. Crear una factura de prueba con las credenciales de Test y obtener el enlace de la página de pago (result.url) 2. Abrir la página de pago y pulsar “Simular pago” → importe completo 3. Mi servidor recibe un webhook con status paid y la firma se verifica 4. El pedido correspondiente queda marcado como pagado 5. Si el mismo webhook llega otra vez (reenvíalo desde “Desarrolladores › Registro de webhooks” en el panel, o con POST /v1/payment/resend), no se envía dos veces **Una dirección de depósito fija por usuario** 1. Abrir una dirección para un usuario de prueba con las credenciales de Test y obtener la dirección y el enlace de la página de depósito 2. Enviar un webhook de ejemplo con POST /v1/test-webhook/wallet 3. Mi servidor recibe un webhook con type wallet y la firma se verifica 4. El saldo de ese usuario sube en payment_amount_usd 5. Si el mismo webhook llega otra vez, el saldo no se acredita dos veces **Enlace de pago (sin código)** 1. El botón se ve bien en el ordenador y en el móvil 2. El botón abre mi enlace de pago (usa primero un enlace creado en modo Test) 3. Al pulsar “Simular pago” en la página de pago, el pago aparece en “Cobros › Transacciones” del panel ## Cuando la IA se atasca. - **La firma nunca se verifica**: Pega el cuerpo bruto del webhook en el [verificador de firmas](https://blockwallets.io/docs/sign?lang=es). Muestra cada paso intermedio y marca la primera diferencia; dile a tu IA exactamente qué difiere. - **Un endpoint devuelve un error**: Pega a tu IA la petición y la respuesta exactas (con el message). Cuando la firma es incorrecta, debug.body_base64 de la respuesta 401 es el texto que firmamos; pide a la IA que lo compare con el suyo. - **No sé dónde se atasca**: Pide a la IA que recorra la lista de comprobación de aceptación desde el primer punto, uno a uno, informando de cada resultado. La página “Desarrolladores › Registro de webhooks” del panel muestra cada petición de webhook y la respuesta de tu servidor. ### Cuatro cosas que debes vigilar. - **Da a la IA solo credenciales de Test**: El ID del merchant y la API key de Test funcionan en testnets; aunque se filtren, no se puede mover dinero. - **Mantén la API key de Live fuera de los chats**: Pon tú mismo la API key de Live en las variables de entorno de tu servidor. No la pegues nunca en un chat ni la subas a un repositorio. - **Haz una copia antes de que la IA edite**: Haz un commit (git commit) o copia los archivos de tu sitio antes de que empiece la IA, para poder deshacer. - **Paga tú una vez antes de salir en vivo**: Tras pasar a Live, paga un importe real pequeño con “Probar un pago” en la página de inicio del panel y comprueba que el pedido queda pagado y que el saldo llega. ## Un archivo de reglas para agentes de código. AGENTS.md reúne lo esencial de la integración, los errores habituales y la lista de comprobación de aceptación. Ponlo en la raíz de tu proyecto: Codex y Cursor lo leen automáticamente, y Claude Code lo importa con @AGENTS.md. ```sh curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md echo '@AGENTS.md' >> CLAUDE.md ``` - [Reglas de integración (AGENTS.md)](https://blockwallets.io/agents.md) - [Resumen de una página](https://blockwallets.io/llms.txt) - [Documentación completa](https://blockwallets.io/llms-full.txt) - [Esta página en Markdown](https://blockwallets.io/docs/ai.md?lang=es) - [Documentación en Markdown](https://blockwallets.io/docs.md?lang=es) - [Servidor MCP](https://blockwallets.io/docs/mcp?lang=es) ## Preguntas, respondidas. ### ¿Puedo integrar de verdad con IA si no sé programar? En la mayoría de los sitios, sí. La IA escribe el código de creación de facturas y de firma a partir de la documentación; tú pones las credenciales en variables de entorno y recorres la lista de comprobación de aceptación en modo de prueba. Si no quieres nada de código, usa los enlaces de pago. ### ¿Qué herramienta de IA debo usar? Lo más fácil es una herramienta que edite tu proyecto y ejecute comandos: Claude Code, Codex o Cursor. ChatGPT o Claude en la web también sirven, pero tú pegas el código en tu sitio. ### ¿Debo darle mi API key a la IA? Solo las credenciales de Test, y en un archivo de entorno en lugar del chat. Pon tú mismo la API key de Live en tu servidor. ### La firma del webhook nunca se verifica. ¿Y ahora? Quita sign, vuelve a codificar el resto como lo hace json_encode de PHP y escapa / como \/. Pega el cuerpo bruto del webhook en /docs/sign para comparar cada paso y luego dile a la IA qué difiere. ### La IA dice que ha terminado. ¿Cómo lo compruebo? Recorre la lista de comprobación de aceptación: crea una factura de prueba, simula el pago, comprueba que el webhook se verifica, que el pedido queda marcado como pagado y reenvía el mismo webhook para confirmar que no se envía nada dos veces. Paga un importe pequeño en Live antes de salir en vivo.