Wompi — Complete Developer Skill
Wompi is Colombia's leading payment gateway, backed by Bancolombia. It processes COP payments via cards, PSE, Nequi, Daviplata, Bancolombia Button/QR, cash (Corresponsales), Puntos Colombia, and SU+ Pay.
Docs: https://docs.wompi.co | Dashboard: https://comercios.wompi.co
Reference Files — Read These As Needed
| File | Read when... |
|---|---|
references/auth-and-security.md | Setting up keys, generating signatures, securing the integration |
references/payment-methods.md | Choosing or implementing a specific payment method |
references/transactions.md | Creating transactions, polling status, handling voids |
references/webhooks.md | Receiving and validating Wompi events |
references/payment-links.md | Generating shareable payment links programmatically |
references/payment-sources.md | Tokenization, subscriptions, recurring billing |
references/payouts.md | Dispersión de pagos / third-party payments API |
references/taxes.md | Sending IVA / consumption tax in transactions |
references/sandbox.md | Sandbox testing data, simulating outcomes |
references/production-checklist.md | Pre-launch security and integration checklist |
references/errors.md | Error codes, retry logic, idempotency patterns |
Environments & Keys (Quick Reference)
| Environment | API Base URL |
|---|---|
| Sandbox | https://sandbox.wompi.co/v1 |
| Production | https://production.wompi.co/v1 |
| Key | Prefix | Use |
|---|---|---|
| Public key | pub_test_ / pub_prod_ | Frontend only. Safe to expose. |
| Private key | prv_test_ / prv_prod_ | Server-side only. Never expose. |
| Integrity secret | test_integrity_ / prod_integrity_ | Sign transactions. Server-side only. |
| Events secret | test_events_ / prod_events_ | Validate webhooks. Server-side only. |
⚠️ Sandbox and Production are completely independent environments — separate keys, separate webhook URLs, separate dashboard settings.
Amounts
All amounts are Colombian pesos in cents as integers.
$35,000 COP → 3500000 | $1,000 COP → 100000
Payment Methods Overview
| Method | type | Sync? | Notes |
|---|---|---|---|
| Credit/Debit Card | CARD | ✅ | Tokenization required; supports installments (credit only) |
| PSE Bank Transfer | PSE | ❌ Async | Requires bank list + ID; redirect_url required |
| Nequi | NEQUI | ❌ Async | Phone number; push notification; up to 10 min |
| Daviplata | DAVIPLATA | ❌ Async | OTP flow — see references/payment-methods.md |
| Bancolombia Button | BANCOLOMBIA_TRANSFER | ❌ Async | Redirects to Bancolombia app/web |
| Bancolombia QR | BANCOLOMBIA_QR | ❌ Async | Natural persons only; returns QR image URL |
| Cash Corresponsal | BANCOLOMBIA_COLLECT | ❌ Async | Cash at 15,000+ Bancolombia points |
| Puntos Colombia | PCOL | ❌ Async | Loyalty points; optional 2nd payment method |
| SU+ Pay | SU_PLUS | ❌ Async | Supermarket loyalty — redirect flow |
For any async method: always start as
PENDING→ use webhooks or polling to get final status.
Core Flow (Every Integration)
1. Server: Fetch acceptance tokens → GET /v1/merchants/:pub_key
2. Server: Generate integrity signature → SHA256(ref + amount + currency + secret)
3. Client/Server: Present payment UI → Widget, Checkout Web, or direct API
4. Server: Verify transaction → GET /v1/transactions/:id (never trust redirect alone)
5. Server: Handle webhook → POST from Wompi → validate checksum → update order
Integration Methods (Summary)
Widget (Recommended — handles all complexity)
<form>
<script
src="https://checkout.wompi.co/widget.js"
data-render="button"
data-public-key="pub_test_YOUR_KEY"
data-currency="COP"
data-amount-in-cents="5000000"
data-reference="ORDER-001"
data-signature:integrity="SERVER_GENERATED_HASH"
data-redirect-url="https://yoursite.com/confirmation">
</script>
</form>
Web Checkout (Redirect)
<form method="GET" action="https://checkout.wompi.co/p/">
<input type="hidden" name="public-key" value="pub_test_YOUR_KEY" />
<input type="hidden" name="currency" value="COP" />
<input type="hidden" name="amount-in-cents" value="5000000" />
<input type="hidden" name="reference" value="ORDER-001" />
<input type="hidden" name="signature:integrity" value="SERVER_GENERATED_HASH" />
<input type="hidden" name="redirect-url" value="https://yoursite.com/ok" />
<button type="submit">Pagar con Wompi</button>
</form>
Direct API
See references/transactions.md for complete server-side transaction creation in Node.js, Python, and PHP.
Transaction Statuses
| Status | Meaning | Action |
|---|---|---|
PENDING | Awaiting action or processing | Poll or wait for webhook |
APPROVED | Payment successful ✅ | Fulfill order |
DECLINED | Rejected by bank ❌ | Notify customer; allow retry |
VOIDED | Annulled (cards only) | Update order; no refund via API |
ERROR | Payment method error | Log; allow retry |
Common Mistakes — Never Do These
- Private key or integrity secret in frontend code — attackers can forge any transaction amount.
- Generating integrity signature on the frontend — same consequence as above.
- Trusting redirect URL
?id=to confirm payment — easily spoofed; always verify server-side. - Reusing references — must be unique per Wompi account, ever.
- Skipping acceptance tokens on API calls — violates Colombian Habeas Data law; call will fail.
- Hardcoding
signature.propertiesin webhook handler — array changes; always read dynamically. - Same webhook URL for Sandbox and Production — configure them separately in the dashboard.
- Not polling / not using webhooks for async methods — PSE/Nequi/QR always start as
PENDING. - Adding taxes on top of
amount_in_cents— taxes are included in the total, not added to it. - Reusing card tokens across merchants — tokens are merchant-scoped and expire.