Wompi Payment Gateway by Codeupp for Columbia, EL salvador , Panama

# 💳 Wompi Payment Gateway for Botble — by Codeupp

> Accept real payments through **Wompi** (Nequi, Bancolombia Transfer, PSE, Daviplata, Cards) directly in your Botble / Martfury / Shofy / Nest store — with full **Test ↔ Live** mode switching and secure webhook signature verification.

**Plugin ID:**`maryam/wompi-pro`

**Namespace:**`Maryam\WompiPro\`

**Install path:**`platform/plugins/wompi/`

**Brand:** Maryam International LLC · [codeupp.xyz](https://codeupp.xyz)

---

## ✨ Features

- ✅ Full **Wompi Colombia API v1** integration (`https://production.wompi.co/v1`)

- ✅ Multi-country support: **Colombia** (primary), **El Salvador**, **Panamá**

- ✅ **Admin-selectable Test / Live mode** from Payment Methods settings — no code changes

- ✅ Separate **Test** and **Live** API key fields (Public Key, Private Key, Events Secret, Integrity Secret)

- ✅ **TWO checkout modes** — switch any time from admin (see below):

- 🌐 **Payment Link** — customer redirected to Wompi hosted checkout

- 🪟 **Web Checkout Widget — auto-redirect** — modal opens on YOUR site, redirects automatically after payment (no "Volver al comercio" click needed)

- ✅ Automatic **webhook handler** at `/payment/wompi/webhook` (CSRF-exempt) for `transaction.updated`

- ✅ **SHA-256 signature verification** of every webhook per [official Wompi spec](https://docs.wompi.co/docs/colombia/eventos/) — spoofed webhooks are rejected

- ✅ **Server-side re-verification** of every event via `GET /v1/transactions/{id}` (defense in depth)

- ✅ **Callback / return URL** handler at `/payment/wompi/return` — handles Wompi's `?id=&env=` query params

- ✅ **Idempotent** processing — no duplicate order updates, even if Wompi retries the webhook

- ✅ Marks **APPROVED → COMPLETED**, **DECLINED / ERROR / VOIDED → FAILED**, **PENDING → unchanged**

- ✅ **Triple-redundant order confirmation** — webhook + browser polling + customer return all converge idempotently

- ✅ **Rate-limited polling endpoint** (60 req/min) prevents abuse

- ✅ Detailed logging at every step for easy debugging

- ✅ Compatible with **Martfury, Shofy, Nest**, and every Botble theme

- ✅ Clean Botble design — integrates as a native payment method alongside Stripe, PayPal, Wava, etc.

---

## 🎯 Two Checkout Modes — Choose Per-Store

The plugin offers two officially-supported Wompi checkout flows. **Switch any time** from `Admin → Payment Methods → Wompi → Checkout Mode (Colombia)`.

### Option 1 — 🌐 Payment Link (default)

```

Customer clicks "Place Order"

→ fully redirected to checkout.wompi.co/l/{link}

→ picks payment method (Nequi / PSE / Bancolombia / Card / Daviplata)

→ completes payment

→ clicks "Volver al comercio" → returns to your store → success page

```

**Pros:** Maximum compatibility. Works for every Wompi merchant out-of-the-box. Only Public Key + Private Key + Events Secret needed.

**Cons:** Customer leaves your branded site during payment. Requires one click on "Volver al comercio" to return.

---

### Option 2 — 🪟 Web Checkout Widget (auto-redirect)

```

Customer clicks "Place Order"

→ stays on your site → Wompi modal opens INSIDE your branded page

→ completes payment in modal

→ page AUTO-REDIRECTS to success page within 3 seconds — NO CLICK NEEDED ✨

```

**How auto-redirect works:** the page polls our backend every 3 seconds. As soon as Wompi reports the transaction `APPROVED`, the browser is redirected to the order success page — bypassing the manual "Volver al comercio" click that all standard Wompi integrations require.

**Pros:** Customer never visually leaves your site. True one-step checkout. Higher conversion.

**Cons:** Requires the **Integrity Secret** to be configured (one extra key from Wompi dashboard). Available for Colombia only.

---

### Which should I pick?

| Need | Recommended |

|---|---|

| Fastest setup, Wompi El Salvador / Panamá | **Payment Link** |

| Best customer experience, Colombia | **Web Checkout Widget** |

| Maximum reliability across edge cases | **Either — both are battle-tested** |

No code change needed to switch — just toggle the dropdown and save.

---

## 📦 Installation

1. Copy the `wompi` folder into `platform/plugins/` of your Botble installation.

2. Go to **Admin → Platform Administration → Plugins**.

3. Find **Wompi Payment Gateway by Codeupp** and click **Activate**.

4. Go to **Admin → Settings → Payment Methods → Wompi** and configure:

-**Country** — `Colombia` (or El Salvador / Panamá)

-**Environment Mode** — `Test` or `Live`

-**Test Public Key** (`pub_test_…`)

-**Test Private Key** (`prv_test_…`)

-**Test Events Secret** (`test_events_…`) ← **CRITICAL — webhooks rejected without it**

-**Live Public Key** (`pub_prod_…`)

-**Live Private Key** (`prv_prod_…`)

-**Live Events Secret** (`prod_events_…`)

5.**Pick your Checkout Mode** — Payment Link (default) or Web Checkout Widget.

- For Widget mode, also fill the **Integrity Secret** field (`test_integrity_…` / `prod_integrity_…`).

6. Copy the **Webhook URL** shown in the admin instructions and paste it into

**Wompi Dashboard → Developers → Events URL**.

7. Enable the payment method (status = ON) and save.

---

## 🔐 Where to find your Wompi keys

Login to [comercios.wompi.co](https://comercios.wompi.co) → **Developers → Secrets for technical integration**.

| Key | Test prefix | Live prefix | Purpose |

|---|---|---|---|

| Public Key | `pub_test_…` | `pub_prod_…` | Read-only API + frontend widget |

| Private Key | `prv_test_…` | `prv_prod_…` | **Create Payment Links** (server-side only) |

| Events Secret | `test_events_…` | `prod_events_…` | **Verify webhook signatures** |

| Integrity Secret | `test_integrity_…` | `prod_integrity_…` | Optional, for on-site Web Checkout widget |

> ⚠️ Keep Private Key and secrets server-side only. Never expose them in frontend code.

---

## 🔗 URLs registered by this plugin

| Purpose | Route name | URL |

|---------|-----------|-----|

| Hosted-checkout return | `wompi.return` | `/payment/wompi/return` |

| Incoming webhook | `wompi.webhook` | `POST /payment/wompi/webhook` |

| Web Checkout Widget renderer | `wompi.widget` | `/payment/wompi/widget/{token}` |

| Status polling (auto-redirect) | `wompi.check_status` | `/payment/wompi/check-status/{token}` |

| AJAX create payment (legacy) | `payments.wompi.create` | `POST /payment/wompi/create` |

---

## 🔔 Webhook events handled

| Wompi Event | Wompi Status | Mapped Botble Status |

|------------|------|----------------------|

| `transaction.updated` | `APPROVED` | **COMPLETED** — order marked paid |

| `transaction.updated` | `DECLINED` | **FAILED** |

| `transaction.updated` | `ERROR` | **FAILED** |

| `transaction.updated` | `VOIDED` | **FAILED** |

| `transaction.updated` | `PENDING` | (no change — wait for next event) |

Every webhook is **re-verified** twice:

1.**HMAC SHA-256** signature check using your Events Secret

2.**Server-fetch** of the transaction via `GET /v1/transactions/{id}` to confirm the data

Spoofed or tampered webhooks are rejected.

---

## 🧪 Testing (Sandbox)

Use Wompi sandbox keys (`pub_test_…` / `prv_test_…`) and place a test order.

Wompi test cards:

- ✅ APPROVED — `4242 4242 4242 4242`, any expiry / CVC, cardholder name `APROBADA`

- ❌ DECLINED — cardholder name `RECHAZADA`

- ⚠️ ERROR — cardholder name `ERROR`

### Payment Link mode test flow

1. Customer redirected to `checkout.wompi.co/l/{link}`

2. Pays → clicks "Volver al comercio"

3. Lands on `/payment/wompi/return?id=<txn>&env=test` → order marked completed

4. Webhook also fires server-side as backup

### Web Checkout Widget mode test flow

1. Customer stays on `/payment/wompi/widget/{order_token}` page

2. Wompi modal opens automatically on your site

3. Customer pays in modal

4. Within 3 seconds polling detects APPROVED → page auto-redirects to success ✨

5. Webhook also fires server-side as backup

Check `storage/logs/laravel.log` — every step is logged with `[WOMPI]` prefix for easy debugging.

---

## 🐛 Troubleshooting

| Symptom | Cause | Fix |

|---|---|---|

| Customer pays but order stays "Pending" | Webhook blocked / events_secret missing | Verify webhook URL in Wompi dashboard + Events Secret in admin |

| `Wompi rejected the request: invalid public key` | Wrong key for environment | Make sure you're using `prv_test_*` for Test mode, `prv_prod_*` for Live |

| `Wompi webhook signature mismatch` | Wrong Events Secret | Re-copy from Wompi dashboard → Developers → Events Secret |

| `Order not found for Wompi reference` | Test data with stale `reference` | Place a fresh order — `reference = order.token` is unique per order |

| 419 errors in logs on webhook | CSRF middleware enabled on webhook | Already fixed — clear route cache: `php artisan route:clear` |

| **Widget mode**: "Wompi Integrity Secret is required" | Integrity Secret field empty | Paste `test_integrity_…` / `prod_integrity_…` from Wompi dashboard |

| **Widget mode**: 422 init error / modal won't open | Reused order reference (already paid in Wompi) | Place a fresh order — plugin auto-detects existing tx and redirects to /return |

| **Widget mode**: page doesn't auto-redirect | `findTransactionByReference` 401 / Private Key missing | Make sure Private Key (`prv_test_…` / `prv_prod_…`) is filled — the polling lookup requires it |

| Settings dropdown reverts after save | Old plugin version (pre-2.0) | Update to latest — fixed via `selected` attribute |

---

## 🗂️ File Structure

```

platform/plugins/wompi/

├── plugin.json

├── composer.json

├── README.md

├── helpers/

│ └── constants.php

├── routes/

│ └── web.php

├── public/

│ └── images/

│ └── wompi.png

├── resources/

│ ├── lang/

│ │ ├── en/

│ │ ├── es/

│ │ └── wompi.php

│ └── views/

│ ├── methods.blade.php # checkout payment-row

│ ├── detail.blade.php # admin order detail (transaction info)

│ ├── instructions.blade.php # admin settings instructions

│ ├── email.blade.php

│ └── payments.blade.php

└── src/

├── Plugin.php

├── Forms/

│ └── WompiPaymentMethodForm.php # admin form: keys, mode, country

├── Http/

│ ├── Controllers/

│ │ └── WompiController.php # return + webhook + create

│ └── Requests/

│ └── WompiPaymentCallbackRequest.php

├── Providers/

│ ├── WompiServiceProvider.php

│ └── HookServiceProvider.php # filters + CSRF exemption

└── Services/

├── Abstracts/

│ └── WompiPaymentAbstract.php

└── Gateways/

├── WompiPaymentService.php # country router

├── WompiColombiaService.php # ★ Colombia (full implementation)

├── WompiElSalvadorService.php

└── WompiPanamaService.php

```

---

## 🔄 Migrating from earlier versions (1.x → 2.0)

This v2.0 release rewrites the Colombia integration. **No data migration needed** — but you must:

1. After upgrade, go to **Admin → Payment Methods → Wompi** and re-enter your keys in the new fields:

- Old `Client ID` → paste into **Test/Live Public Key** (depending on environment)

- Old `Client Secret` → paste into **Test/Live Private Key**

- Add the new **Events Secret** (CRITICAL for webhooks)

2. Save settings.

3. Run `php artisan route:clear && php artisan view:clear`.

The old `client_id` and `client_secret` keys are still read as fallback — but you should migrate to the new, properly-named fields for clarity and security.

---

## 👑 Why Choose Maryam International LLC

**We are a registered professional software company based in the UAE**, specializing in building world-class digital products for businesses that refuse to settle for average.

### 🌍 Technologies We Master

-**Frontend**: React, Next.js, Vue.js, Nuxt.js, Angular, Svelte, HTML5, CSS3, SASS, Tailwind CSS, Bootstrap

-**Languages**: JavaScript, TypeScript, PHP, Python, Go, Ruby, Java, Kotlin, Swift, Dart, C#, C++, Rust

-**Backend**: Laravel, Node.js, Express, NestJS, Django, FastAPI, Flask, Spring Boot, .NET, Ruby on Rails

-**Mobile**: Flutter, React Native, Swift (iOS), Kotlin (Android), Ionic

-**CMS & E-commerce**: Botble CMS, WordPress, Shopify, WooCommerce, Magento, Prestashop

-**Databases**: MySQL, PostgreSQL, MongoDB, Redis, SQLite, Firebase, Supabase

-**DevOps & Cloud**: AWS, Google Cloud, Azure, DigitalOcean, Docker, Kubernetes, CI/CD, Nginx, Apache

-**AI / ML**: OpenAI, LangChain, TensorFlow, PyTorch, HuggingFace, custom LLM integrations

-**Blockchain / Web3**: Solidity, Ethereum, Smart Contracts, NFT marketplaces, crypto payment gateways

-**Design**: Figma, Adobe XD, Photoshop, Illustrator, UI/UX strategy

### 💼 What We Build

- Custom e-commerce platforms and marketplaces

- SaaS products & startup MVPs

- Mobile apps (iOS + Android)

- Progressive Web Apps

- Custom CMS plugins & extensions

- Payment gateway integrations

- AI-powered chatbots & automation

- Blockchain dApps & crypto platforms

- Enterprise dashboards & admin panels

- API development & third-party integrations

### 🌟 Why Hire Us

- ✅ **Registered, professional UAE-based company** — real accountability, real contracts, real delivery.

- ✅ **Your satisfaction is our top priority** — we revise until you smile.

- ✅ **We can build anything you imagine** — if you can describe it, we can ship it.

- ✅ **Full-stack mastery** — one team, one invoice, end-to-end delivery.

- ✅ **Fast, transparent communication** in English, Hindi, Urdu and Arabic.

- ✅ **Post-launch support included** — we don't disappear after going live.

- ✅ **Competitive pricing** for enterprise-grade quality.

---

## 📞 Contact Us — Let's Build Something Incredible

-**Company:** Maryam International LLC

-**Website:** [https://codeupp.xyz](https://codeupp.xyz)

-**Email:** [maryaminternationalllc@gmail.com](mailto:maryaminternationalllc@gmail.com) · [codeupp.xyz@gmail.com](mailto:codeupp.xyz@gmail.com)

-**WhatsApp:** [+971 55 368 2656](https://wa.me/971553682656)

-**Based in:** United Arab Emirates 🇦🇪

-**Serving:** Worldwide 🌍

>**Have an idea? Send us a WhatsApp. We reply within minutes, not days.**

---

## 🛡️ License & Support

This plugin is a premium product by **Maryam International LLC**.

Purchase includes:

- ✔️ Lifetime updates

- ✔️ 6 months of priority support

- ✔️ Free installation help via WhatsApp

- ✔️ Compatibility guarantee across Martfury, Shofy, Nest & future Botble releases

**Your success is our signature.**

---

**© Maryam International LLC — [codeupp.xyz](https://codeupp.xyz)**

*Your satisfaction is our top priority. We can build anything you imagine.*