WordPress integration

Before you begin

Complete:

1. Store setup
2. Understand flow

Use this path if your tenant website is on WordPress and you want a straightforward integration setup.

Official WordPress plugin (recommended)

The plugin is maintained on GitHub: ibrahim317/vodafoncash-wordpress-plugin.

1. Open Releases and download the latest .zip file attached to the newest release (this is the file you upload to WordPress).
2. In your WordPress admin go to Plugins → Add New → Upload Plugin, choose that zip, then activate VodafoneCash Integration.

What it does

1. Settings — Settings → VodafoneCash in wp-admin: API base URL (e.g. https://vodafoncash.com), Store ID, default language (ar / en), API token (stored server-side only), and user_name mapping (logged-in login, ID, email, or a guest field on the form).

2. Payment form — Adds:

   • Shortcode: [vodafoncash_payment_form] (optional title="...").
   • Block: VodafoneCash Payment (same output as the shortcode). The form talks to your WordPress site first; the plugin then calls our GET /api/payment_link_check for you so your Store ID and settings stay on the server.

3. Callback URL — The plugin settings screen shows your callback URL, typically:

   https://YOUR-SITE.com/wp-json/vodafoncash/v1/callback

   Paste this into your store’s API URL field. In the tenant dashboard, pick Website type → WordPress: the form shows a link to this guide and prefills the API URL with https://example.com/wp-json/vodafoncash/v1/callback when the field is empty—replace example.com with your real domain (or paste the exact URL from Settings → VodafoneCash in WordPress). You can also use Custom integration with the same URL; both types use the same callback contract on our side.

   After a successful match, our platform calls that URL with GET and parameters such as key, action=addPayment, username, amount, from, and trans_id. The plugin checks the key against your saved API token and replies so we know the payment was recorded. The same transaction is not applied twice if our system retries the request.

Manual integration (without the plugin)

If you prefer not to use the plugin, follow the sections below.

WordPress integration idea

In your WordPress site, build/use a payment form to collect:

• Phone number
• Amount

Then call:

GET /api/payment_link_check?phone=...&amount=...&user_name=...&store_id=...&lang=en

Handling responses in WordPress

Success

{
  "status": true,
  "requires_verification": false
}

Your action:

• Show payment success.
• Apply business action (credit balance, complete order, etc.).

Failure / no match

{
  "status": false,
  "message": "No matching transaction found"
}

Your action:

• Show clear error message.
• Let user retry.

Callback endpoint in your WordPress site

When matching succeeds, our system sends a GET request to the endpoint you configured in store settings.

Make sure your WordPress endpoint:

• Receives transaction parameters.
• Validates request integrity.
• Updates your DB with your intended action.

Anti‑Spam (covered here after the basic integration)

When Anti‑Spam is enabled:

• First request from a new phone (or blacklisted phone) may become waiting-for-approval.
• /api/payment_link_check may return requires_verification: true.
• Store owner must approve manually in vodafoncash.com.

Example response:

{
  "status": false,
  "requires_verification": true,
  "pending_verification": true,
  "flow_state": "waiting-for-approval",
  "message": "This transaction is waiting for manual approval."
}

Your WordPress form should handle this case explicitly (e.g. "Your request is waiting for approval. Please try again later.").