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 mcp add --transport http merchantlink https://www.merchantlink.ai/api/mcp \
--header "Authorization: Bearer ml_sk_…"{
"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.
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"
}'{
"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"
}{
"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.
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 } }
}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.
# 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" }'# 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" }'# 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-Accountand 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/:idor a webhook, never from the return URL. - Lost the answer to a create call?
GET /api/v1/payment-sessions?reference=9921lists the sessions you created for that business with yourreference, newest first, with their payments. - Payment events for a payment made through one of your sessions carry
data.payment_session: itsid, yourreferenceandmetadata(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 carriesaccount. Only your endpoints also getpartner.account_connectedandpartner.account_disconnectedwhen 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/chargestakes 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 isapproved,partially_approved(collect the rest another way, under a newreference),declinedorunknown. Areferenceis charged at most once; while it isunknown, look it up withGET /api/v1/card-present/charges?reference=…and don’t run the card again. Refunds use the usualPOST /api/v1/payments/:id/refund; a tip added later usesPOST /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
Amount limits
Approval before contact
Audit trail
Idempotency
Event feed
OpenAPI 3.1
llms.txt
Reference
48 tools, one catalogue
Identical over MCP and REST. Money is always integer cents.
| Tool | Scope | What it does |
|---|---|---|
| create_payment_link | links:write | Create 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_url | links:read | Check 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_url | links:write | Give 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_links | links:read | List standalone payment links (fixed, donation, open) with amounts collected. |
| get_payment_link | links:read | Get a payment link by id. |
| set_payment_link_status | links:write | Deactivate a payment link so it can no longer be paid, or re-activate it. |
| create_invoice | invoices:write | Create 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_invoices | invoices:read | List invoices, optionally filtered by status (draft, open, partially_paid, paid, void, overdue) or customer_id. |
| get_invoice | invoices:read | Get an invoice with line items, balance due, pay_url and payments. |
| finalize_invoice | invoices:write | Finalize a draft invoice so it becomes payable. |
| void_invoice | invoices:write | Void an unpaid invoice. Its payment link stops accepting payments. |
| list_estimates | invoices:read | Estimates (quotes): priced offers the business sends before billing. Status is draft, sent (waiting for the customer), accepted, declined, canceled, expired, or invoiced. |
| get_estimate | invoices:read | Get an estimate with its lines, totals, status, the answer the customer gave and the invoice it became, if any. |
| create_estimate | invoices:write | Draft 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_subscriptions | invoices:read | Subscriptions: 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_products | invoices:read | The business's price list. Put a product on an invoice line with items[].product_id. |
| create_product | invoices:write | Add a product or service to the price list. |
| list_processor_deposits | payments:read | Deposits 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_reports | payments:read | Reports 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_disputes | payments:read | Disputes (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_coupons | invoices:read | The 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_rates | invoices:read | Tax rates the business has defined. Apply one to an invoice with tax_rate_id; tax is calculated on the taxable lines. |
| create_tax_rate | invoices:write | Define a tax rate (a percentage) the business can apply to invoices. MerchantLink does not decide which tax applies where. |
| send_payment_request | messages:send | Email 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_customer | customers:write | Create a customer. Phone numbers in E.164 (+15551234567). |
| update_customer | customers:write | Change 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_customers | customers:read | List or search customers by name, email, company or phone. |
| get_customer | customers:read | Get a customer by id. |
| list_payments | payments:read | List payments (most recent first), optionally by status or invoice. |
| get_payment | payments:read | Get a payment by id. |
| list_settlement_batches | payments:read | Settlement 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_batch | payments:read | One settlement batch with every sale, void and refund in it (amounts signed: voids and refunds negative). |
| refund_payment | refunds:write | Refund 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_session | payments:write | A 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_session | payments:read | A 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_sessions | payments:read | The 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_session | payments:write | Stop a session that hasn’t been paid from taking payments. |
| capture_payment | payments:write | Charge a card hold (status authorized), for what was held or less (amount_cents). |
| release_hold | payments:write | Let a card hold go without charging anything. |
| get_saved_card | customers:read | Whether a customer has a saved card that can be charged (last four digits only). |
| charge_saved_card | payments:charge | Charge 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_charge | payments:write | Charge 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_charge | payments:read | The 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_tip | payments:write | Add 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_summary | insights:read | Revenue collected in the last N days, outstanding and overdue balances, and the probability-weighted collections forecast for the coming weeks. |
| list_events | insights:read | Poll 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_approval | insights:read | Check whether the merchant approved an action this agent requested (status: proposed, executed, rejected, failed). |
| list_pending_approvals | insights:read | Actions 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.