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.properties in 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.

wompi

Wompi — Complete Developer Skill

Reference Files — Read These As Needed