Wompi (Colombia)

Wompi is the payment platform operated by Bancolombia. It's the cleanest path to processing Colombian pesos (COP) for Genius Checkout merchants serving Colombian buyers. Cards plus the full local payment-method set (PSE bank transfer, Nequi wallet, Bancolombia Transfer, Daviplata, Baloto and Efecty cash networks) all run through a single Wompi account.

What Wompi covers

Capability	Supported
Currency	COP only (USD is not supported)
Cards (Visa, Mastercard, Amex)	✓
PSE bank transfer	✓ (opt-in per merchant in Wompi dashboard)
Nequi	✓ (opt-in)
Bancolombia Transfer / Daviplata	✓ (opt-in)
Cash (Baloto, Efecty)	✓ (opt-in)
3-D Secure 2	✓
Recurring billing (stored card via payment_source)	✓
Refunds	✓ (partial supported; settlement is async via webhook)
Void	✓ (cards, limited time window)
Tokenization (PCI-safe stored cards)	✓

Step 1 — Get your Wompi account approved

Sign up at comercios.wompi.co and complete the business-verification form. Wompi reviews production accounts in 1-3 business days. Sandbox keys work immediately while you wait.

You'll need:

• Razón social (legal company name)
• NIT (Colombian tax ID)
• Average ticket size + monthly volume projections
• Refund + privacy + terms URLs (pointing at geniuscheckout.com is fine)

Step 2 — Find your 4 credentials

In the Wompi dashboard → Mi cuenta → Secretos para integración técnica, you'll see four values per environment (test + production):

Field in Wompi	Where it goes in Genius Checkout
Llave pública (pub_*)	Public key
Llave privada (prv_*)	Private key
Secreto de integridad (*_integrity_*)	Integrity secret
Secreto de eventos (*_events_*)	Events secret

Copy each separately — Wompi shows them masked by default; click the eye icon to reveal.

Test vs Live

The TEST keys start with pub_test_ / prv_test_, the PRODUCTION keys with pub_prod_ / prv_prod_. Don't mix them — sandbox and production are entirely separate accounts under your one Wompi login.

Step 3 — Add the gateway in Genius Checkout

1. Open Merchant → Gateways.
2. In the Available Gateways section, find the Wompi tile and click Configure.
3. Fill in the four credentials separately for Test and Live modes. You can leave Live blank until production approval lands.
4. Set Enabled Modes — start with test only.
5. Set Currencies — COP is auto-suggested; leave at that.
6. Save.

Step 4 — Configure the webhook URL in Wompi

Genius Checkout needs Wompi to push transaction-status updates so refunds and asynchronous payment methods settle correctly. Configure both test + production webhooks:

In the Wompi dashboard → Mi cuenta → Eventos → Configurar:

• URL: https://app.geniuscheckout.com/webhooks/wompi
• Event: transaction.updated (only one — that's all Genius Checkout consumes)
• Format: JSON

Wompi will start delivering events as soon as the URL is saved. The first transaction you make in test mode should generate one — open Developer Surface → Webhook Deliveries in Genius Checkout to confirm receipt.

Step 5 — Payment methods

Wompi enables payment methods at the account level when your application is approved, not via a per-merchant toggle. The methods you applied for during onboarding are the methods your buyers will see. If you want to add or remove one later, contact Wompi support — there is no self-service toggle in most account tiers.

Genius Checkout currently sends payment_method.type: CARD to Wompi, so cards are the only buyer-facing method active today. Adding PSE, Nequi, Bancolombia Transfer, Daviplata, or cash (Baloto / Efecty) requires extending the gateway adapter (each method has its own request shape and buyer-flow). Open a feature request if you need one of these.

Step 6 — Optional dashboard tweaks

Most Wompi account tiers don't expose every setting in the dashboard. Here's what to look for and what to ignore if the panel doesn't show it:

Setting	Where to look	If not present in your panel
3-D Secure policy	Mi cuenta → Configuración de pagos	Wompi defaults to "adaptive" (challenge when risk score is high). Acceptable.
Descriptor en estado de cuenta	Mi cuenta → Información comercial	Buyer sees the Wompi default (WOMPI*<merchant_name>). Acceptable.
Notificaciones por correo (buyer)	Mi cuenta → Notificaciones	Wompi will send a confirmation email per transaction in addition to ours. Buyers may receive two emails — see "Known limitations" below.
Notificaciones por correo (merchant)	Mi cuenta → Notificaciones	Useful while learning the system; harmless if always on.

None of these are dealbreakers. The core integration works regardless of what the Wompi panel exposes.

Step 7 — Smoke-test in sandbox

1. In Genius Checkout, create a customer-entered payment link with currency = COP. The minimum amount Wompi accepts is 1,500 COP (~ USD$0.40).
2. Open the link, enter Wompi's test card:
   • Number: 4242 4242 4242 4242
   • CVC: any 3 digits
   • Expiry: any future date
3. Submit. The transaction should flip from PENDING → APPROVED in 2-3 seconds.
4. From the transaction detail page in Genius Checkout, issue a partial refund. It'll show PENDING immediately, then APPROVED once the webhook fires (~5-10 seconds).
5. From the same page, void a separate test transaction.

Going live

Once your Wompi production account is approved:

1. Switch the credential set in Genius Checkout's gateway config from test to live.
2. Repeat Step 4 with the production webhook URL configured in Wompi's production tab (same URL: https://app.geniuscheckout.com/webhooks/wompi).
3. Run a real-money $1.50 USD-equivalent (≈6,000 COP) charge through your own card to confirm the production keys work end-to-end.
4. Set Enabled Modes to include live in Genius Checkout.

Known limitations

• Minimum transaction: 1,500 COP (Wompi platform-level minimum)
• Refunds are async: the merchant + buyer see PENDING immediately, then APPROVED via webhook within seconds (rare cases up to 24h)
• Refund amount required: Wompi doesn't have a "full-refund shortcut" — pass the original transaction amount for a full refund
• No USD support: if a buyer enters a USD-priced payment link, Wompi won't process it; route through PowerTranz or PayPal instead
• Cards only (for now): PSE, Nequi, Bancolombia Transfer, Daviplata, and cash networks are supported by Wompi but require gateway-adapter extension on our side. Open a feature request if you need one of these.
• Possible duplicate buyer emails: if your Wompi account tier sends transaction-confirmation emails to buyers and you can't disable them in the panel, buyers will receive two emails — Wompi's plain-text one + our branded receipt. There is no clean fix today; we may add a suppress_wompi_buyer_email capability later if this becomes a real problem.

Troubleshooting

Symptom	Cause
"El monto mínimo es $1,500"	Transaction is below Wompi's 1,500 COP minimum
"La referencia ya ha sido usada"	Wompi rejects duplicate reference — internal bug, contact support
Webhook 401 in Wompi delivery logs	The events_secret in Genius Checkout doesn't match Wompi's. Re-copy from Wompi dashboard.
Transaction stuck PENDING for >15 min	Webhook URL wrong or 5xx on our side. Re-check Step 4. The reconciliation cron picks these up every 15 min as backup.