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()))"

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

Variable	Default	Purpose
WAYL_API_KEY	—	Required. Merchant token, sent as X-WAYL-AUTHENTICATION.
WAYL_ENV	test	Default environment for new links: test or live.
WAYL_BASE_URL	https://api.thewayl.com	API host.
WAYL_WEBHOOK_URL	—	Default webhook URL for new links.
WAYL_WEBHOOK_SECRET	—	Default webhook signing secret (10–255 chars).
WAYL_REDIRECT_URL	—	Where buyers land after paying.
WAYL_REFERENCE_PREFIX	order	Prefix for generated order IDs.
WAYL_TIMEOUT	30	HTTP timeout in seconds.

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

Tool	Does
sell_item	Create a checkout link for a simple sale, with the price breakdown filled in.
check_order_paid	Answer whether an order is paid and safe to fulfil.
create_payment_link	Create a payment link with full control over every field.

Links

Tool	Does
get_payment_link	Fetch one link and its status.
list_payment_links	List links, newest first, filterable by status.
get_payment_links_batch	Look up to 100 links at once; reports which were missing.
invalidate_payment_link	Cancel an unpaid link.
invalidate_payment_link_if_pending	Cancel it only if still pending.

Products

Tool	Does
list_products	List your Wayl catalogue (Digital, Physical, Service).
get_product	Fetch one product's details.

Refunds

Tool	Does
create_refund	Request a refund. Needs a 100+ character justification.
list_refunds	List refund requests.
get_refund	Fetch one refund.
cancel_refund	Withdraw a refund still in Requested.

Webhooks and diagnostics

Tool	Does
parse_webhook	Verify a webhook's signature and report whether the order is paid.
verify_webhook	Signature check alone.
verify_auth_key	Confirm the API key works.
wayl_status	Show how the server is configured, without calling the API.

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