Introduction

An AI agent that books a flight, renews a subscription, or restocks
inventory on a user's behalf needs a way to spend money — but handing an
agent a raw credit card number is not a payments primitive, it's a
liability. moyasar-ac is a proof-of-concept for the missing piece:
a payment-mandate service that sits between an agent and a real charge,
turning "the agent wants to spend money" into a chain of explicit,
revocable, cryptographically-verifiable consent.

The shape of it:

1. An agent registers itself (Agents) and gets credentials.
2. The agent asks moyasar-ac to create an Intent Mandate — a signed, capped spending authorization scoped to one user, one currency, one ceiling amount, and (optionally) a domain-specific intent like a flight booking.
3. The mandate is not active yet. The user must open a hosted approval link, authenticate, and sign the mandate with a WebAuthn passkey before a single unit of currency can move.
4. Once approved, a merchant can draw against the mandate — a signed, replay-protected charge request bounded by the mandate's cap.
5. Every step is appended to a hash-chained audit log, so the full history of who authorized what, and when, is independently verifiable.

Domain-specific intents are pluggable: the flight-booking demo, for
instance, lets an agent name a carrier — Saudia or Emirates — either in
the mandate's structured airline field or in plain language (e.g. "book
an Emirates flight to London"), and the correct merchant is resolved
automatically.

This reference documents the REST API a developer integrates against,
the hosted approval flow a real human completes, and the MCP tool layer
that lets an AI agent (Claude, an LLM in LM Studio, or any MCP-capable
client) drive the whole flow through natural conversation.

Authentication

Agents authenticate with OAuth2 client-credentials. You get a
client_id/client_secret pair from registering an agent,
then exchange them for a short-lived bearer token.

All examples on this page use http://localhost:3000, the sandbox host
this PoC runs on — substitute your own deployment's host.

Get a bearer token

curl -X POST http://localhost:3000/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "ag_YlTyCQWgXSwI6ElAyJsYEKbY",
    "client_secret": "your-agent-client-secret"
  }'

import httpx

resp = httpx.post("http://localhost:3000/oauth/token", json={
    "grant_type": "client_credentials",
    "client_id": "ag_YlTyCQWgXSwI6ElAyJsYEKbY",
    "client_secret": "your-agent-client-secret",
})
print(resp.json())

require "net/http"
require "json"

uri = URI("http://localhost:3000/oauth/token")
res = Net::HTTP.post(uri, {
  grant_type: "client_credentials",
  client_id: "ag_YlTyCQWgXSwI6ElAyJsYEKbY",
  client_secret: "your-agent-client-secret"
}.to_json, "Content-Type" => "application/json")

puts JSON.parse(res.body)

Response 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}

Send the token on every subsequent API call:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Tokens expire after 300 seconds (5 minutes) — request a new one when
create_intent_mandate or any bearer-authenticated call returns
401 unauthorized.

Authentication errors

Scopes

Every token is issued with the mandates:write scope. Endpoints that
require a scope your token doesn't have return 403 {"error":
"insufficient_scope"}.

Agents

Register a new spending agent. Do this once per agent identity — the
returned client_secret is used for every Authentication
token request afterward.

Register an agent

curl -X POST http://localhost:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "SkyBooker"}'

import httpx

resp = httpx.post("http://localhost:3000/v1/agents", json={"name": "SkyBooker"})
print(resp.json())

require "net/http"
require "json"

uri = URI("http://localhost:3000/v1/agents")
res = Net::HTTP.post(uri, { name: "SkyBooker" }.to_json,
                      "Content-Type" => "application/json")
puts JSON.parse(res.body)

By default moyasar-ac mints and retains the agent's Ed25519 signing keypair
itself (there's no real external process to hold it for). A counterparty that
holds its own private key — such as the ac-mcp agent, which signs cart terms
via sign_cart — can instead supply just its public half at registration
time, so moyasar-ac never sees the private key:

curl -X POST http://localhost:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "SkyBooker", "public_key": "xLwNQML3k4hfGPVzHzqr_9yKfETvsdYyGCZczsscJQ0"}'

Request

Agent registration response

{
  "agent_id": "43b53ae5-caf7-464c-a00d-e89ffb154d21",
  "name": "SkyBooker",
  "client_id": "ag_YlTyCQWgXSwI6ElAyJsYEKbY",
  "client_secret": "9k2mZ...40-character-random-string"
}

client_secret is shown exactly once and cannot be recovered.
The server stores only a bcrypt digest of it — there is no "forgot my
secret" endpoint. Store it securely the moment you receive it.

Agent errors

Catalog

Closed discovery endpoint: lets an authenticated agent browse the
in-stock catalog of products offered by merchants that have completed
onboarding (portal_status: "approved") through the merchant portal, an
internal application-review flow with no dedicated public docs section
today. A product only appears here if it's active, has stock
available (stock_on_hand - reserved_count > 0), and belongs to an
approved merchant — a merchant
that's still pending or has been rejected has no products surfaced
here, even if it has some on file.

Requires a bearer token with the mandates:write scope (see
Authentication).

List catalog products

curl "http://localhost:3000/v1/catalog?domain_id=retail_purchase&currency=SAR" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

import httpx

resp = httpx.get(
    "http://localhost:3000/v1/catalog",
    params={"domain_id": "retail_purchase", "currency": "SAR"},
    headers={"Authorization": f"Bearer {access_token}"},
)
print(resp.json())

require "net/http"
require "json"

uri = URI("http://localhost:3000/v1/catalog")
uri.query = URI.encode_www_form(domain_id: "retail_purchase", currency: "SAR")
req = Net::HTTP::Get.new(uri, "Authorization" => "Bearer #{access_token}")
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts JSON.parse(res.body)

Query parameters

Catalog response

{
  "products": [
    {
      "id": "9c3b6f1a-2e4d-4a7b-9f0e-1234567890ab",
      "merchant_id": "33333333-3333-3333-3333-333333333333",
      "title": "In stock",
      "description": null,
      "price_minor": 100,
      "currency": "SAR",
      "domain_id": "generic_purchase",
      "sku": "IN-1",
      "available": 3,
      "merchant_name": "SinglePage (test)",
      "image_data_uri": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i..."
    }
  ]
}

Each entry in products is one in-stock, active product:

Where the safety guarantee for this field actually lives. SVG is
executable markup, so a hostile image_data_uri is a real concern — but the
guarantee here is the render path, not a content scan. The MCP Apps
widget renders artwork only as <img src="data:...">, never as inline
<svg> markup, a CSS background-image, or an <object>/<embed>/
<iframe>; that invariant is enforced on the widget's own source by
test_artwork_only_ever_renders_via_img_src_data_uri
(tools/ac-mcp/tests/test_mcp_apps.py), and confirmed with a live Chromium
network trace to make zero network requests for an <img>-rendered SVG
regardless of its content. That is what actually keeps a hostile payload
inert.

The widget also enforces the scheme itself, rather than trusting this
API to have done it: a value that is not a data:image/ URI is never put in
an src at all — it falls back to the same neutral placeholder a product
with no artwork gets. So an https://… value arriving here by any route
produces no image request from inside the host's page.

On top of that, Product runs a best-effort content check on write —
rejecting an SVG containing a <script>/<foreignObject> element, an
event-handler attribute, a DOCTYPE declaration, or an href/src/url(...)
reference outside the document (a bare #fragment or a data:image/...
value is still allowed; other data: subtypes are not). This check is
not a security boundary and does not claim to be one: it is a
text-level scan, not a CSS- or SMIL-aware parser, and known gaps — CSS
escape sequences, an unquoted @import, and a SMIL <set attributeName=
"href" to="..."> that installs a reference only when a browser's animation
engine runs it — are left open deliberately rather than chased with an
ever-growing set of regexes. It exists to catch accidents and unsophisticated
attempts cheaply, on top of the render-path guarantee above, not instead of
it.

stock_on_hand, reserved_count, active, and the owning merchant's
portal_status are never included in the response as raw values — they
only affect which products are eligible to be listed in the first
place. available is the one number derived from them that is
surfaced, precisely because a picker needs to show "only N left."

A product is listed only while stock_on_hand - reserved_count > 0. A
product with stock on the shelf but every unit reserved by an
in-flight draw is not listed at all, rather than listed with
available: 0.

Catalog errors

Inventory feed

Instead of typing products into the merchant portal one at a time, you
can publish a REST feed — a single https:// endpoint that returns
your catalog as JSON — and moyasar-ac will poll it and keep your
catalog listings in step with it.

You build the endpoint; we call it. There is no API to push a catalog to
us in v1, and nothing about this section is something an agent ever
sees: the feed is the merchant-side contract, and the
Catalog endpoint is what agents read afterwards.

Before you connect one, read Stock is overwritten, not adjusted.
A feed whose stock_on_hand does not already account for units sold
through moyasar-ac will oversell — every poll re-inflates our count
back to yours, and the difference is sold twice. It is the one part of
this contract that costs money to get wrong.

Connecting a feed

Feeds are connected from the merchant portal at /merchant/inventory —
there is no API for this in v1. You supply the feed's URL and,
optionally, a bearer token. A merchant may have one feed connected
at a time; connecting a second is refused.

The connect and edit forms refuse a URL that:

• doesn't use https://
• carries userinfo (https://user:pass@host/...)
• uses any port other than 443
• resolves (at connect time, and again on every page of every poll) to a private, loopback, link-local, CGNAT, multicast or otherwise reserved address, or to one of moyasar-ac's own hostnames
• is longer than 2,000 characters

moyasar-ac never follows a redirect to your feed: a 3xx is a failed
poll, not a hop to follow. This is the same outbound guard the
merchant webhook dispatcher uses — the feed
poller extends that client rather than copying it.

Disconnecting a feed does not delete the products it created. They
stay exactly as they are, on sale, and become hand-entered products you
own in the portal from that moment on — keeping the price and stock from
the last good sync, since nothing refreshes them while no feed is
connected.

They are also marked as having come from a disconnected feed. When you
connect a feed again, the Inventory screen offers to hand them to it in
one click; until you accept, the new feed reports each of them as a SKU
collision, because a feed never overwrites a product you own by hand.
Accepting hands over every product left by a disconnected feed, not
only the SKUs the new feed lists — anything it does not list is taken
off sale on the first complete traversal, exactly as it would have been
had you never disconnected. Products you typed yourself are never
offered and never touched.

Authenticating our requests

Every request we make to your feed carries:

A public feed is a legitimate configuration. Leave the token field
empty and we send no Authorization header at all. If your catalog
isn't sensitive, an unauthenticated endpoint is a perfectly good answer
and there is nothing to store or rotate.

If you do set a token, it is stored encrypted and never shown back to
you. The portal's token field always renders empty, and leaving it
empty when you edit the feed means keep the token I already have — it
does not clear it. Removing a token is a separate, explicit control.

Changing the feed's host drops the stored token. If you edit the URL
so that its hostname changes, the token is discarded and the portal says
so; re-enter it if the new host needs one. (Editing only the path or
query string on the same host keeps it.) This is deliberate: without it,
repointing a feed at another host would have delivered your secret to
that host in an Authorization header.

The feed response

Answer 200 with a JSON object. Anything else — a non-2xx, a body
that isn't JSON, or an object that fails the envelope rules below —
fails the whole run and changes nothing in your catalog.

Envelope fields

Item fields

Field names and value domains are deliberately identical to the product
columns the Catalog exposes. There is no mapping layer in
v1: what you send is what is stored.

Three of these behave in a way that surprises people:

active is a strict boolean. true and false only. The string
"false", the number 0, and "" are all rejected — the item is
refused with a reason naming the value, and the product's current
active state is left alone. This matters because it is the one field
that decides whether an agent can buy the listing: if a stringified
"false" were coerced, the most common serializer bug in the world
(PHP, XML-derived and CSV-to-JSON feeds routinely stringify booleans)
would silently leave a withdrawn product on sale, with a clean
"succeeded" run in your portal and nothing to notice. If your serializer
emits "true"/"false", fix it at the source or your listings cannot
be taken off sale.

A sku with stray whitespace or a control character is refused, not
cleaned up. "COFFEE-1KG " (trailing space) is rejected rather than
trimmed to "COFFEE-1KG". Silently stripping would let two different
rows in your feed — "ABC" and "ABC " — collapse onto one product,
with the last one written winning; and a feed that drifts on whitespace
from one poll to the next would create a look-alike product while the
real one was taken off sale. Refusing is the only behaviour that can't
quietly damage a live listing.

Omitting an optional field blanks it. These are absolute writes, not
patches: if description was set and your next poll omits it, the
description becomes empty. The same is true of
cancellation_policy_text and return_policy_text — and those two are
not cosmetic. They are copied into the mandate's signed
intent_payload and rendered on the hosted approval page that a human
authorizes with a passkey. Dropping them from a poll removes those terms
from the consent ceremony for every mandate created afterwards. Send
them on every page of every poll, not just when they change.

A conforming feed response

{
  "version": 1,
  "generated_at": "2026-08-04T09:00:00Z",
  "items": [
    {
      "sku": "COFFEE-1KG",
      "title": "Arabica Roast 1kg",
      "price_minor": 8900,
      "currency": "SAR",
      "domain_id": "generic_purchase",
      "stock_on_hand": 12,
      "fulfillment_mode": "pickup",
      "description": "Single origin, roasted weekly.",
      "active": true,
      "cancellation_policy_text": "Cancel free of charge up to 24 hours before pickup.",
      "return_policy_text": "Unopened bags may be returned within 14 days."
    },
    {
      "sku": "EBOOK-ROASTING",
      "title": "Home Roasting, 2nd edition",
      "price_minor": 4500,
      "currency": "SAR",
      "domain_id": "generic_purchase",
      "stock_on_hand": 999,
      "fulfillment_mode": "digital",
      "active": false
    }
  ],
  "next": null
}

This is exactly the request we make — reproduce it against your own
endpoint to check what we'll see:

curl -sS "https://feeds.example.com/moyasar-ac/catalog" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $FEED_TOKEN"   # omit this line for a public feed

A minimal conforming responder, with pagination:

from flask import Flask, jsonify, request

app = Flask(__name__)
PAGE = 500

@app.get("/moyasar-ac/catalog")
def catalog():
    cursor = int(request.args.get("cursor", 0))
    rows = load_products(offset=cursor, limit=PAGE)   # your own query
    has_more = len(rows) == PAGE
    return jsonify({
        "version": 1,
        "generated_at": utcnow_iso8601(),
        "items": [
            {
                "sku": r.sku,
                "title": r.title,
                "price_minor": int(r.price_minor),
                "currency": r.currency,
                "domain_id": "generic_purchase",
                # Units you are willing to sell through moyasar-ac, with
                # everything already sold through it deducted.
                "stock_on_hand": int(r.available_to_moyasar_ac),
                "fulfillment_mode": "pickup" if r.physical else "digital",
                "description": r.description,
                "active": bool(r.on_sale),          # a real bool, never "false"
                "cancellation_policy_text": r.cancellation_terms,
                "return_policy_text": r.return_terms,
            }
            for r in rows
        ],
        # Absolute, https, same host and port as the URL you registered.
        "next": (f"https://feeds.example.com/moyasar-ac/catalog?cursor={cursor + PAGE}"
                 if has_more else None),
    })

require "sinatra"
require "json"

PAGE = 500

get "/moyasar-ac/catalog" do
  content_type :json
  cursor = params.fetch("cursor", 0).to_i
  rows = load_products(offset: cursor, limit: PAGE)   # your own query
  has_more = rows.size == PAGE

  {
    version: 1,
    generated_at: Time.now.utc.iso8601,
    items: rows.map do |r|
      {
        sku: r.sku,
        title: r.title,
        price_minor: r.price_minor.to_i,
        currency: r.currency,
        domain_id: "generic_purchase",
        # Units you are willing to sell through moyasar-ac, with
        # everything already sold through it deducted.
        stock_on_hand: r.available_to_moyasar_ac.to_i,
        fulfillment_mode: r.physical? ? "pickup" : "digital",
        description: r.description,
        active: !!r.on_sale?,                        # a real bool, never "false"
        cancellation_policy_text: r.cancellation_terms,
        return_policy_text: r.return_terms
      }
    end,
    # Absolute, https, same host and port as the URL you registered.
    next: has_more ? "https://feeds.example.com/moyasar-ac/catalog?cursor=#{cursor + PAGE}" : nil
  }.to_json
end

Pagination

Set next to the absolute URL of the following page, and null (or
omit it) on the last one. We follow it until it is absent, and every
page is fetched with the same headers and checked against the same
guard as the first.

next must be:

• a string or null. Any other JSON type — {}, [], 42, true — ends the traversal as incomplete. It is not treated as "no more pages", because silently truncating your catalog is the one outcome this contract never allows
• https://, on the same host and the same port as the feed URL you registered. Not merely the same host as the previous page — a chain of same-as-previous hops can't walk away from the origin you registered. A cross-origin next ends the traversal as incomplete and is never fetched
• not a page we've already fetched in this run. A next cycle ends the traversal as incomplete

A query-string cursor, an opaque token, a page number — any of them is
fine, as long as the URL stays on your registered origin.

Caps

Note that the byte cap is per page, not per run: a 40 MB catalog is
fine, spread over pages that are each under 2 MB.

The 120-second wall clock bounds when we stop starting pages, not when
we stop reading one, so a single source's worst case is closer to 153
seconds — the 120-second budget, plus a 3-second DNS timeout, plus a
final page that is allowed its full 30-second deadline. Size your
endpoint's own timeouts accordingly.

Every cap ends the run as incomplete, and an incomplete run is not a
discarded run: valid items already fetched are applied. What it
suppresses is deactivation — see below.

The polling schedule

Connected, active feeds are polled every 15 minutes. There is no way
to configure the interval in v1, and no way to have moyasar-ac poll only
on demand.

The portal has a Sync now button, which queues a run rather than
running one. It is not immediate: manual runs are serialized against the
scheduled batch, so a click that lands while a batch is in progress
waits for it. It's rate limited to 5 per hour per merchant, and it
is refused for a feed the breaker has disabled — re-enable
it instead.

Only feeds belonging to a portal-approved merchant are polled. A source
whose merchant is suspended stops being polled immediately, mid-batch if
necessary.

What a sync does to your catalog

Each run reads your whole feed, validates every item, writes the valid
ones, and reports the rest. Each item is written in its own transaction,
so one bad row is one rejected row and never a rolled-back run.

partial counts as a working feed: your consecutive-failure count
resets, because items really did land.

A product that disappears is deactivated, not deleted

When a complete traversal doesn't mention a SKU that this feed created,
that product is set active: false. It is never deleted. Its
history stays intact, any in-flight reservation against it still
resolves, and it stops appearing in the catalog so no new
agent can buy it. List the SKU again in a later poll and it goes back on
sale with whatever the feed says.

Deactivation also requires that at least one item in the run was
accepted. A run in which nothing landed — an empty items array, or a
feed in which every single row was rejected — is far more likely a
broken endpoint than a merchant who has genuinely stopped selling
everything, so it deactivates nothing.

Only products this feed owns are touched. Hand-entered products, and
products from any other source, are invisible to deactivation — nothing
a feed does can take a product you typed in yourself off sale.

Note also that a SKU your feed named but we rejected is not a
vanished SKU. A typo'd currency on one row will get you a reject, not a
deactivated product.

An incomplete traversal deactivates nothing

If the run ended early for any reason — a cap, a cross-origin next, a
page that timed out, a page that 500'd — nothing is deactivated at
all. A run that died on page 2 of 5 hasn't established that anything
vanished, and treating it as if it had would turn a network blip into a
wiped catalog.

An incomplete traversal also does not count as fresh. Freshness is
measured from the last run that read your feed all the way through, so a
feed that keeps ending early is reported as stale in the portal even
though it's technically been polled every 15 minutes and its
consecutive-failure count is zero. That's deliberate: an incomplete run
refreshed page 1 and nothing else, and it left deactivation suppressed —
so a product you withdrew is still on sale, and you need to see that.

The portal warns once a feed's last complete run is more than an
hour old. Staleness never stops your products selling; it is a signal,
not a cutoff.

Stock is overwritten, not adjusted

Your stock_on_hand must already account for units sold through
moyasar-ac. Every poll overwrites our count with yours. If your
inventory system does not receive moyasar-ac orders, each poll
re-inflates stock by everything sold since your feed was generated,
and the difference is sold twice.

This is the contract, not a caveat. A sync writes stock_on_hand
absolutely — it never adds, subtracts, or reconciles against what we
previously had. Concretely, if you publish stock_on_hand: 10, we sell
3, and your next feed still says 10 because your warehouse system
never heard about those 3 orders, then we are back to 10 units for sale
against 7 on your shelf.

Two details make this sharper than it looks:

• Units reserved by an in-flight draw are tracked separately and are never overwritten by a feed. Availability is stock_on_hand - reserved_count; your feed owns the first number and only the draw path writes the second. If your feed reports stock lower than what's currently reserved, we write it through anyway and availability goes negative, which correctly refuses further sales rather than hiding the discrepancy.
• A sale that lands mid-sync loses to the feed, on purpose. If a charge captures against a product in the same instant we're writing it, the write is retried once from fresh state and re-applies your feed's number over the capture. The alternative — letting a stale in-flight write win — would be worse, but it does mean the feed is always the authority, including for a sale that completed seconds ago. If the same row is contended twice in a row, the item is reported as a reject and left for the next poll.

The safe pattern is: deduct moyasar-ac's captured orders in your own
system (via merchant webhooks or the
polling endpoints) before generating the feed,
and publish the resulting number. If you can't do that, publish a
conservative allocation you're prepared to lose — a fixed number of
units set aside for moyasar-ac — rather than your live shelf count.

Rejected items

An item that breaks a rule is rejected individually: it doesn't fail
the run, doesn't affect any other item, and doesn't change whatever we
already have stored for that SKU. Each run records its rejects as
sku / field / key + args, shown in the portal on the Inventory
screen as a sentence in the reader's language.
Up to 50 rejects are stored per run, with a count of any beyond
that, so a badly broken feed is never silently summarized as "50
problems".

Each item is reported with one reason — the first rule it breaks —
so fixing one row can reveal the next problem with it on the following
poll. Values echoed into a reason are truncated at 128 characters.

If the sku itself wasn't a usable string, the reject's sku is
null; there is nothing else we can honestly call the row. In that
case, deactivation is also suppressed for the whole run — we can't
establish which product was listed, and guessing is not acceptable when
the guess takes a live listing off sale.

Item validation errors

Every reason below is stored as a translation key and its values, and
assembled when someone opens the portal — so it appears in the language
of whoever is reading it, not the language the poller happened to run
in. The English wording is reproduced here; %{value} marks where your
own value is echoed back, and echoed values are bidi-isolated so a Latin
SKU or currency code doesn't reorder inside an Arabic sentence.

The field column is not translated in either direction: it names
the JSON key in your own feed, which is the thing you have to go and
edit.

Four more rejects come from writing the item rather than validating it:

Errors that fail the whole run

These are recorded once on the run, not per item, and nothing in your
catalog changes. Like the item rejects above, each is stored as a key
and assembled in the reader's language.

When your feed keeps failing

A feed that produces 10 consecutive failed runs is automatically
disabled, and we stop polling it. What that does and doesn't mean:

• Your products stay on sale. Being unable to reach your endpoint is our failure to observe your catalog, not a statement about it, so nothing is deactivated when the breaker trips. Stock ages instead, and the portal says so prominently.
• Any single non-failed run resets the count to zero. That includes a partial run — items landing means the feed works.
• Nothing re-enables it automatically. The portal shows a Re-enable button, which fetches one page of your feed and checks the envelope before clearing the breaker. If that page doesn't come back valid, the feed stays disabled — a click alone won't hand you a green tick over a feed that's still broken. Like every other outbound failure, a refusal here reports one generic message.
• The re-enable check is limited to 5 attempts per minute and reads a single page, so it is not a substitute for fixing the endpoint.
• Only one of these checks runs at a time across the whole platform, so if another merchant's check is in flight yours is declined with a message saying exactly that. It is not a statement about your feed, and nothing about your feed changes — but the attempt still counts against your five per minute, and a single check can hold the slot for up to 30 seconds, so wait about a minute rather than retrying immediately.

Disconnecting and reconnecting is still not the way to clear a
disabled feed: it makes every product that feed created hand-entered,
and the reconnected feed rejects all of them as SKU collisions until you
accept the offer to hand them over. That offer exists so the state is
recoverable — not so it becomes a routine. Use Re-enable.

Intent Mandates

An intent mandate is a capped, signed spending authorization scoped to
one user. It starts awaiting_approval and does nothing until the user
approves it through the hosted approval flow.

Requires a bearer token (see Authentication) with the
mandates:write scope.

Create a mandate

curl -X POST http://localhost:3000/v1/intent-mandates \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_identifier": "traveler@example.com",
    "currency": "SAR",
    "env": "sandbox",
    "total_cap_minor": 900000,
    "domain_id": "flight_booking",
    "not_valid_after": "2026-08-01T00:00:00Z",
    "intent_payload": {
      "description": "Business-class flight to Dubai",
      "flight": { "route": "RUH-DXB", "cabin": "business" }
    },
    "mandate_kind": "one_shot_multi_draw"
  }'

import httpx

resp = httpx.post(
    "http://localhost:3000/v1/intent-mandates",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "user_identifier": "traveler@example.com",
        "currency": "SAR",
        "env": "sandbox",
        "total_cap_minor": 900000,
        "domain_id": "flight_booking",
        "not_valid_after": "2026-08-01T00:00:00Z",
        "intent_payload": {
            "description": "Business-class flight to Dubai",
            "flight": {"route": "RUH-DXB", "cabin": "business"},
        },
        "mandate_kind": "one_shot_multi_draw",
    },
)
print(resp.json())

require "net/http"
require "json"

uri = URI("http://localhost:3000/v1/intent-mandates")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json",
                                "Authorization" => "Bearer #{access_token}")
req.body = {
  user_identifier: "traveler@example.com",
  currency: "SAR",
  env: "sandbox",
  total_cap_minor: 900000,
  domain_id: "flight_booking",
  not_valid_after: "2026-08-01T00:00:00Z",
  intent_payload: {
    description: "Business-class flight to Dubai",
    flight: { route: "RUH-DXB", cabin: "business" }
  },
  mandate_kind: "one_shot_multi_draw"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts JSON.parse(res.body)

Request fields

Product-driven mandates

Passing product_id (from GET /v1/catalog) changes how a
few fields are handled, because the listing itself is the source of
truth for a catalog purchase — an agent's own claims about it aren't
trusted:

• domain_id and currency are derived from the product and override whatever you sent for those fields — an agent-supplied value for either is treated as a stale or adversarial claim about a listing it doesn't own, not merely cross-checked against it. Because both are derived, you may also simply omit them on a product-driven request; currency is only validated after the listing's own value has been resolved, so omitting it is not an error here even though it's required for every other mandate. This applies to an outright invalid currency too — sending "GBP" alongside a product_id yields the listing's currency rather than a 422, since the field is overridden either way.
• If the resolved domain_id's schema declares a quantity field (today only retail_purchase does), intent_payload.quantity is forced to match product_quantity, overriding whatever you sent. The two are otherwise independent — product_quantity drives the price floor and the stock reservation, while intent_payload.quantity is what the hosted approval page shows the user verbatim before they sign. Reconciling them prevents a mandate where the user approves one number of units and the system charges and ships for another.
• total_cap_minor must be at least product.price_minor * product_quantity. This is a floor, not an equality check — a larger cap to cover tax, fees, or a tip is accepted — but a cap below that floor is rejected up front, since it would let the mandate the user approves diverge from what the merchant could legitimately draw.
• The product must have enough available stock (stock_on_hand - reserved_count) for product_quantity, or the request is rejected immediately — so a listing whose every unit is already reserved by an in-flight draw will refuse a new mandate. This is a fast-fail check only: it does not itself reserve stock, so a mandate created here can still be refused with product_out_of_stock at draw time.
• If the product has cancellation_policy_text and/or return_policy_text set, that text is copied verbatim into intent_payload before schema validation — but only for whichever of those two fields the resolved domain_id's schema actually declares (e.g. retail_purchase declares only return_policy_text; hotel_booking/car_rental/activity_booking declare only cancellation_policy_text). This way it's covered by the same signature the user's passkey later applies to the whole mandate, without ever tripping the schema's additionalProperties: false.
• If the intent_payload you sent does not already validate against the resolved domain_id's schema (e.g. it's a plain {"description": "..."}, the shape a caller with no domain-specific fields of its own — such as the MCP browse_catalog picker — actually has to send), retail_purchase derives one for you: variant from the product's own title (truncated to the schema's own 120-character limit — the title column itself has no length cap), quantity from product_quantity. This is only ever a fallback — a caller that already sent a complete, valid intent_payload (including a real return_policy_ack it obtained from the user) has it respected exactly as sent, never overwritten.
  
  return_policy_ack is never derived this way, on any domain — it is an acknowledgment, not a fact about the product, and this API will not assert the user agreed to a policy it never showed them. A product-driven retail_purchase mandate whose caller supplies no intent_payload fields of its own will therefore still 422 on return_policy_ack specifically — regardless of how long the underlying product's title is — never on variant/quantity/a disallowed description. Narrower than before, but still a real rejection until a caller (or a future approval-page flow) supplies a genuine one. hotel_booking/car_rental/activity_booking have no such fallback at all today — their required fields (booking dates, locations, guest counts) aren't facts a catalog listing carries in the first place, so a product-driven mandate on those domains still requires a caller-supplied intent_payload in full.

intent_payload for domain_id: "generic_purchase"

intent_payload for domain_id: "flight_booking"

intent_payload for domain_id: "hotel_booking"

intent_payload for domain_id: "car_rental"

intent_payload for domain_id: "activity_booking"

intent_payload for domain_id: "retail_purchase"

recurrence (only when mandate_kind: "recurring")

Mandate creation response

{
  "intent_mandate_id": "7f8639ee-7039-412e-ac87-503b8e9986f1",
  "approval_url": "http://localhost:3000/m/Z3su5K-CTVmk9Uhv5ZvO0CYyNByXpGnC34QeEVAqtNs",
  "draw_key": "wHyJGRAjTGmNDxDosja5Cc63sqgJK3qwG2fAa4X16tU"
}

Share approval_url with the user — nothing can be charged until they
complete the hosted approval flow there.

draw_key is a merchant secret, shown exactly once. It's the
credential a merchant uses to sign Draws requests against
this mandate. If your agent is acting on behalf of a merchant, relay
this value to them out-of-band — never log it or forward it into an
LLM's context (the MCP tool layer deliberately omits this field from
what it returns to a model — see MCP Tools).

Intent mandate errors

env: "sandbox" requests are never subject to the three live-mode checks
above.

Check mandate status

curl http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/status \
  -H "Authorization: Bearer $ACCESS_TOKEN"

resp = httpx.get(
    "http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/status",
    headers={"Authorization": f"Bearer {access_token}"},
)
print(resp.json())

uri = URI("http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/status")
req = Net::HTTP::Get.new(uri, "Authorization" => "Bearer #{access_token}")
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts JSON.parse(res.body)

Mandate status response

{
  "intent_mandate_id": "7f8639ee-7039-412e-ac87-503b8e9986f1",
  "status": "approved",
  "approved": true,
  "currency": "SAR",
  "total_cap_minor": 900000,
  "total_drawn_minor": 450000,
  "no_money_moved": false,
  "last_booking_status": "drawn",
  "payment_status": "captured",
  "latest_draw_charged_minor": 450000
}

status is one of draft, awaiting_approval, approved, revoked,
expired, exhausted, or suspended. Draws are refused while a mandate is
suspended — moyasar-ac found this mandate's recorded outcomes disagreeing
with the payment processor and paused it pending operator reconciliation.

total_drawn_minor is always present, including a genuine 0 — it's the
same cumulative captured-total field the merchant mandate
view already exposes, here alongside
total_cap_minor for the agent that created the mandate. This is the
figure to trust as "the amount charged": a mandate can draw more than
once (mandate_kind: "recurring", or a multi-draw one_shot_multi_draw),
and summing only the latest draw understates what has actually left the
account.

no_money_moved is the only field you may use to tell a user that
nothing was charged. It is true when this mandate has no payment record
of any kind, false otherwise — the same predicate the hosted receipt page
uses for its own version of that claim, so the two can never disagree.

last_booking_status and payment_status are null until a booking attempt
actually exists — a flight_booking mandate, or a retail_purchase/
generic_purchase mandate backed by a product_id, once
auto-draw has reserved a draw. last_booking_status
is complete_booking's own outcome word for the most
recent attempt (drawn, already_booked, cap_exhausted,
mandate_not_approved, not_ready, or a cart_signature_* refusal). It is
rewritten on every attempt — including the one the hosted receipt page
makes each time it is loaded, which typically turns drawn into
already_booked — but it never reflects the outcome of the async charge:
it describes whether a draw was placed, not whether it was paid.
payment_status is the linked draw's own status (pending, captured, or
failed) and is the field that actually distinguishes "still charging" from
"done" from "failed"; last_booking_status alone cannot, since it can still
read drawn after the charge has failed.

latest_draw_charged_minor is null until payment_status is captured —
once set it is the most recent draw's own amount (in the currency shown
above), never a placeholder and never 0 standing in for "nothing was
charged yet". It is deliberately not named charged_minor: on a
mandate with more than one captured draw it would read as the total while
actually reporting only the latest one (e.g. two SAR 100/200 captures would
report latest_draw_charged_minor: 20000 while SAR 300 had left the
account) — use total_drawn_minor for anything that needs "how much has
this mandate charged in total".

Only the agent that created a mandate can query its status — a mismatched
agent or unknown ID returns 404 {"error": "not_found"}.

Preview a mandate's cart

For a mandate on a completable domain — flight_booking, or
retail_purchase/generic_purchase backed by a product_id — auto-draw won't fire until the agent has signed the cart's
exact terms (see Submit a cart signature below)
— this endpoint returns that cart, unsigned, so the agent has something
concrete to sign. For a flight_booking mandate the fare is computed from
the mandate's intent_payload.flight fields and clamped to whatever remains
under total_cap_minor; for a catalog mandate the total is price_minor ×
product_quantity from the linked listing, and a price that no longer fits
the remaining cap is refused outright rather than clamped (see
price_changed below). Either way, the agent can't
use this endpoint to inflate or invent a price, only to see (and later
attest to) the terms moyasar-ac already decided. Only reachable for
mandates on a completable domain, owned by the requesting agent — any other
domain (e.g. hotel_booking) returns domain_not_supported.

curl http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/cart-preview \
  -H "Authorization: Bearer $ACCESS_TOKEN"

resp = httpx.get(
    "http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/cart-preview",
    headers={"Authorization": f"Bearer {access_token}"},
)
print(resp.json())

uri = URI("http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/cart-preview")
req = Net::HTTP::Get.new(uri, "Authorization" => "Bearer #{access_token}")
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts JSON.parse(res.body)

Cart preview response

{
  "intent_mandate_id": "7f8639ee-7039-412e-ac87-503b8e9986f1",
  "currency": "SAR",
  "line_items": [
    { "name": "Saudia RUH–DXB business", "amount_minor": 420000 }
  ],
  "total_minor": 420000
}

Cart preview errors

Submit a cart signature

Sign the exact cart returned by cart-preview
locally with your agent's own Ed25519 private key (the half moyasar-ac
never sees — see Cart signatures for the canonicalize/
sign/envelope steps, same rule here), then submit both the cart and the
signature envelope. moyasar-ac recomputes the cart itself from the
mandate rather than trusting what you send — your submitted cart must
byte-match that recomputation (via
RFC 8785 JCS) and your signature
must verify against it, or the request is rejected. Nothing is stored
until both checks pass. The stored signature is only consumed later, when
auto-draw actually reserves the charge — this
call doesn't draw anything by itself, and can be re-submitted (e.g. after
a fare changes) any time before that happens.

curl -X POST http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/cart-signature \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": {
      "intent_mandate_id": "7f8639ee-7039-412e-ac87-503b8e9986f1",
      "currency": "SAR",
      "line_items": [ { "name": "Saudia RUH–DXB business", "amount_minor": 420000 } ],
      "total_minor": 420000
    },
    "agent_signature": { "alg": "Ed25519", "kid": "a1b2c3d4e5f6a7b8", "value": "..." }
  }'

resp = httpx.post(
    "http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/cart-signature",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "cart": cart,  # exactly what cart-preview returned
        "agent_signature": {"alg": "Ed25519", "kid": signing_kid, "value": signature_b64url},
    },
)
print(resp.json())

uri = URI("http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/cart-signature")
req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json",
                                "Authorization" => "Bearer #{access_token}")
req.body = {
  cart: cart, # exactly what cart-preview returned
  agent_signature: { alg: "Ed25519", kid: signing_kid, value: signature_b64url }
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts JSON.parse(res.body)

Cart signature request fields

Cart signature response

{ "status": "pending" }

Cart signature errors

Complete a booking

Asks moyasar-ac to complete a mandate on a completable domain
(flight_booking, or retail_purchase/generic_purchase backed by a
product_id) now, instead of waiting for the background sweeper that
picks up approved, tokenized bookings on its own — the sweeper scans every
completable domain, not just flights. Call it once
status reports approved — by then the user has
approved the mandate and added a card, which is everything completion needs.

POST /v1/intent-mandates/:id/complete-booking

This endpoint grants no authority the sweeper doesn't already have; it only
changes when the same work happens. It is idempotent — the draw is
serialized on the mandate's draw key, so calling it repeatedly (or racing it
against the sweeper, or against the user loading the receipt page) can
produce at most one booking. The charge itself is reserved through the same
draw validation path a merchant would use, so every cap, expiry,
and cart-signature check still applies, and a refusal is returned to you
rather than retried.

curl -X POST http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/complete-booking \
  -H "Authorization: Bearer $ACCESS_TOKEN"

resp = httpx.post(
    "http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/complete-booking",
    headers={"Authorization": f"Bearer {access_token}"},
)
print(resp.json())

uri = URI("http://localhost:3000/v1/intent-mandates/7f8639ee-7039-412e-ac87-503b8e9986f1/complete-booking")
req = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{access_token}")
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts JSON.parse(res.body)

Complete booking response

{ "status": "drawn" }

A 200 is returned for every outcome, including a refusal — the outcome is
in status, not the HTTP code. Only transport/authorization problems use a
non-200 code (see the error table below).

Only cap_exhausted and mandate_not_approved are treated as final. Every
other refusal — including price_changed — is one the background sweeper
will keep retrying for as long as its 24-hour window lasts, so the user's
booking page shows the reason without claiming the booking is over — see
Auto-draw and receipt.

Complete booking errors

Merchant view of a mandate

A separate, merchant-authenticated endpoint (same credential scheme as
Draws) returns a redacted view — the financial envelope and
intent, never the user's identity:

GET /v1/intent-mandates/:id

Merchant mandate view response

{
  "id": "7f8639ee-7039-412e-ac87-503b8e9986f1",
  "status": "approved",
  "currency": "SAR",
  "env": "sandbox",
  "total_cap_minor": 900000,
  "per_draw_cap_minor": null,
  "total_drawn_minor": 420000,
  "pending_amount_minor": 0,
  "not_valid_before": null,
  "not_valid_after": "2026-08-01T00:00:00Z",
  "domain_id": "flight_booking",
  "intent_payload": { "description": "Business-class flight to Dubai", "flight": { "route": "RUH-DXB", "cabin": "business" } }
}

Draws

A draw is a merchant-initiated charge against an approved mandate.
Unlike every other endpoint on this page, draws don't use a bearer
token — they use a merchant API key plus an HMAC-SHA256 request
signature, so a compromised network intermediary can't replay or tamper
with a charge request.

Getting merchant credentials: sign up at /merchant/applications/new
in the merchant portal. Your merchant_id and initial API key are
minted immediately at signup — the key is shown once, on that screen,
and never again. The key authenticates straight away, but draws are
refused with merchant_not_portal_approved until an operator approves
your application. See
Rotating your key below for how to replace it
later without an integration outage.

Authentication scheme

Every request needs:

• Authorization: Merchant <your-api-key>
• X-Merchant-Id: <your-merchant-id>
• X-Mandate-Id: <the intent_mandate_id you're drawing against>
• X-Nonce: <a fresh random value per request>
• X-Timestamp: <current time, ISO 8601, must be within 5 minutes>
• X-Idempotency-Key: <a key you control — retrying with the same key returns the original response instead of double-charging>
• X-Signature: <computed below>

Computing the signature

1. Build the canonical string — nine fields joined by \n, in this exact order:

   METHOD
   HOST
   PATH
   base64url(SHA256(raw request body bytes))
   mandate_id
   merchant_id
   nonce
   timestamp
   idempotency_key

1. X-Signature = base64url(HMAC-SHA256(draw_key_secret, canonical_string))

draw_key_secret is the draw_key value returned once when the
mandate was created.

base64url here means standard base64 with +→-, /→_, and
= padding stripped (RFC 4648 §5).

Rotating your key

Replace your API key at any time from the merchant portal, at
/merchant/api-keys — there is no API for this in v1. Rotating:

1. Mints a new key immediately and shows it to you once — copy it before you navigate away, the same as a webhook signing secret.
2. Requires you to pick a retirement date for the key being replaced, strictly in the future and no more than 90 days out. This is mandatory: an old key with no deadline is a permanent security hole, so moyasar-ac refuses to rotate without one, and refuses a date far enough out to amount to the same thing. Within that 90-day ceiling, you pick the date, not moyasar-ac — we don't know your deploy schedule, and a platform-chosen window would either cut you off mid-rollout or leave a leaked key alive too long.
3. Both the new key and the outgoing one authenticate every request until the outgoing one's retirement date passes or you disable it — check its last used time on the portal before that date to confirm your integration has actually switched over.

You can also disable the outgoing key immediately, before its
scheduled retirement, from the same screen — useful if you rotated
because a key leaked and can't wait out the grace period.

You can hold at most two live keys at a time. While you already
hold two, rotating again is refused until one of them stops being live
— either its retirement date passes or you disable it. This keeps the
number of keys the platform authenticates against per request bounded,
so it isn't something a rotation loop can inflate.

The cap counts live keys, not outgoing ones, so the leaked-key path
stays open: if you rotate and then immediately disable the new
current key because it leaked, you are down to one live key and can
rotate again straight away.

Key states

Every key you hold is in exactly one of these states, shown on
/merchant/api-keys alongside the time it was last used to
authenticate a request:

Disabled wins over expired: a key you disabled stays reported as
disabled even after its retirement date goes by.

When a key stops working

Expiry is evaluated on every authenticated request, against the
clock at that moment — it is not applied by a nightly job or any other
background sweep. The practical consequence is that a retirement date
is exact: the last request before it passes succeeds, and the next one
does not. Disabling a key behaves the same way, taking effect on the
very next request rather than at some later sweep.

A request presenting an expired or disabled key — or simply the wrong
key — is refused identically:

Response 401 Unauthorized

{
  "error": "unauthorized"
}

There is no distinct error for "your key expired": moyasar-ac does not
tell an unauthenticated caller why a key was rejected, so treat
401 unauthorized on a previously working integration as "this key is
no longer live — deploy the new one".

Watch the "last used" column, not the calendar. It is stamped every
time a key successfully authenticates a request, so it is the direct
answer to the only question that matters before a retirement date
arrives: has anything still got the old key? An outgoing key whose last
used time keeps advancing is an outage scheduled for that date.

HOST is a configured value, not the literal address you connect
to: the server signs against MERCHANT_API_HOST (Rails config
config.x.merchant_api_host), which may differ from the host/port
you're actually connecting to. The samples below use
HOST="localhost:3000" because that matches a server explicitly
configured with MERCHANT_API_HOST=localhost:3000 — if your server
uses a different value (the default is moyasar-ac.local), use that
value instead or you'll get 401 signature_invalid.

Create a draw

#!/usr/bin/env bash
HOST="localhost:3000"
PATH_="/v1/draws"
MANDATE_ID="7f8639ee-7039-412e-ac87-503b8e9986f1"
MERCHANT_ID="your-merchant-id"
DRAW_KEY_SECRET="the-draw_key-from-mandate-creation"
# cart's agent_signature/merchant_signature are computed as described in
# "Cart signatures" below -- omitted here for brevity, shown as an example shape.
BODY='{"amount_minor":420000,"currency":"SAR","cart":{"line_items":[{"sku":"seat-2a","amount_minor":420000}],"total_minor":420000,"agent_signature":{"alg":"Ed25519","kid":"a1b2c3d4e5f6a7b8","value":"..."},"merchant_signature":{"alg":"Ed25519","kid":"1a2b3c4d5e6f7a8b","value":"..."}}}'
NONCE=$(openssl rand -hex 16)
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
IDEMPOTENCY_KEY=$(uuidgen)

b64url() { base64 | tr '+/' '-_' | tr -d '=\n'; }
BODY_SHA=$(printf '%s' "$BODY" | openssl dgst -sha256 -binary | b64url)
CANONICAL=$(printf 'POST\n%s\n%s\n%s\n%s\n%s\n%s\n%s\n%s' \
  "$HOST" "$PATH_" "$BODY_SHA" "$MANDATE_ID" "$MERCHANT_ID" "$NONCE" "$TIMESTAMP" "$IDEMPOTENCY_KEY")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$DRAW_KEY_SECRET" -binary | b64url)

curl -X POST "http://$HOST$PATH_" \
  -H "Content-Type: application/json" \
  -H "Authorization: Merchant your-merchant-api-key" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Mandate-Id: $MANDATE_ID" \
  -H "X-Nonce: $NONCE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

import base64
import hashlib
import hmac
import httpx
import uuid
from datetime import datetime, timezone

def b64url(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

host = "localhost:3000"
path = "/v1/draws"
mandate_id = "7f8639ee-7039-412e-ac87-503b8e9986f1"
merchant_id = "your-merchant-id"
draw_key_secret = "the-draw_key-from-mandate-creation"
# cart's agent_signature/merchant_signature are computed as described in
# "Cart signatures" below -- omitted here for brevity, shown as an example shape.
body = (
    b'{"amount_minor":420000,"currency":"SAR","cart":{"line_items":'
    b'[{"sku":"seat-2a","amount_minor":420000}],"total_minor":420000,'
    b'"agent_signature":{"alg":"Ed25519","kid":"a1b2c3d4e5f6a7b8","value":"..."},'
    b'"merchant_signature":{"alg":"Ed25519","kid":"1a2b3c4d5e6f7a8b","value":"..."}}}'
)
nonce = uuid.uuid4().hex
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
idempotency_key = str(uuid.uuid4())

body_sha = b64url(hashlib.sha256(body).digest())
canonical = "\n".join([
    "POST", host, path, body_sha, mandate_id, merchant_id, nonce, timestamp, idempotency_key,
])
signature = b64url(hmac.new(draw_key_secret.encode(), canonical.encode(), hashlib.sha256).digest())

resp = httpx.post(
    f"http://{host}{path}",
    content=body,
    headers={
        "Content-Type": "application/json",
        "Authorization": "Merchant your-merchant-api-key",
        "X-Merchant-Id": merchant_id,
        "X-Mandate-Id": mandate_id,
        "X-Nonce": nonce,
        "X-Timestamp": timestamp,
        "X-Idempotency-Key": idempotency_key,
        "X-Signature": signature,
    },
)
print(resp.status_code, resp.json())

require "net/http"
require "json"
require "openssl"
require "base64"
require "securerandom"
require "time"

def b64url(bytes)
  Base64.strict_encode64(bytes).tr("+/", "-_").delete("=")
end

host = "localhost:3000"
path = "/v1/draws"
mandate_id = "7f8639ee-7039-412e-ac87-503b8e9986f1"
merchant_id = "your-merchant-id"
draw_key_secret = "the-draw_key-from-mandate-creation"
# cart's agent_signature/merchant_signature are computed as described in
# "Cart signatures" below -- omitted here for brevity, shown as an example shape.
body = {
  amount_minor: 420_000, currency: "SAR",
  cart: {
    line_items: [ { sku: "seat-2a", amount_minor: 420_000 } ], total_minor: 420_000,
    agent_signature: { alg: "Ed25519", kid: "a1b2c3d4e5f6a7b8", value: "..." },
    merchant_signature: { alg: "Ed25519", kid: "1a2b3c4d5e6f7a8b", value: "..." }
  }
}.to_json
nonce = SecureRandom.hex(16)
timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
idempotency_key = SecureRandom.uuid

body_sha = b64url(OpenSSL::Digest::SHA256.digest(body))
canonical = ["POST", host, path, body_sha, mandate_id, merchant_id, nonce, timestamp, idempotency_key].join("\n")
signature = b64url(OpenSSL::HMAC.digest("SHA256", draw_key_secret, canonical))

uri = URI("http://#{host}#{path}")
req = Net::HTTP::Post.new(uri,
  "Content-Type" => "application/json",
  "Authorization" => "Merchant your-merchant-api-key",
  "X-Merchant-Id" => merchant_id,
  "X-Mandate-Id" => mandate_id,
  "X-Nonce" => nonce,
  "X-Timestamp" => timestamp,
  "X-Idempotency-Key" => idempotency_key,
  "X-Signature" => signature)
req.body = body
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts res.body

Request body

Cart signatures

The cart object must be independently signed by both the agent and
the merchant, each with the Ed25519 keypair registered for their
signing_kid (provisioned out-of-band alongside your API key — there's
no self-service key-registration endpoint in this PoC yet). The signature
makes the cart's contents tamper-evident (any edit after signing
invalidates it), and the cart's total_minor is additionally required to
equal the request's top-level amount_minor (and, when the cart declares
them, its currency/intent_mandate_id must match the request/mandate
too) — so a validly-signed cart for one set of terms can't be submitted
against a different charge. A tampered or mismatched cart is rejected
before it can consume a nonce-replay slot.

1. Canonicalize the cart excluding the agent_signature and merchant_signature keys themselves, using RFC 8785 JSON Canonicalization Scheme (JCS).
2. Ed25519-sign the canonical bytes with the signer's private key.
3. Attach the result as an envelope:

   {
     "alg": "Ed25519",
     "kid": "<the signer's registered signing_kid>",
     "value": "<base64url(signature), no padding>"
   }

Each envelope's kid must exactly equal that party's own registered
signing_kid — the public key used to verify is always looked up from
the agent/merchant record itself, never from anything inside the cart
payload, which closes a kid-confusion attack a naive "verify against
whatever kid the payload claims" implementation would open.

{
  "line_items": [ { "sku": "seat-2a", "amount_minor": 420000 } ],
  "total_minor": 420000,
  "agent_signature": { "alg": "Ed25519", "kid": "a1b2c3d4e5f6a7b8", "value": "..." },
  "merchant_signature": { "alg": "Ed25519", "kid": "1a2b3c4d5e6f7a8b", "value": "..." }
}

Response 202 Accepted

{
  "payment_mandate_id": "215066c6-9d23-435e-8154-f02df48b44fd",
  "status": "pending"
}

The charge is reserved and processed asynchronously; poll the mandate's
status or the merchant view to see it move to
captured.

Want to know when this settles, without polling in a loop? Register a
merchant webhook endpoint and subscribe to
draw.captured/draw.failed — moyasar-ac pushes the event to you. Webhooks
are best-effort, though; GET /v1/draws/:id below remains the endpoint you
reconcile against.

For a live mandate, the platform-wide kill switch is re-checked a
second time immediately before the actual capture call — not just at
reservation time — since capture happens later in a background job on
its own schedule. If the kill switch is thrown after a draw is reserved
but before it captures, the draw fails closed: it stays pending
(never failed, and the reserved hold is never released). Once live
mode is re-armed, a background sweeper picks the draw back up and
retries the charge — a kill-switch strand is provably never sent to
the payment processor, so resuming it is safe. sandbox draws are
never affected.

A draw whose charge response was lost is resolved automatically.
If a charge was sent to the payment processor but its response never
came back, the platform looks the payment up by a deterministic
identifier derived from the draw itself, and settles it either way: if
the payment exists it is reconciled to captured or failed as
normal; if the processor confirms no such payment was ever created, the
draw is failed and its reserved stock released. Where the charge does
have to be re-sent, the processor's own idempotency returns the original
payment rather than creating a second one, so a draw is never charged
twice.

A draw only stays pending indefinitely when that lookup itself cannot
be completed — the processor is unreachable, so there is no evidence in
either direction. Those draws are surfaced to an operator for manual
reconciliation rather than guessed at, because recording a failure that
did not happen would release stock and mandate headroom for a payment
that may have succeeded, and there is no automated refund path to
reverse it. Treat pending as "outcome not yet known", never as
"not charged".

Draw errors

Stock moves in two steps rather than one. A draw against a
product-linked mandate reserves product_quantity units — it
increments the product's reserved_count and leaves stock_on_hand
untouched — which is what makes the units unavailable to anyone else.
The reservation then resolves exactly once:

• Captured: the units are consumed. stock_on_hand and reserved_count both drop, because the units have genuinely left the merchant's shelf.
• Terminal failure (webhook or charge response reports one): the reservation is released. Only reserved_count drops; stock_on_hand is never touched, because the units were never sold. A legitimate retry is then treated as a fresh attempt rather than being wrongly blocked or double-counted.

Because a failure never writes stock_on_hand, a merchant can restate
their on-hand figure at any time — including while a draw is still
settling — without that edit being inflated or deflated by the draw's
later outcome.

Only one draw at a time may hold a product mandate's reservation. A second
draw attempted while the first is still settling is refused with
product_draw_in_flight rather than sharing the reservation — together with
product_already_purchased, that is what enforces the rule that a product-linked
mandate consumes at most product_quantity units in total. A draw attempted
after an earlier one failed is accepted normally, because the failure released
the reservation.

A retried request with the same X-Idempotency-Key and the same
semantic fields (method/host/path/body-hash/mandate/merchant/amount)
returns the original response instead of creating a second charge —
safe to retry on a network timeout.

Merchant webhooks

Subscribe your endpoint to the draw lifecycle events you care about and
moyasar-ac pushes them to you as they happen. Nothing is delivered until
you both register an endpoint and subscribe it to an event type —
an unsubscribed merchant receives nothing.

Webhooks are best-effort. Polling is authoritative.
Delivery is retried on a fixed ladder and then given up on; a network
partition, a redeploy of your receiver, or an endpoint that fails for
long enough can all mean an event you were supposed to get never
arrives. Treat webhooks as a low-latency notification channel and the
polling endpoints below as the source of truth you reconcile against.

Registering an endpoint

Endpoints are registered from the merchant portal, at /merchant/webhook
— there is no API for this in v1. The flow:

1. Submit your https:// URL and pick the event types you want (draw.reserved, draw.captured, draw.failed).
2. moyasar-ac immediately sends the challenge handshake to that URL. Nothing is delivered until it succeeds.
3. On success, the portal shows you a signing secret once. It is never shown again and isn't recoverable — store it before you navigate away.

There is no recovery path for a lost secret in v1. Changing your
endpoint's URL re-runs the challenge handshake, but it does not mint a
new secret — the secret is set once, at registration, and never
changes for the life of the endpoint. There is also no way to
re-register: a merchant may only ever have one endpoint, and
registering again while one already exists is refused. Secret
rotation is explicitly out of scope for v1 (a future kid-based
dual-validity rotation is schema-possible, not shipped). If you lose
the secret, there is nothing to do about it from the portal today.

The registration and edit forms refuse a URL that:

• doesn't use https://
• carries userinfo (https://user:pass@host/...)
• resolves (at registration time, and again every time we're about to send) to a private, loopback, link-local, CGNAT, or multicast address, or to one of moyasar-ac's own hostnames
• uses any port other than 443 — see below

moyasar-ac never follows a redirect while registering or delivering to
your endpoint: a 3xx response is treated as a failure, not a hop to
follow.

Port 443 is required. Your endpoint must be https:// on port 443.
A URL with any other port — for example
https://hooks.example.com:8443/mac — is rejected at registration and
never contacted. If your receiver listens elsewhere, put it behind a
443 front door.

Editing your subscribed event types alone does not re-trigger the
challenge — nothing about proof of control over the URL changed.
Changing the URL itself always re-demotes the endpoint to
unverified and re-runs the handshake, because control of the old
address proves nothing about the new one.

The challenge handshake

On registration, and again on any URL change, moyasar-ac POSTs your
endpoint:

{ "type": "webhook.verification", "challenge": "<random token>" }

Respond 2xx and echo the token back, in either of two shapes:

{ "challenge": "<the same token>" }

or as the raw response body — a plain-text <the same token> with
nothing else in it.

Anything else — a non-2xx status, a redirect, a timeout, TLS failure,
or a body that doesn't echo the current token — fails verification, and
your endpoint stays (or becomes) unverified. Every failure mode shows
the merchant the same one generic message:

Verification failed — check that your endpoint echoes the challenge
over HTTPS.

This is deliberate: a message that distinguished "refused" from
"timed out" from "wrong body" would turn the registration form into a
port-scan oracle against arbitrary hosts. The specific reason is logged
internally; only the generic message reaches the portal.

There is exactly one other message, and it is not a verification
result:

We're checking another endpoint right now — wait about a minute and
try again.

Only one verification runs at a time across the whole platform, so if
another is in flight yours is declined without your endpoint being
contacted at all. Nothing about your endpoint changes — not its status,
not its challenge token. It is reported separately from a failure
precisely because telling you verification failed when we never called
you would send you rewriting a handler that works. It says nothing about
any address, so it is not the oracle the rule above prevents.

No event is ever delivered to an unverified endpoint.

Verifying a delivery signature

Every delivery carries five headers:

To verify a delivery:

1. Build the signed string: "#{X-MoyasarAc-Timestamp}.#{raw request body}" — the timestamp header, a literal ., then the exact bytes of the request body (no re-serialization).
2. Compute HMAC-SHA256 of that string using your endpoint's signing secret (shown once at registration), and lowercase-hex-encode it.
3. Compare your result to the value after v1= in X-MoyasarAc-Signature, using a constant-time comparison — not ==.
4. Reject the delivery if X-MoyasarAc-Timestamp is further from your own clock than the skew tolerance you choose to enforce. moyasar-ac doesn't impose one on you; pick something that comfortably covers clock drift and retry latency (a few minutes is reasonable).

The version prefix is there on purpose: a future v2 scheme would be an
additional header value, never a replacement of what v1= means, so
verifying against v1= specifically continues to work indefinitely.

Worked example

The exact inputs below are reproduced verbatim from this repo's
MerchantWebhooks::SignTest — the normative source. Run any of these
three samples and you should get exactly this signature back.

• Secret: 3vZq1c9x8Kx0m2p5s7Q_bJ8tW4nR6yF1aH0dL2gU3kE
• Timestamp: 1767225600
• Body (300 bytes): json {"type":"draw.captured","delivery_id":"6f1c2b7e-0d3a-4c5b-9e8f-1a2b3c4d5e6f","occurred_at":"2026-01-01T00:00:00Z","data":{"payment_mandate_id":"7f8639ee-7039-412e-ac87-503b8e9986f1","intent_mandate_id":"b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091","amount_minor":42000,"currency":"SAR","status":"captured"}}
• Expected signature: v1=ba6ca1c8f91cefaa3e8c0f2c3878307d1cd61f3f1b164544d4c2e5cbca20f6ab

SECRET="3vZq1c9x8Kx0m2p5s7Q_bJ8tW4nR6yF1aH0dL2gU3kE"
TIMESTAMP="1767225600"
BODY='{"type":"draw.captured","delivery_id":"6f1c2b7e-0d3a-4c5b-9e8f-1a2b3c4d5e6f","occurred_at":"2026-01-01T00:00:00Z","data":{"payment_mandate_id":"7f8639ee-7039-412e-ac87-503b8e9986f1","intent_mandate_id":"b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091","amount_minor":42000,"currency":"SAR","status":"captured"}}'

printf '%s.%s' "$TIMESTAMP" "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1
# => ba6ca1c8f91cefaa3e8c0f2c3878307d1cd61f3f1b164544d4c2e5cbca20f6ab
# Prefix with "v1=" for the full header value.

import hashlib
import hmac

secret = "3vZq1c9x8Kx0m2p5s7Q_bJ8tW4nR6yF1aH0dL2gU3kE"
timestamp = "1767225600"
body = (
    b'{"type":"draw.captured","delivery_id":"6f1c2b7e-0d3a-4c5b-9e8f-1a2b3c4d5e6f",'
    b'"occurred_at":"2026-01-01T00:00:00Z","data":{"payment_mandate_id":'
    b'"7f8639ee-7039-412e-ac87-503b8e9986f1","intent_mandate_id":'
    b'"b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091","amount_minor":42000,"currency":"SAR",'
    b'"status":"captured"}}'
)
signed_string = f"{timestamp}.".encode() + body
signature = "v1=" + hmac.new(secret.encode(), signed_string, hashlib.sha256).hexdigest()
assert signature == "v1=ba6ca1c8f91cefaa3e8c0f2c3878307d1cd61f3f1b164544d4c2e5cbca20f6ab"

require "openssl"

secret = "3vZq1c9x8Kx0m2p5s7Q_bJ8tW4nR6yF1aH0dL2gU3kE"
timestamp = "1767225600"
body = '{"type":"draw.captured","delivery_id":"6f1c2b7e-0d3a-4c5b-9e8f-1a2b3c4d5e6f",' \
       '"occurred_at":"2026-01-01T00:00:00Z","data":{"payment_mandate_id":' \
       '"7f8639ee-7039-412e-ac87-503b8e9986f1","intent_mandate_id":' \
       '"b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091","amount_minor":42000,"currency":"SAR",' \
       '"status":"captured"}}'

signed_string = "#{timestamp}.#{body}"
signature = "v1=" + OpenSSL::HMAC.hexdigest("SHA256", secret, signed_string)
raise unless signature == "v1=ba6ca1c8f91cefaa3e8c0f2c3878307d1cd61f3f1b164544d4c2e5cbca20f6ab"

Event reference

Every delivery is a JSON envelope:

data:

Not included, by design: decline/failure reasons, card or token
data, and any user identifier. The customer relationship is with the
operator, not the merchant, and a merchant has no channel to act on
processor-internal decline classification anyway — see
Errors if you need the shape of a rejected inbound draw
request instead.

Delivery, retries and idempotency

Respond promptly. Every request we make to your endpoint — the
verification challenge and each delivery attempt alike — is abandoned if
connect, send and the complete response haven't finished within 15
seconds, no matter how slowly the bytes arrive. Do your own processing
after you've answered, not before.

A failed attempt (a non-2xx response, a timeout, or any transport
error) is retried on a fixed ladder: 1 minute, 10 minutes, 30
minutes, 1 hour, 2 hours after the previous attempt. That's five
retries plus the original attempt — six attempts total — after
which the event is given up on and shown as exhausted in your portal
delivery log.

X-MoyasarAc-Delivery is the same value on every attempt of a
given event, including retries. De-duplicate on it: if you've already
processed a delivery with this id, it's safe to acknowledge and ignore
a repeat.

If an endpoint racks up 25 consecutive failed attempts (across any
mix of events, not 25 failures of one event), it is automatically
disabled: its undelivered events are dropped, and you'll need to
re-verify it (re-running the challenge handshake)
before anything is delivered to it again. Any single 2xx resets the
consecutive-failure count to zero.

Self-service resend, from the portal, re-queues your exhausted
deliveries from the last 7 days. It doesn't retroactively deliver
anything older, and it's bounded per request — it exists for
"my endpoint was down for an hour, catch me up," not for replaying your
whole history.

Your subscription list is checked only once, when an event is queued
for you — not again right before it's sent. If you unsubscribe from
an event type after one was already queued, that in-flight event is
still delivered; unsubscribing only stops future events from being
queued. (Your endpoint's own verified-vs-disabled status is different:
that is re-checked immediately before every send, so an endpoint
that becomes unverified between emission and send has its queued
events exhausted rather than sent.) This is intentional — a queued
row already represented a correct decision when it was made — but it
means "I just unsubscribed" is not a guarantee that nothing more
shows up.

Ordering — read this

Attempts to a single endpoint are serialized — moyasar-ac never sends
two deliveries to the same endpoint concurrently. But serialized is
not the same as in lifecycle order: because failed attempts retry on
a ladder, a later event can be delivered before an earlier one finally
succeeds. Concretely, a draw.reserved that hits a flaky retry can
arrive after the draw.captured for the same draw.

Do not assume you'll see reserved before captured before failed.
Treat every delivery as an independent fact about a draw at a point in
time, and key fulfillment off draw.captured's own payload rather than
off having previously seen a draw.reserved for the same id.

Limitation: reversals are not notified

A payment this subsystem reports as captured can still be refunded or
voided later, directly at the payment processor. v1 has no
correction event — there is no draw.reversed or equivalent, so
nothing is pushed to you when that happens.

Concretely: if you fulfil (ship a product, grant access, etc.) as soon
as you receive draw.captured, you may be fulfilling against money
that is later reversed. The polling endpoints
below always return the draw's current truth, so re-polling a draw
you consider closed would show you the reversal — but nothing prompts
you to do that re-poll. A draw.reversed event is the planned
successor to close this gap; it does not exist yet.

Polling (authoritative)

Both endpoints below use the same request-signing scheme as
Draws — a merchant API key plus the
nine-field canonical string, HMAC-signed
with your draw_key_secret. Two differences for a GET with no body:

• the body-hash field is base64url(SHA256("")) — the hash of an empty string, since there is no request body to hash
• the X-Idempotency-Key field in the canonical string is empty, and the header itself is omitted from the request entirely (there's nothing to make idempotent about a read)

GET /v1/draws/:id

HOST="localhost:3000"
PATH_="/v1/draws/7f8639ee-7039-412e-ac87-503b8e9986f1"
MANDATE_ID="b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091"
MERCHANT_ID="your-merchant-id"
DRAW_KEY_SECRET="the-draw_key-from-mandate-creation"
NONCE=$(openssl rand -hex 16)
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

b64url() { base64 | tr '+/' '-_' | tr -d '=\n'; }
BODY_SHA=$(printf '' | openssl dgst -sha256 -binary | b64url)
# The idempotency-key field is empty, so the canonical string must end in a
# bare trailing newline -- built as $(...)$'\n' rather than a trailing %s "",
# because command substitution silently strips a trailing newline captured
# via $(...) and would otherwise sign one byte short of the real string.
CANONICAL="$(printf 'GET\n%s\n%s\n%s\n%s\n%s\n%s\n%s' \
  "$HOST" "$PATH_" "$BODY_SHA" "$MANDATE_ID" "$MERCHANT_ID" "$NONCE" "$TIMESTAMP")"$'\n'
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$DRAW_KEY_SECRET" -binary | b64url)

curl "http://$HOST$PATH_" \
  -H "Authorization: Merchant your-merchant-api-key" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Mandate-Id: $MANDATE_ID" \
  -H "X-Nonce: $NONCE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

import base64
import hashlib
import hmac
import httpx
import uuid
from datetime import datetime, timezone

def b64url(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

host = "localhost:3000"
path = "/v1/draws/7f8639ee-7039-412e-ac87-503b8e9986f1"
mandate_id = "b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091"
merchant_id = "your-merchant-id"
draw_key_secret = "the-draw_key-from-mandate-creation"
nonce = uuid.uuid4().hex
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

body_sha = b64url(hashlib.sha256(b"").digest())
canonical = "\n".join([
    "GET", host, path, body_sha, mandate_id, merchant_id, nonce, timestamp, "",
])
signature = b64url(hmac.new(draw_key_secret.encode(), canonical.encode(), hashlib.sha256).digest())

resp = httpx.get(
    f"http://{host}{path}",
    headers={
        "Authorization": "Merchant your-merchant-api-key",
        "X-Merchant-Id": merchant_id,
        "X-Mandate-Id": mandate_id,
        "X-Nonce": nonce,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    },
)
print(resp.status_code, resp.json())

require "net/http"
require "json"
require "openssl"
require "base64"
require "securerandom"
require "time"

def b64url(bytes)
  Base64.strict_encode64(bytes).tr("+/", "-_").delete("=")
end

host = "localhost:3000"
path = "/v1/draws/7f8639ee-7039-412e-ac87-503b8e9986f1"
mandate_id = "b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091"
merchant_id = "your-merchant-id"
draw_key_secret = "the-draw_key-from-mandate-creation"
nonce = SecureRandom.hex(16)
timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")

body_sha = b64url(OpenSSL::Digest::SHA256.digest(""))
canonical = ["GET", host, path, body_sha, mandate_id, merchant_id, nonce, timestamp, ""].join("\n")
signature = b64url(OpenSSL::HMAC.digest("SHA256", draw_key_secret, canonical))

uri = URI("http://#{host}#{path}")
req = Net::HTTP::Get.new(uri,
  "Authorization" => "Merchant your-merchant-api-key",
  "X-Merchant-Id" => merchant_id,
  "X-Mandate-Id" => mandate_id,
  "X-Nonce" => nonce,
  "X-Timestamp" => timestamp,
  "X-Signature" => signature)
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts res.body

GET /v1/draws/:id response fields

The optional trio (merchant_idempotency_key, product_id, sku) is
absent as a key, not present-and-null, exactly matching the
webhook payload's "or absent" contract — one shape
across both transports.

Each entry in notifications is one delivery attempt row:

notifications never includes a delivery's body or headers — only
ids, statuses and counts.

GET /v1/intent-mandates/:id/draws

Every draw against your mandate, paginated — including draws you never
asked for and hold no id for, because they were created by the flow's
agent or by the hosted approval page rather than by your own
POST /v1/draws call. This is how you catch up on agent-initiated
draws.

Signed exactly like GET /v1/draws/:id above — same canonical string
shape, same empty-body-hash and empty-idempotency-key convention. The
path is different, though, and PATH is one of the nine signed
fields: the samples below are fully self-contained and recompute their
own signature over /v1/intent-mandates/:id/draws — do not reuse the
$SIGNATURE/$NONCE/$TIMESTAMP from the GET /v1/draws/:id sample
above, they were computed against a different path and will not verify
here.

PATH in the canonical string is the bare path only —
/v1/intent-mandates/:id/draws, without the ?since=...&limit=...
query string. since and limit are not signed; only the path,
method, mandate/merchant ids, nonce, timestamp and (empty) body/
idempotency-key fields are.

HOST="localhost:3000"
PATH_="/v1/intent-mandates/b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091/draws"
MANDATE_ID="b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091"
MERCHANT_ID="your-merchant-id"
DRAW_KEY_SECRET="the-draw_key-from-mandate-creation"
NONCE=$(openssl rand -hex 16)
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

b64url() { base64 | tr '+/' '-_' | tr -d '=\n'; }
BODY_SHA=$(printf '' | openssl dgst -sha256 -binary | b64url)
# The idempotency-key field is empty, so the canonical string must end in a
# bare trailing newline -- built as $(...)$'\n' rather than a trailing %s "",
# because command substitution silently strips a trailing newline captured
# via $(...) and would otherwise sign one byte short of the real string.
CANONICAL="$(printf 'GET\n%s\n%s\n%s\n%s\n%s\n%s\n%s' \
  "$HOST" "$PATH_" "$BODY_SHA" "$MANDATE_ID" "$MERCHANT_ID" "$NONCE" "$TIMESTAMP")"$'\n'
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$DRAW_KEY_SECRET" -binary | b64url)

# The query string rides along on the request URL; it is NOT part of $PATH_ above.
curl "http://$HOST$PATH_?since=2026-01-01T00:00:00Z&limit=50" \
  -H "Authorization: Merchant your-merchant-api-key" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Mandate-Id: $MANDATE_ID" \
  -H "X-Nonce: $NONCE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"

import base64
import hashlib
import hmac
import httpx
import uuid
from datetime import datetime, timezone

def b64url(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

host = "localhost:3000"
path = "/v1/intent-mandates/b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091/draws"
mandate_id = "b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091"
merchant_id = "your-merchant-id"
draw_key_secret = "the-draw_key-from-mandate-creation"
nonce = uuid.uuid4().hex
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

body_sha = b64url(hashlib.sha256(b"").digest())
# PATH here is the bare path -- the query string below is not part of it.
canonical = "\n".join([
    "GET", host, path, body_sha, mandate_id, merchant_id, nonce, timestamp, "",
])
signature = b64url(hmac.new(draw_key_secret.encode(), canonical.encode(), hashlib.sha256).digest())

resp = httpx.get(
    f"http://{host}{path}",
    params={"since": "2026-01-01T00:00:00Z", "limit": 50},
    headers={
        "Authorization": "Merchant your-merchant-api-key",
        "X-Merchant-Id": merchant_id,
        "X-Mandate-Id": mandate_id,
        "X-Nonce": nonce,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    },
)
print(resp.status_code, resp.json())

require "net/http"
require "json"
require "openssl"
require "base64"
require "securerandom"
require "time"

def b64url(bytes)
  Base64.strict_encode64(bytes).tr("+/", "-_").delete("=")
end

host = "localhost:3000"
path = "/v1/intent-mandates/b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091/draws"
mandate_id = "b2c3d4e5-6f70-4812-9a3b-4c5d6e7f8091"
merchant_id = "your-merchant-id"
draw_key_secret = "the-draw_key-from-mandate-creation"
nonce = SecureRandom.hex(16)
timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")

body_sha = b64url(OpenSSL::Digest::SHA256.digest(""))
# PATH here is the bare path -- the query string added to the URI below is not part of it.
canonical = ["GET", host, path, body_sha, mandate_id, merchant_id, nonce, timestamp, ""].join("\n")
signature = b64url(OpenSSL::HMAC.digest("SHA256", draw_key_secret, canonical))

uri = URI("http://#{host}#{path}")
uri.query = URI.encode_www_form(since: "2026-01-01T00:00:00Z", limit: 50)
req = Net::HTTP::Get.new(uri,
  "Authorization" => "Merchant your-merchant-api-key",
  "X-Merchant-Id" => merchant_id,
  "X-Mandate-Id" => mandate_id,
  "X-Nonce" => nonce,
  "X-Timestamp" => timestamp,
  "X-Signature" => signature)
res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
puts res.body

GET /v1/intent-mandates/:id/draws response fields

{
  "draws": [ { "payment_mandate_id": "...", "...": "..." } ],
  "next_since": "2026-01-01T00:03:12.482910Z",
  "has_more": true
}