Ziina Payment Gateway For UAE Only

Ziina Payment Gateway — Botble Plugin

By Maryam International LLC · Version 1.0.0

Accept Card, Apple Pay, and Google Pay payments on your Botble ecommerce store using Ziina — the UAE-based payment gateway trusted by businesses across the Middle East.

Compatibility

PlatformSupported

Botble CMS

≥ 7.3.0

Martfury Theme

✅

Shofy Theme

✅

Nest Theme

✅

PHP

≥ 8.1

Features

• Hosted Payment Page — customers are redirected to Ziina's secure, PCI-compliant payment page
• Card, Apple Pay & Google Pay — all in one integration
• Test & Live Mode — toggle without changing your API key
• Processing Fee support — fixed or percentage fee shown at checkout
• Full Refund API — full and partial refunds via admin
• Webhook support — async status updates with HMAC-SHA256 signature verification
• 10 Currencies — AED, USD, EUR, GBP, SAR, QAR, INR, BHD, KWD, OMR
• 3-decimal currency handling — BHD, KWD, OMR rounded to nearest 10 fils automatically
• IP Allowlist — only accepts webhooks from verified Ziina IP addresses

Installation1. Upload the Plugin

Copy the ZiinabyCodeupp folder to:

platform/plugins/ziina/

The folder must be named ziina inside platform/plugins/.

2. Activate the Plugin

Go to Admin → Plugins and activate Ziina Payment Gateway.

The migration will run automatically and create the ziina_payment_intents table.

3. Publish Assets

Run the following command from your Laravel root:

php artisan vendor:publish --tag=cms-public --force

This copies the Ziina SVG logo to public/vendor/core/plugins/ziina/images/ziina.svg.

4. Configure Settings

Go to Admin → Payments → Payment Methods and scroll to the Ziina section.

FieldDescription

Status

Enable/disable Ziina on the checkout

API Key

Your Bearer token from ziina.com/business/connect

Test Mode

ON = test mode (no real charges), OFF = live mode

Default Currency

Fallback currency when cart currency is not set

Allow Tips

Show tip option on the Ziina-hosted payment page

Webhook HMAC Secret

Optional. Signs incoming webhooks for verification

Processing Fee

Fixed or % fee added to order total at checkout

Getting Your API Token

1. Visit https://ziina.com/business/connect
2. Select "Other builder or custom"
3. Enter your phone number → verify OTP → enter email
4. Your Bearer token is generated and shown once — copy it immediately

⚠️ The same token is used for both Test and Live mode. Switch modes via the Test Mode toggle in plugin settings.

Webhook Setup (Optional but Recommended)

Webhooks allow Ziina to notify your store of payment status changes asynchronously — useful if the customer closes the browser before being redirected.

Register Your Webhook

Call the Ziina API once to register your URL:

curl --request POST \  --url https://api-v2.ziina.com/api/webhook \  --header 'Authorization: Bearer YOUR_TOKEN' \  --header 'Content-Type: application/json' \  --data '{    "url": "https://yourstore.com/payment/ziina/webhook",    "secret": "your-chosen-hmac-secret"  }'

Then add the same secret string into the Webhook HMAC Secret field in plugin settings.

Accepted Webhook IPs

The plugin automatically rejects webhooks from IPs not in this list:

3.29.184.186 3.29.190.95 20.233.47.127 13.202.161.181

Payment Flow

1. Customer selects "Ziina" at checkout and clicks Place Order        ↓ 2. Plugin calls POST /payment_intent → gets redirect_url        ↓ 3. Customer is redirected to Ziina-hosted payment page        ↓ 4a. SUCCESS  → redirected to /payment/ziina/success 4b. CANCEL   → redirected to /payment/ziina/cancel 4c. FAILURE  → redirected to /payment/ziina/failure        ↓ 5. Success handler verifies status via GET /payment_intent/{id}   (server-side verification — never trusts URL params alone)        ↓ 6. PAYMENT_ACTION_PAYMENT_PROCESSED fires → order marked as paid        ↓ 7. Webhook fires payment_intent.status.updated → secondary confirmation

Supported Currencies & Amount Encoding

CurrencyCodeEncodingExample

UAE Dirham

AED

× 100

100 AED → 10000

US Dollar

USD

× 100

10.50 USD → 1050

Euro

EUR

× 100

25 EUR → 2500

British Pound

GBP

× 100

50 GBP → 5000

Saudi Riyal

SAR

× 100

75 SAR → 7500

Qatari Riyal

QAR

× 100

100 QAR → 10000

Indian Rupee

INR

× 100

500 INR → 50000

Bahraini Dinar

BHD

× 1000, round to 10

1.234 BHD → 1230

Kuwaiti Dinar

KWD

× 1000, round to 10

2.555 KWD → 2560

Omani Rial

OMR

× 1000, round to 10

3.001 OMR → 3000

Minimum payment: 2 AED (200 base units).

Test Cards

Use these when Test Mode is ON:

BrandNumberCVVExpiry

Visa

4242 4242 4242 4242

Any 3 digits

Any future date

Visa

4000 0000 0000 0002

Any 3 digits

Any future date

Mastercard

5555 5555 5555 4444

Any 3 digits

Any future date

Mastercard

5200 8282 8282 8210

Any 3 digits

Any future date

Amex

3782 822463 10005

Any 4 digits

Any future date

Amex

3714 496353 98431

Any 4 digits

Any future date

These cards are declined in Live mode.

Payment Status Reference

StatusMeaning

requires_payment_instrument

Customer hasn't attempted payment yet

requires_user_action

Awaiting 3-D Secure authentication

pending

Payment is processing

completed

✅ Payment successful — order marked as paid

failed

❌ Payment failed

canceled

Customer cancelled

File Structure

ziina/ ├── composer.json ├── plugin.json ├── README.md ├── config/ │   └── ziina.php ├── database/ │   └── migrations/ │       └── 2026_01_01_000001_create_ziina_payment_intents_table.php ├── helpers/ │   └── constants.php ├── public/ │   └── images/ │       └── ziina.svg ├── resources/ │   ├── lang/ │   │   └── en/ │   │       └── ziina.php │   └── views/ │       ├── detail.blade.php │       ├── instructions.blade.php │       └── methods.blade.php ├── routes/ │   └── web.php └── src/    ├── Plugin.php    ├── Forms/    │   └── ZiinaPaymentMethodForm.php    ├── Http/    │   └── Controllers/    │       └── ZiinaController.php    ├── Providers/    │   ├── HookServiceProvider.php    │   └── ZiinaServiceProvider.php    └── Services/        ├── Abstracts/        │   └── ZiinaPaymentAbstract.php        └── Gateways/            └── ZiinaPaymentService.php

Security Checklist

• [x] API key stored via Botble payment settings (encrypted at rest), never hardcoded
• [x] Payment status verified server-side via GET /payment_intent/{id} before marking order paid
• [x] Webhook source IP validated against Ziina's published allowlist
• [x] HMAC-SHA256 webhook signature verification (when secret is configured)
• [x] Webhook route excluded from CSRF protection via core_middleware_verify_csrf_token_except filter
• [x] All payment events logged for audit trail

Support

• Plugin Support: codeupp.xyz
• Ziina API Docs: docs.ziina.com
• Ziina Business: ziina.com/business/connect