Developers & AI agents

Payments your AI assistant can run

MerchantLink is a native MCP server with a matching REST API. Let Claude or your own agents create invoices, send payment links and follow the money, with limits and approvals you control.

MCP server

Connect an assistant in one line

MerchantLink speaks the Model Context Protocol over Streamable HTTP. Any MCP client can discover its tools, and each key only sees the tools its scopes allow.

Claude Code
claude mcp add --transport http merchantlink https://www.merchantlink.ai/api/mcp \
  --header "Authorization: Bearer ml_sk_…"
Any MCP client (JSON config)
{
  "mcpServers": {
    "merchantlink": {
      "type": "http",
      "url": "https://www.merchantlink.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ml_sk_…"
      }
    }
  }
}

REST API

The same operations over plain HTTP

Integer cents, predictable JSON, Stripe-style idempotency keys, and pay links and QR codes in every response.

Create an invoice
curl https://www.merchantlink.ai/api/v1/invoices \
  -H "Authorization: Bearer ml_sk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c9a" \
  -d '{
    "customer": { "name": "Jane Smith", "email": "jane@example.com" },
    "items": [{ "description": "Logo design", "unit_amount_cents": 45000 }],
    "due_date": "2026-10-07"
  }'
200 OK
{
  "id": "inv_…",
  "object": "invoice",
  "number": "INV-1012",
  "status": "open",
  "total_cents": 45000,
  "amount_due_cents": 45000,
  "pay_url": "https://www.merchantlink.ai/pay/v7nkneh7ts",
  "qr_code_url": "https://www.merchantlink.ai/api/qr/v7nkneh7ts"
}
202 Accepted: over a limit or needs approval
{
  "status": "pending_approval",
  "approval_id": "ai_…",
  "message": "This API key requires approval before contacting customers…"
}

Webhooks

Hear about it when it happens

Add an endpoint in Settings and MerchantLink POSTs it within about a minute of a payment, a paid invoice, a refund, a dispute, an accepted estimate and more. Signed, retried for a day and a half, and safe to receive twice.

What your server receives
POST https://example.com/webhooks/merchantlink
MerchantLink-Signature: t=1791676800,v1=5f2b...
MerchantLink-Event-Id: evt_8sK2pQ...

{
  "id": "evt_8sK2pQ...",
  "object": "event",
  "type": "payment.succeeded",
  "account": "mer_…",
  "created_at": "2026-10-11T15:04:05.000Z",
  "data": { "object": { "id": "pay_...", "object": "payment", "status": "succeeded", "amount_cents": 128500 } }
}
Check the signature (Node.js)
import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: the request body exactly as received (not re-serialized JSON)
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false // too old: a replay
  const expected = createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex')
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}

Platforms (ISVs)

Use MerchantLink as the gateway for the businesses on your platform

Your software takes payments for each business through that business’s own processor: Magensa, TSYS TransIT, Stripe and the rest. Card details go from the payer straight to the processor’s fields, so neither you nor MerchantLink handle card numbers.

Connect a business
# 1. Ask a business that already uses MerchantLink to connect to your platform
curl -X POST https://www.merchantlink.ai/api/partner/v1/connect-requests \
  -H "Authorization: Bearer ml_pk_…" -H "Content-Type: application/json" \
  -d '{ "external_id": "shop_123", "return_url": "https://yourapp.com/merchantlink/connected", "state": "c81e" }'
# → { "id": "pcr_…", "url": "https://www.merchantlink.ai/partners/connect/…" }   send the owner to url;
#   they come back to return_url with ?account=mer_…&status=approved&state=c81e

# Or sign up a business that isn't on MerchantLink yet (its owner is invited by email)
curl -X POST https://www.merchantlink.ai/api/partner/v1/accounts -H "Authorization: Bearer ml_pk_…" \
  -d '{ "business_name": "Main Street Bakery", "owner_email": "owner@example.com", "external_id": "shop_124" }'
Take payments for it
# 2. Take a payment for that business, on its own processor
curl -X POST https://www.merchantlink.ai/api/v1/payment-sessions \
  -H "Authorization: Bearer ml_pk_…" \
  -H "MerchantLink-Account: mer_…" \
  -H "Idempotency-Key: order-9921" -H "Content-Type: application/json" \
  -d '{ "amount_cents": 12500, "description": "Order #9921",
        "customer": { "name": "Jane Smith", "email": "jane@example.com" },
        "return_url": "https://yourapp.com/orders/9921", "reference": "9921" }'
# → { "id": "lnk_…", "object": "payment_session", "status": "open", "url": "https://www.merchantlink.ai/pay/…" }

# 3. Later, charge the card she saved, without her present
curl -X POST https://www.merchantlink.ai/api/v1/charges \
  -H "Authorization: Bearer ml_pk_…" -H "MerchantLink-Account: mer_…" \
  -H "Idempotency-Key: renewal-2026-11" \
  -d '{ "customer_id": "cus_…", "amount_cents": 12500, "description": "November renewal" }'
Card present: your own card reader, the business’s Magensa account
# At the counter: your POS's MagTek reader encrypts the card; send its output as is
curl -X POST https://www.merchantlink.ai/api/v1/card-present/charges \
  -H "Authorization: Bearer ml_pk_…" -H "MerchantLink-Account: mer_…" \
  -H "Idempotency-Key: sale-5521-card-1" -H "Content-Type: application/json" \
  -d '{ "amount_cents": 1850, "tip_cents": 300, "reference": "sale-5521-card-1",
        "card_read": { "entry_mode": "emv", "emv_data": "DFDF54…", "device_serial": "B4F3D21" } }'
# → { "object": "card_present_charge", "status": "approved", "approved_cents": 2150,
#     "card": { "entry_mode": "emv", "last4": "0119", "brand": "VISA" }, "auth_code": "A1B2C3", "payment_id": "pay_…" }

# No answer? Never run the card again: look the reference up until it isn't "unknown"
curl "https://www.merchantlink.ai/api/v1/card-present/charges?reference=sale-5521-card-1" -H "Authorization: Bearer ml_pk_…" -H "MerchantLink-Account: mer_…"

# A tip written on the receipt afterwards
curl -X POST https://www.merchantlink.ai/api/v1/payments/pay_…/tip-adjust -H "Authorization: Bearer ml_pk_…" -H "MerchantLink-Account: mer_…" \
  -d '{ "tip_cents": 400 }'
  • Partner keys (ml_pk_…) are issued by MerchantLink after a short review. Write to us to become a partner.
  • Every call for a business names it with MerchantLink-Account and can do only what the business allowed when it connected you. It can disconnect you at any time.
  • Payment sessions are hosted pay pages (card, bank transfer, Apple Pay and Google Pay where the processor offers them). Confirm the outcome with GET /api/v1/payment-sessions/:id or a webhook, never from the return URL.
  • Lost the answer to a create call? GET /api/v1/payment-sessions?reference=9921 lists the sessions you created for that business with your reference, newest first, with their payments.
  • Payment events for a payment made through one of your sessions carry data.payment_session: its id, your reference and metadata (null otherwise).
  • The whole business API works the same way: invoices, payment links, customers, refunds (made at once for partners), card holds, reports and settlements.
  • One webhook endpoint (POST /api/partner/v1/webhook-endpoints) receives the events of every connected business; each event carries account. Only your endpoints also get partner.account_connected and partner.account_disconnected when a business connects (or approves new scopes) and when either side disconnects.
  • Charges require an Idempotency-Key. A 502 means the processor didn’t confirm: check the payment instead of retrying.
  • Card present (beta, Magensa): POST /api/v1/card-present/charges takes your MagTek reader’s encrypted swipe or EMV output (never a card number) and charges it on the business’s own live Magensa account. The answer is approved, partially_approved (collect the rest another way, under a new reference), declined or unknown. A reference is charged at most once; while it is unknown, look it up with GET /api/v1/card-present/charges?reference=… and don’t run the card again. Refunds use the usual POST /api/v1/payments/:id/refund; a tip added later uses POST /api/v1/payments/:id/tip-adjust.

Guardrails for autonomous agents

Give agents real power, safely

Every API key is a policy. Decide what an agent may do, how much it may bill, and when it must ask you first.

Scoped keys

Ten scopes, from links:read to refunds:write. Read-only and full-access presets included.

Amount limits

Invoices or links above a key’s ceiling become approval requests instead of executing.

Approval before contact

Optionally require your OK before an agent emails or texts a customer. Agent refunds always need approval.

Audit trail

Every agent action is recorded with the key that made it, alongside human and AI actions.

Idempotency

Retry any POST safely with an Idempotency-Key; the original response is replayed.

Event feed

Poll list_events with a cursor to react to payments, views and customer replies.

OpenAPI 3.1

Generated from the same schemas that validate every request, so it never drifts.

llms.txt

A plain-text guide at /llms.txt teaches any model how to use MerchantLink.

Reference

48 tools, one catalogue

Identical over MCP and REST. Money is always integer cents.

ToolWhat it does
create_payment_linkCreate a shareable payment link with a QR code. type "fixed" = one-time payment of amount_cents; "donation" = payer picks from suggested_amounts or enters any amount; "open" = payer enters any amount. Returns the pay url and qr_code_url.
check_payment_link_urlCheck whether a custom ending for a pay URL (the "slug" of create_payment_link) is available. Returns the normalized slug, available, and a reason when it is not.
change_payment_link_urlGive an existing payment link a new address (slug). The old address keeps working and redirects to the new one. Not for invoice links. Check availability first with check_payment_link_url.
list_payment_linksList standalone payment links (fixed, donation, open) with amounts collected.
get_payment_linkGet a payment link by id.
set_payment_link_statusDeactivate a payment link so it can no longer be paid, or re-activate it.
create_invoiceCreate an itemized invoice. Pass customer_id, or customer {name, email, phone} to match/create one. Amounts are integer cents. Every invoice gets a pay_url and qr_code_url. Use send_payment_request afterwards to email/text it.
list_invoicesList invoices, optionally filtered by status (draft, open, partially_paid, paid, void, overdue) or customer_id.
get_invoiceGet an invoice with line items, balance due, pay_url and payments.
finalize_invoiceFinalize a draft invoice so it becomes payable.
void_invoiceVoid an unpaid invoice. Its payment link stops accepting payments.
list_estimatesEstimates (quotes): priced offers the business sends before billing. Status is draft, sent (waiting for the customer), accepted, declined, canceled, expired, or invoiced.
get_estimateGet an estimate with its lines, totals, status, the answer the customer gave and the invoice it became, if any.
create_estimateDraft an estimate (quote) for a customer: same lines, products and tax as an invoice, plus an optional valid-until date. It is saved as a draft and nothing is sent or billed: the business reviews it in MerchantLink, sends it, and turns it into an invoice once the customer accepts.
list_subscriptionsSubscriptions: invoices the business bills a customer on a schedule (weekly, monthly, every 3 months, yearly). Shows the amount per invoice, the next invoice date, and whether the card on file is charged automatically. Subscriptions are set up by the business in MerchantLink.
list_productsThe business's price list. Put a product on an invoice line with items[].product_id.
create_productAdd a product or service to the price list.
list_processor_depositsDeposits as the processor reported them: for each, the sales, refunds, the processor's fees, chargebacks and other adjustments, and the net amount that reached the bank. These are the processor's own figures (read from the processor or from a report the business uploaded), unlike list_settlement_batches, which is MerchantLink's estimate. Empty when the business has not connected or uploaded any.
get_reportsReports for a period (dates on the calendar the business keeps, default this month): money received over time, by customer and by payment method (payments that went through, with what has since been refunded on them); what was billed by product and the tax on it (invoices issued, not drafts or void); and aged receivables as of today. Processor fees and chargebacks are not included.
list_disputesDisputes (chargebacks) on the business's payments: amount, reason, the date to respond by, and status (needs_response, under_review, won, lost, accepted). Responses are written and sent by the business in MerchantLink.
list_couponsThe business's coupon codes: a percentage or an amount off. Put one on an invoice with coupon_code. Payers can type one on fixed-price payment links created with allow_coupons.
list_tax_ratesTax rates the business has defined. Apply one to an invoice with tax_rate_id; tax is calculated on the taxable lines.
create_tax_rateDefine a tax rate (a percentage) the business can apply to invoices. MerchantLink does not decide which tax applies where.
send_payment_requestEmail and/or text the pay link for an invoice or payment link to the customer. Texts only go to customers who opted in themselves on the payment page or the merchant's text sign-up page; otherwise use email. If the API key requires approval, the send is queued for the merchant to approve.
create_customerCreate a customer. Phone numbers in E.164 (+15551234567).
update_customerChange a customer's name, email, phone, company or notes. Send only the fields to change; null clears email, phone, company or notes. Changing the phone number ends that customer's text opt-in: they opt in again themselves.
list_customersList or search customers by name, email, company or phone.
get_customerGet a customer by id.
list_paymentsList payments (most recent first), optionally by status or invoice.
get_paymentGet a payment by id.
list_settlement_batchesSettlement report: what each processor account should deposit, per daily batch. Each batch has sales, voids, refunds, net_cents (sales minus voids and refunds, before the processor's own fees and chargebacks), status (open, closed = awaiting deposit, deposited) and any deposit the business recorded with its variance. Computed from MerchantLink's records, not a processor settlement file. Dates are batch dates (YYYY-MM-DD) in the business's time zone; defaults to the last 14 days, 92 days at most.
get_settlement_batchOne settlement batch with every sale, void and refund in it (amounts signed: voids and refunds negative).
refund_paymentRefund a payment in full or in part (amount_cents). Refunds requested by AI agents and API keys wait for the merchant’s approval; a platform partner the business granted refunds:write refunds at once.
create_payment_sessionA one-time hosted pay page for an amount, paid on the business’s own processor. Send the payer to url; afterwards they can return to return_url (with session_id and payment_id added). Confirm the result with get_payment_session or the payment.succeeded webhook, never from the return URL alone. Tie it to a customer and the payer may save their card for later charges.
get_payment_sessionA payment session and its outcome: status is open, processing, authorized (a hold), paid, expired or canceled; payment is the payment when there is one.
list_payment_sessionsThe payment sessions created with your reference, newest first, each with its status and payment. Use it to recover a session (and whether it was paid) when the answer to create_payment_session was lost. Only this business’s sessions are searched; a platform partner sees only the sessions it created.
cancel_payment_sessionStop a session that hasn’t been paid from taking payments.
capture_paymentCharge a card hold (status authorized), for what was held or less (amount_cents).
release_holdLet a card hold go without charging anything.
get_saved_cardWhether a customer has a saved card that can be charged (last four digits only).
charge_saved_cardCharge a customer’s saved card with the customer not present: amount_cents and a description (an invoice is made for it, and voided if the card is declined), or invoice_id to charge an open invoice. status is succeeded, failed or processing. Send an Idempotency-Key. A 502 means the processor didn’t confirm: check the payment before trying again.
create_card_present_chargeCharge the encrypted output of a MagTek card reader (swipe or EMV, DUKPT ciphertext; never a card number) on the business’s own live Magensa account. status is approved, partially_approved (approved_cents is what the card covered: collect the rest another way, under a new reference), declined (failure_code says why; nothing was charged) or unknown (the charge may have gone through: never run the card again, look the reference up until it resolves). A reference is charged at most once: sending it again returns the earlier answer. Send an Idempotency-Key.
get_card_present_chargeThe latest card-present charge made with your reference, in the same shape create_card_present_charge answers. An unknown outcome is first checked with Magensa (recall), so call this to resolve one. attempts counts every attempt for the reference (a declined one may be followed by another).
adjust_tipAdd a tip after the card was charged (Magensa TIPADJUST), once per payment, on a card-present payment approved in full with no tip at the reader and nothing refunded. status is approved (amount_cents now includes the tip), declined or unknown (don’t send a different tip; send the same tip again to check on it). Sending the same tip again after approval returns the same answer.
get_account_summaryRevenue collected in the last N days, outstanding and overdue balances, and the probability-weighted collections forecast for the coming weeks.
list_eventsPoll the account event log (payment.succeeded, invoice.paid, invoice.viewed, message.received, ...). Pass after_seq from the previous call to get only new events.
get_approvalCheck whether the merchant approved an action this agent requested (status: proposed, executed, rejected, failed).
list_pending_approvalsActions waiting for the merchant to approve (AI-drafted reminders, agent requests...).

Full schemas in the OpenAPI spec and llms.txt.

Send your first payment link today

Every account starts with a built-in sandbox, so you can create invoices, send links and take test payments before you connect a processor.