# MerchantLink

> Invoicing, payment links, QR codes and payment collection (card, ACH, Apple Pay) across many processors. AI agents can bill customers and track payments on a merchant's behalf.

## Connect
- MCP server (Streamable HTTP): https://www.merchantlink.ai/api/mcp  (header: Authorization: Bearer ml_sk_...)
- REST API: https://www.merchantlink.ai/api/v1  (OpenAPI: https://www.merchantlink.ai/api/v1/openapi.json)
- The merchant creates an API key in MerchantLink > Settings > API & Agents and chooses its scopes, amount limit and whether sends need approval.

## Conventions
- Money is integer cents; currency defaults to usd.
- Invoices and links return a pay url and a qr_code_url.
- Actions that contact customers or move money can return {"status":"pending_approval","approval_id":...}; poll get_approval.
- Follow activity with list_events(after_seq).
- POST requests accept an Idempotency-Key header.

## Tools
- create_payment_link (scope: 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.
- list_payment_links (scope: links:read): List standalone payment links (fixed, donation, open) with amounts collected.
- get_payment_link (scope: links:read): Get a payment link by id.
- set_payment_link_status (scope: links:write): Deactivate a payment link so it can no longer be paid, or re-activate it.
- create_invoice (scope: 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 (scope: invoices:read): List invoices, optionally filtered by status (draft, open, partially_paid, paid, void, overdue) or customer_id.
- get_invoice (scope: invoices:read): Get an invoice with line items, balance due, pay_url and payments.
- finalize_invoice (scope: invoices:write): Finalize a draft invoice so it becomes payable.
- void_invoice (scope: invoices:write): Void an unpaid invoice. Its payment link stops accepting payments.
- send_payment_request (scope: messages:send): Email and/or text the pay link for an invoice or payment link to the customer. SMS requires the customer's consent (set sms_consent_confirmed only if they agreed). If the API key requires approval, the send is queued for the merchant to approve.
- create_customer (scope: customers:write): Create a customer. Phone numbers in E.164 (+15551234567).
- list_customers (scope: customers:read): List or search customers by name, email, company or phone.
- get_customer (scope: customers:read): Get a customer by id.
- list_payments (scope: payments:read): List payments (most recent first), optionally by status or invoice.
- get_payment (scope: payments:read): Get a payment by id.
- refund_payment (scope: refunds:write): Request a full or partial refund (amount_cents). Refunds requested by agents always require merchant approval.
- get_account_summary (scope: 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 (scope: 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 (scope: insights:read): Check whether the merchant approved an action this agent requested (status: proposed, executed, rejected, failed).
- list_pending_approvals (scope: insights:read): Actions waiting for the merchant to approve (AI-drafted reminders, agent requests...).