ePayco Skill

Conocimiento operativo para integrar pagos con ePayco en Colombia, empaquetado como skill para Claude Code y como guía legible para cualquier desarrollador.

Buena parte de lo que hay aquí no está en la documentación oficial: se dedujo integrando la pasarela de verdad, cobrando con tarjetas de prueba y leyendo sus mensajes de error.

No es un producto oficial de ePayco ni está afiliado a la empresa.

English version below ↓

---

Por qué existe

Integrar una pasarela de pagos tiene dos partes. La primera está documentada: qué endpoint llamar y qué campos enviar. La segunda no: qué hace la API cuando algo va mal, qué valores acepta de verdad, qué se comporta distinto en pruebas y en producción, y qué fallos no dejan rastro.

Esa segunda parte es la que cuesta horas. Este repositorio la recoge.

Qué encontrarás

.claude/skills/epayco/SKILL.md	La skill completa. Cópiala a .claude/skills/ de tu proyecto
examples/crear-sesion.ts	Crear una sesión del Smart Checkout desde el backend
examples/validar-firma.ts	Validar la firma del webhook de confirmación
examples/content-security-policy.md	Los dominios que hay que permitir en la CSP
docs/trampas.md	Las trampas, una por una, con su síntoma y su causa

Instalación como skill

mkdir -p .claude/skills
cp -r ruta/a/epayco-skill/.claude/skills/epayco .claude/skills/

A partir de ahí, tu agente la usará cuando el trabajo toque ePayco.

Lo esencial, en cinco puntos

1. La API responde HTTP 200 aunque haya fallado. El resultado real está en success y en data.errors[].errorMessage. Decidir por el código HTTP es la causa número uno de fallos invisibles.
2. Solo el webhook acredita un pago. La página de retorno es manipulable por quien navega.
3. Hay dos referencias por transacción, una numérica y una ofuscada, y la consulta de validación solo acepta la ofuscada. Guardar las dos.
4. El límite de importe de 5.000–200.000 es del sandbox, no de producción. No lo dejes como valor por omisión en tu código.
5. Con CSP activa, la ventana de pago no abre y no avisa. El formulario vive en new-checkout.epayco.co, que es el dominio que más se olvida.

El resto está en la skill.

Contribuir

Si descubres otro comportamiento no documentado, abre un issue contando el síntoma, lo que respondió la API y cómo lo confirmaste. Lo que hace útil a este repositorio es que cada afirmación esté verificada, no supuesta.

Licencia

MIT. Ver LICENSE.

---

ePayco Skill — English

Field-tested knowledge for integrating ePayco payments in Colombia, packaged as a skill for Claude Code and as a readable guide for any developer.

Much of this is not in the official documentation: it was learned by integrating the gateway for real, charging test cards, and reading its error messages.

Not an official ePayco product, and not affiliated with the company.

Why it exists

Integrating a payment gateway has two halves. The documented one: which endpoint to call, which fields to send. And the undocumented one: what the API does when something goes wrong, which values it really accepts, what behaves differently in sandbox versus production, and which failures leave no trace.

The second half is where the hours go. This repository collects it.

What's inside

.claude/skills/epayco/SKILL.md	The full skill, in Spanish. Copy it into your project's .claude/skills/
examples/crear-sesion.ts	Creating a Smart Checkout session from the backend
examples/validar-firma.ts	Validating the confirmation webhook signature
examples/content-security-policy.md	The domains your CSP must allow
docs/trampas.md	Every pitfall, with its symptom and its cause

The five things that matter most

1. The API answers HTTP 200 even when it failed. The real outcome lives in success and data.errors[].errorMessage. Trusting the HTTP status is the number one cause of invisible failures.
2. Only the webhook credits a payment. The return page can be tampered with by the buyer.
3. Each transaction has two references, numeric and obfuscated, and the validation endpoint only accepts the obfuscated one. Store both.
4. The 5,000–200,000 amount limit is a sandbox mock, not production. Never hardcode it as a default.
5. With CSP enabled, the payment window silently fails to open. The card form is served from new-checkout.epayco.co, the domain everyone forgets.

The skill itself is written in Spanish, which is the working language of ePayco's documentation and of most of its users.

Contributing

Found another undocumented behaviour? Open an issue with the symptom, what the API actually answered, and how you confirmed it. What makes this repository useful is that every claim is verified rather than assumed.

License

MIT. See LICENSE.