wayl-mcp

An MCP server for the Wayl payments API — take payments online in Iraq from an AI assistant.

Ask your assistant to "charge 25,000 dinars for a consultation" and it creates the payment link, hands you the checkout URL, and can tell you later whether the customer actually paid. Works for anything you sell: physical goods, digital downloads, services, tickets, invoices.

Wayl is an Iraqi payment gateway. All amounts are in Iraqi Dinar (IQD).

Setup

You need an API key. Wayl's guide says to email jisr@wayl.io to request a merchant token; their API reference says it is in your merchant dashboard. Try the dashboard first, then email. Your store must be verified before it can create links.

uv sync

Then set the key:

export WAYL_API_KEY="your-merchant-token"

Check it works:

uv run python -c "import asyncio, wayl_mcp.server as s; print(asyncio.run(s.verify_auth_key()))"

Related MCP server: PayPal

Connecting it

Claude Code

claude mcp add wayl --env WAYL_API_KEY=your-merchant-token -- uv run --directory /absolute/path/to/wayl_MCP wayl-mcp

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "wayl": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/wayl_MCP", "wayl-mcp"],
      "env": {
        "WAYL_API_KEY": "your-merchant-token",
        "WAYL_ENV": "test"
      }
    }
  }
}

Use an absolute path — the server is launched from an arbitrary working directory.

Configuration

WAYL_ENV defaults to test so nothing moves real money until you opt in. Set it to live when you are ready to actually sell, or pass env="live" per call.

While in test mode, check_order_paid and parse_webhook report paid: true for a completed sandbox checkout but safeToFulfil: false — the payment is simulated, so the order should not be fulfilled. Branch on safeToFulfil, not paid.

Tools

Selling

Links

Products

Refunds

Webhooks and diagnostics

Read-only tools are marked readOnlyHint; refunds and invalidations are marked destructiveHint so your client can ask before running them.

Taking a payment

Creating the link:

Sell "Wireless keyboard" for 30000 IQD with 5000 delivery

sell_item builds the line items, generates a unique reference ID, and returns a checkout URL like https://checkout.thewayl.com/pay/I94F590I. Send that to the customer. It works the same for a service, a ticket or a digital download — set delivery_fee=0 when nothing ships.

For full control over webhooks, redirects and custom line items, use create_payment_link instead.

Finding out whether they paid — either poll:

Has order order-wireless-keyboard-a1b2c3 been paid?

or receive a webhook. Set webhookUrl and webhookSecret when creating the link, then pass each incoming request to parse_webhook, which verifies the signature and tells you whether to fulfil.

Webhooks

Wayl signs each delivery with HMAC-SHA256 over the raw request body, sending the hex digest in the x-wayl-signature-256 header.

Three things that break integrations:

1. Hash the raw bytes. json.dumps(json.loads(body)) changes whitespace and key order, so the digest will not match. Verify before you parse.

2. Wayl sends Content-Type: text/plain, so JSON body parsers may hand you an empty body. Read the raw body yourself.

3. Deduplicate on the payload's id. There is no timestamp in the signature, so a captured request replays forever — and Wayl retries on timeout, so duplicates happen in normal operation too.

The webhook reports paymentStatus: "Paid", which is not one of the eight link statuses the REST API uses. parse_webhook handles that distinction.

Development

uv run pytest

uv run ruff check src tests

See CLAUDE.md for architecture notes and the API's sharp edges.

Licence

MIT