Wayl API — payment lifecycle

Step 2

Create a payment link

When a customer is ready to pay, you call the API and get back a single checkout URL for that order. You identify the order with a unique referenceId, send the amount in IQD as total, and can optionally add webhookUrl, webhookSecret, and redirectionUrl so you are notified when status changes and you can send people somewhere friendly after checkout. This is available to verified stores only.

1. Call POST /api/v1/links from your server. Use env=test while you are still testing; switch when you go live.
2. Pass a unique referenceId for this order, the total, and currency IQD.
3. Make sure your line items add up to the same total you send.
4. Use data.url from the response as the checkout link you give the customer. data.code is the short code if you need to show or store it.

curl https://api.thewayl.com/api/v1/links \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-WAYL-AUTHENTICATION: YOUR_SECRET_TOKEN' \
  --data '{
  "env": "live",
  "referenceId": "dummy-reference-id",
  "total": 10000,
  "currency": "IQD",
  "customParameter": "",
  "lineItem": [
    {
      "label": "Basket Value",
      "amount": 10000,
      "type": "increase"
    }
  ],
  "webhookUrl": "https://webhook.site/your-webhook-url",
  "webhookSecret": "1234567890",
  "redirectionUrl": "https://www.google.com"
}'

A successful create returns 201. The body includes the checkout URL in data.url, a short code, the link id, status, and paymentMethod (this stays empty until the customer has paid). total is returned as a string.

{
  "data": {
    "referenceId": "order-1001",
    "id": "cmlink_01hq_example",
    "code": "I94F590I",
    "total": "10000",
    "currency": "IQD",
    "type": "standard",
    "paymentMethod": null,
    "status": "Created",
    "completedAt": null,
    "createdAt": "2025-04-09T12:00:00.000Z",
    "updatedAt": "2025-04-09T12:00:00.000Z",
    "url": "https://checkout.thewayl.com/pay/I94F590I",
    "webhookUrl": "https://example.com/webhooks/wayl",
    "redirectionUrl": "https://example.com/thanks"
  },
  "message": "Link created successfully."
}

Step 3

Check payment status

Any time you need to know where an order stands—after a redirect, from a cron job, or before you ship—you can ask Wayl for the current link by the same referenceId you used when you created it. Call GET /api/v1/links/{referenceId} — the response tells you whether it's still open, paid, or finished, and when things changed. status moves through values like Created, Pending, Processing, Complete, Delivered, Cancelled, Rejected, and Returned; the hosted API reference has the full list and meanings.

curl -s "https://api.thewayl.com/api/v1/links/order-1001" \
  -H "X-WAYL-AUTHENTICATION: YOUR_MERCHANT_TOKEN"

A successful lookup returns 200 with that link in data. Use status for the lifecycle, paymentMethod once the customer has paid (if present), and completedAt when you need the time the payment completed.

{
  "data": {
    "referenceId": "order-1001",
    "id": "cmlink_01hq_example",
    "total": "10000",
    "currency": "IQD",
    "paymentMethod": "Card",
    "status": "Complete",
    "completedAt": "2025-04-09T12:07:30.000Z",
    "createdAt": "2025-04-09T12:00:00.000Z",
    "updatedAt": "2025-04-09T12:07:30.000Z",
    "url": "https://checkout.thewayl.com/pay/I94F590I",
    "webhookUrl": "https://example.com/webhooks/wayl",
    "redirectionUrl": "https://example.com/thanks"
  },
  "message": "Link retrieved successfully."
}

Step 4

Webhooks & verify

{
  "verb": "POST",
  "event": "order.created",
  "referenceId": "dassasasuaassasmmy-rzel2faserasaseneas-id",
  "paymentMethod": "...",
  "paymentStatus": "...",
  "paymentProcessor": "...",
  "total": 1000,
  "commission": 0,
  "code": "I94F590I",
  "customer": {
    "id": "cmBkktqmz0000g00btwuo4ill",
    "name": "...",
    "phone": "...",
    "city": "iraq_al_basrah",
    "country": "IQ",
    "address": "Baghdad"
  },
  "items": [
    {
      "type": "increase",
      "label": "Basket Value",
      "amount": 1000
    }
  ],
  "id": "cmay0lf12000ng0194x5r801o"
}

Respond

When you've accepted the payload and queued work, reply with any HTTP 2xx status code. If Wayl sees an error or a timeout, it may try again—so keep your endpoint quick (do heavy work in the background) and return success only once you've safely stored the event.

Verify HMAC

Use the same webhookSecret you used when creating the link. Hash the raw body with HMAC-SHA256 and compare the result to the x-wayl-signature-256 header using a constant-time comparison so timing attacks can't leak information.

Node.js

import crypto from "crypto";

function verifyWebhookSignature(data, signature, secret) {
  // data from webhook req.body
  // signature from req.headers "x-wayl-signature-256"
  // secret that was previously sent when creating the link, should be locally
  // stored in your code or database
  // generate signature from data and secret
  const calculatedSignature = crypto.createHmac("sha256", secret).update(data).digest("hex");

  // Convert the signatures to buffers for security
  const signatureBuffer = Buffer.from(signature, "hex");
  const calculatedSignatureBuffer = Buffer.from(calculatedSignature, "hex");

  // Compare the created signature with the signature from the request
  if (signatureBuffer.length !== calculatedSignatureBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(signatureBuffer, calculatedSignatureBuffer);
  // true if the signature is valid, false otherwise
}

verifyWebhookSignature(data, signature, secret);

Sign the exact bytes Wayl posted—typically the buffer or string you read from the request before you call JSON.parse, so whitespace and ordering stay identical.

Step 5

Refunds

When you need to return money to a customer after a successful charge, you open a refund against the same order using POST /api/v1/refunds. You send the order's referenceId, how much to refund in IQD as amount (up to what was captured), and a clear reason (100–1500 characters) so support and risk teams can see why. Wayl tracks each refund with a status such as Requested, Refunded, Rejected, or Cancelled.

curl -s -X POST "https://api.thewayl.com/api/v1/refunds" \
  -H "X-WAYL-AUTHENTICATION: YOUR_MERCHANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "order-1001",
    "reason": "Customer requested a refund after a duplicate charge. Support ticket #4521 confirms the issue; merchant policy allows a full reversal within fourteen days of purchase.",
    "amount": 10000
  }'

If the refund request is accepted, you'll get 201 and a data object with the refund's id, linkId, amount, who started it (initiatedBy), and the current status.

{
  "data": {
    "id": "cmrefund_01hq_example",
    "reason": "Customer requested a refund after a duplicate charge. Support ticket #4521 confirms the issue; merchant policy allows a full reversal within fourteen days of purchase.",
    "linkId": "cmlink_01hq_example",
    "referenceId": "order-1001",
    "amount": 10000,
    "initiatedBy": "Merchant",
    "status": "Requested"
  },
  "message": "Refund created successfully."
}

Listing refunds and cancelling a pending request are documented in the hosted API reference.