Wava Payment Gateway by Codeupp compatible Shofy / Martfury for Columbia

# 💳 Wava Payment Gateway for Botble — by Codeupp

> Accept real payments through **Wava** (Nequi, Daviplata, Breb, and Stripe card payments) directly in your Botble / Martfury / Shofy / Nest store — with full **Test ↔ Live** mode switching from the admin panel.

**Plugin ID:**`codeupp/wava`

**Namespace:**`Codeupp\Wava\`

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

---

## ✨ Features

- ✅ Full **Wava API v1** integration (`https://api.wava.co/v1` live + `https://api.dev.wava.co/v1` sandbox)

- ✅ **Admin-selectable Test / Live mode** from Payment Methods settings — just like Stripe

- ✅ **Two integration modes** — selectable per-store from the admin panel:

-**Option A — Payment Links** (hosted checkout on `pay.wava.co`) → simplest, requires `links` scope on your Wava key

-**Option B — Direct API** (custom checkout on **your** site → Nequi push / Daviplata OTP / Breb QR) → requires `orders` scope

- ✅ Separate **Test Merchant Key** and **Live Merchant Key** fields

- ✅ Built-in **custom checkout form** for Direct API mode (Wava-branded, mobile-ready, standalone HTML — no theme conflicts)

- ✅ Built-in **waiting page** with live status polling — auto-detects gateway and renders:

-**Nequi** → "Open your Nequi app" + spinner + masked phone

-**Daviplata** → 6-digit OTP input with AJAX submission to `/orders/{id}/daviplata/otp`

-**Breb (Bre-B)** → base64 QR code + transfer key

- ✅ Automatic **webhook handler** at `/payment/wava/webhook` (CSRF-exempt) for `order.confirmed`, `order.cancelled`, `order.refunded`, `order.failed`

- ✅ **Server-side verification** of every webhook via `GET /v1/orders/{id}` (never trust the payload alone)

- ✅ **Callback/return URL** handler at `/payment/wava/callback`

- ✅ **Refund** support from Botble admin → Order detail → Refund button

- ✅ **Idempotent** webhook processing using `id_external` (Botble order ID)

- ✅ Uses Wava's standardized error codes (`api_code`, `code`, `gateway_name`) for clear debug messages

- ✅ Auto-resized payment method **logo** on checkout (works with admin-uploaded logos of any size)

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

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

---

## 📦 Installation

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

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

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

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

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

-**Integration Mode** — `A) Payment Links` or `B) Direct API` (see below)

-**Test Merchant Key** (from Wava dev dashboard)

-**Live Merchant Key** (from Wava production dashboard)

- Optional: default `payment_gateway` ID (e.g. `1` = Nequi)

- Optional: default buyer country (ISO 2-letter, e.g. `CO`)

5. Copy the **Webhook URL** shown in the admin panel and paste it into

**Wava Dashboard → Settings → Integrations → API → Webhook URL**.

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

---

## 🔀 Integration Modes — A vs B

The plugin ships with **two complete integration flows**. You pick which one to use from the admin panel — switching is instant, no code changes required.

### 🅐 Option A — Payment Links (Hosted Checkout)

The **simplest** flow — Wava hosts the entire checkout UI for you.

**Flow:**

1. Customer clicks **Place Order** with Wava selected

2. Plugin calls `POST /v1/links` to create a payment link

3. Customer is redirected to `https://pay.wava.co/{link_id}` (Wava-hosted checkout)

4. Customer picks **Nequi / Daviplata / Breb / Card** on Wava's page and completes payment

5. Wava redirects back to `/payment/wava/callback`

6. Plugin verifies + marks order as paid

**Required Wava scope:**`links`

**Best for:** stores that want zero PCI/KYC handling on their own server.

---

### 🅑 Option B — Direct API (Custom Checkout on Your Site)

A **fully branded** checkout experience — customer never leaves your domain.

**Flow:**

1. Customer clicks **Place Order** with Wava selected → redirected to `/payment/wava/form/{orderId}` (your own domain)

2.**Custom checkout form** asks for:

- Payment method (Nequi / Daviplata / Breb — auto-loaded from `GET /v1/orders/paymentGateways`)

- First name, Last name, Email, Phone (+57…)

- Document type (CC / CE / TI from `GET /v1/national-document-types/CO`)

- National ID number

3. Plugin calls `POST /v1/orders` with the buyer data

4. Customer lands on `/payment/wava/waiting/{orderId}` — a **live-polling page** that:

- For **Nequi** → shows "Open your Nequi app" + spinner + masked phone

- For **Breb** → renders the base64 QR code + transfer key from Wava response

- For **Daviplata** → shows OTP input → AJAX-submits to `POST /v1/orders/{id}/daviplata/otp`

5. JS polls `/payment/wava/status/{remoteOrderId}` every 3 s — auto-redirects to checkout-success when Wava confirms

**Required Wava scope:**`orders`

**Best for:** stores that want full brand control + a one-page checkout experience.

---

### Comparison

| Feature | Option A (Links) | Option B (Direct API) |

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

| Setup difficulty | Easiest | Medium |

| Customer leaves your site? | Yes (to `pay.wava.co`) | **No** (custom form on your domain) |

| Branding control | Wava-branded | **Fully your brand** |

| Required Wava API scope | `links` | `orders` |

| Mobile UX | Excellent (Wava-optimized) | Excellent (responsive Bootstrap form) |

| Daviplata OTP handled by | Wava | This plugin |

| Breb QR rendered by | Wava | This plugin |

---

## 🔐 API Keys — where to get them

| Mode | Endpoint | Dashboard |

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

| **Test** | `https://api.dev.wava.co/v1` | [https://app.dev.wava.co](https://app.dev.wava.co) |

| **Live** | `https://api.wava.co/v1` | [https://app.wava.co](https://app.wava.co) |

Get your `merchant-key` from **Settings → Integrations → API**.

---

## ⚠️ Wava Account Setup — IMPORTANT

A freshly-created Wava merchant key starts with **NO API scopes enabled**. Both integration modes will return `INSUFFICIENT_SCOPE` until Wava activates the required scopes on your key.

**You must email `soporte@wava.co` and request scope activation:**

```

Please enable the following scopes on our merchant key:

✅ orders (for Direct API — Option B)

✅ links (for Payment Links — Option A)

✅ orders:refund (for admin refunds)

```

Provide both your **sandbox** key (from `app.dev.wava.co`) and your **production** key (from `app.wava.co`). Wava typically responds within 1 business day.

Until scopes are granted, the plugin code is fully functional — but Wava's servers will refuse the API calls.

---

## 🧪 Testing (Sandbox)

In **Test mode**, Wava simulates payments — no real money is charged. Use these values:

### Nequi

| Field | Test Value |

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

| Phone | `+573001234567` |

| Gateway ID | `1` |

To confirm a Nequi sandbox order, Wava auto-confirms when you fetch it via `GET /v1/orders/{id}` — the plugin's callback handler does this automatically.

### Daviplata OTPs

| OTP | Result |

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

| `123456` | ✅ Success |

| `000000` | ✅ Success |

| `111111` | ✅ Success |

| `999999` | ❌ Invalid OTP |

### Test documents

| Field | Value |

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

| National ID | `12345678` |

| Document Type | `1` (CC) / `2` (CE) / `3` (TI) |

---

## 🔗 URLs registered by this plugin

### Common (both modes)

| Purpose | Route | URL |

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

| Hosted-checkout callback | `payment.wava.callback` | `/payment/wava/callback` |

| Incoming webhook | `payment.wava.webhook` | `/payment/wava/webhook` |

| Test-connection button | `payment.wava.test-connection` | `/payment/wava/test-connection` |

### Direct API mode only (Option B)

| Purpose | Route | URL |

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

| Custom checkout form | `payment.wava.form` | `/payment/wava/form/{orderId}` |

| Form submit | `payment.wava.form.submit` | `POST /payment/wava/form/{orderId}` |

| Waiting page | `payment.wava.waiting` | `/payment/wava/waiting/{orderId}` |

| Status polling (AJAX) | `payment.wava.status` | `/payment/wava/status/{remoteOrderId}` |

| Daviplata OTP submit | `payment.wava.daviplata-otp` | `POST /payment/wava/daviplata-otp/{remoteOrderId}` |

The webhook URL is automatically shown inside the admin settings page — just copy-paste it into Wava.

---

## 🔔 Webhook events handled

| Wava Event | Mapped Botble Status |

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

| `order.confirmed` | **COMPLETED** — order marked paid |

| `order.refunded` | **REFUNDED** |

| `order.cancelled` | **FAILED** |

| `order.failed` | **FAILED** |

Every webhook is **re-verified** against `GET /v1/orders/{id}` before the order is marked paid — so spoofed webhooks are safely ignored.

---

## 🗂️ File Structure

```

platform/plugins/WAVABYCODEUPP/

├── plugin.json

├── README.md

├── helpers/

│ └── constants.php

├── routes/

│ └── web.php

├── public/

│ └── images/

│ └── wava.svg

├── resources/

│ └── views/

│ ├── methods.blade.php # checkout payment-row + auto-sized logo

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

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

│ ├── checkout-form.blade.php # ★ Option B custom checkout form (standalone)

│ └── waiting.blade.php # ★ Option B waiting/polling page (Nequi / Daviplata / Breb)

└── src/

├── Plugin.php

├── Forms/

│ └── WavaPaymentMethodForm.php

├── Http/Controllers/

│ └── WavaController.php

├── Providers/

│ ├── WavaServiceProvider.php

│ └── HookServiceProvider.php

└── Services/

├── Abstracts/WavaPaymentAbstract.php

└── Gateways/WavaPaymentService.php

```

---

## 👑 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.*