Wompi (Colombia)

Wompi is the payment platform operated by Bancolombia. Genius Checkout redirects the buyer to Wompi's hosted Web Checkout, where Wompi presents the payment methods enabled for that merchant account and transaction.

What Wompi covers

Capability	Supported
Currency	COP only (USD is not supported)
Buyer checkout	Wompi-hosted Web Checkout
Cards and Colombian local methods	Available when Wompi enables them for the merchant account and transaction
Recurring billing	Supported for eligible stored-card payment sources; local redirect methods are not reusable card credentials
Refunds	Supported; final status can be asynchronous
Status updates	Signed Wompi event, with transaction lookup as a fallback

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. After the first test transaction, open its Genius Checkout transaction detail page and confirm that the timeline contains the final Wompi status.

Step 5 — Payment methods

Genius Checkout does not force a card-only payment type in the hosted flow. Wompi decides which methods appear based on the merchant's onboarding, account configuration, transaction eligibility, and current Wompi availability.

Possible methods can include cards, PSE, Nequi, Bancolombia Transfer and other methods supported by Wompi. Not every Wompi account receives every method. Contact Wompi if an expected option is missing, and select only genuinely available methods in your Genius Checkout gateway appearance settings.

Step 6 — Optional dashboard tweaks

Checkout language

Genius Checkout passes the buyer's resolved language to Wompi Web Checkout. Wompi currently provides complete hosted-checkout language packs for English and Spanish:

• Spanish Genius Checkout sessions open Wompi in Spanish.
• English sessions open Wompi in English.
• French, Portuguese, and other unsupported Wompi languages fall back to English instead of Wompi's Spanish default.

The buyer's explicit language selection takes priority over the storefront locale and browser language. Genius Checkout preserves that selection through Wompi redirects, retries, returns, and buyer notifications. No additional merchant configuration is required.

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	Choose the provider notification behaviour appropriate for your account and your Genius Checkout notification settings.
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. Confirm the final refund status in the transaction timeline.

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

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.

Related guides

• Adding a Gateway
• Test vs Live Credentials
• Gateway Appearance
• Issuing Refunds

Provider references

• Wompi environments and integration keys
• Wompi Web Checkout
• Wompi payment methods
• Wompi events