Developer Documentation

Backed by GET /v1/receipts/{txnId}, which returns the transaction (line items + modifiers + tip / tax / discount / tendered / change), refund/void state, and merchant branding (logo, brand color, business address, footer).

Renders a printable receipt themed by the merchant's brand color. Loud red banner + struck-through total + "Net charged" line for refunds; grey banner with line-through total for voids.

Both endpoints route through the merchant's resolved provider creds and respect the same gates as receipts and invoices:

• ISV-scope (global vs merchant) determines whose creds get used.
• Per-merchant integration_*_enabled flags gate whether the send fires at all — 400 if off.
• SMS picks Sinch first when both Twilio and Sinch are configured. filterSmsCreds zeroes out a disabled provider so a Twilio-only merchant can't fall through to Sinch.

• Phone-number lifecycle — search Twilio/Sinch inventory, buy numbers, configure inbound webhooks, release back to the provider.
• A2P 10DLC — register a brand (merchant EIN, encrypted) and a campaign per use-case, then attach numbers. Required to send SMS to US long-codes without carrier filtering.
• Toll-free verification — alternative path for merchants who can't go 10DLC.
• Outbound voice — same numbers, voice calls.
• SMS approval gate — POST /v1/messages/sms refuses to send from a long-code unless its campaign is approved, or from a toll-free unless the verification is approved.

1. Buy a number. POST /v1/messaging/numbers/search with { areaCode, numberType: "local" } → pick one → POST /v1/messaging/numbers/buy. Status flips to active.
2. Register a brand. POST /v1/messaging/brands with the merchant's legal name, EIN, address, contact. State machine: draft → submitted → in_review → approved/failed/suspended. EIN gets encrypted at rest via the crypto-vault. Poll POST /v1/messaging/brands/{id}/refresh-status until approved.
3. Register a campaign. POST /v1/messaging/campaigns with use-case, sample messages, the brand id. Same state machine. Poll until approved.
4. Attach the number. POST /v1/messaging/campaigns/{id}/numbers with { numberIds: ["brz_msgnum_..."] }. Each number can only be on one campaign at a time; switching is recorded in messaging_number_campaign_history.
5. Send. POST /v1/messages/sms with { to, body, from: "brz_msgnum_..." }. The approval gate checks the number's attached campaign status. If approved → sent. If not → 409 messaging_not_approved.

Toll-free path is the same shape but uses POST /v1/messaging/tollfree-verifications instead of brand+campaign. The number itself stays attached to the verification record (messagingNumber.tollfreeVerificationId) once submitted.

When merchants.test_mode = true, every messaging-provisioning call routes through a mock provider that:

• Auto-approves brands and campaigns in ~5 seconds — the dashboard's status badge flips green on its own.
• Auto-approves toll-free verifications in ~10 seconds.
• Mints fake `brz_msgnum_…` numbers on buy, no real provider calls.
• Logs SMS sends to the dashboard transaction list instead of hitting Twilio/Sinch.

Use this for dashboard development, integration tests, demos. End-to-end flows work without setting up a Twilio or Sinch account.

merchant_settings.enforce_messaging_approval defaults to true. Set it to false via PATCH /v1/settings (admin-only — merchants can't disable this themselves) and the SMS gate is bypassed.

When you'd actually want this: one-off integration testing against a real upstream when an approval is mid-review. Don't leave it off in production. Carriers (T-Mobile, AT&T, Verizon) will silently filter unregistered SMS, and the merchant won't know until customers complain that they never got the receipt.

Before dispatch, the gateway sums the merchant's month-to-date usage against messaging_monthly_cap_messages (default 500) and messaging_monthly_cap_dollars (default $25). If either is hit:

HTTP/1.1 402 Payment Required
{
  "error": "quota_exceeded",
  "reason": "messages",          // or "dollars"
  "messages_used": 500,
  "messages_cap": 500,
  "dollars_used_cents": 1875,
  "dollars_cap_cents": 2500,
  "next_reset_at": "2026-05-01T00:00:00.000Z"
}

International destinations (anything not +1 or 10–11-digit US format) reject earlier with HTTP 402 not_supported_in_plan.

Metering happens after a successful dispatch — failed sends don't burn quota.

• messaging.cap_warning webhook + email at 80% of either cap
• messaging.cap_reached webhook + email at 100% — coincides with the first 402 quota_exceeded

Each carries { reason, messages_used, messages_cap, dollars_used_cents, dollars_cap_cents, period }. Email goes to messaging_alert_email (configurable on settings) or falls back to the merchant's primary contact. messaging_alert_state has a UNIQUE (merchant_id, billing_period, threshold) constraint so each threshold fires exactly once.

Wired into the existing tiyo-run-recurring-billings pg_cron. On day-of-month=1 at the merchant's preferred_billing_hour, the gateway sums the prior month's usage (tier base + SMS overage + MMS) and appends a line item to the merchant's draft invoice. Lookup is by notes LIKE '[messaging-billing:YYYY-MM]%' — the prefix is the dedupe key, since the invoices table has no separate reference column.

The platform tier is the floor. Each ISV layers their own pricing program on top: one-time provisioning fees, monthly recurring fees per number / per campaign, and optional per-message rate overrides. Configured at /isv/messaging-billing.

card = list
ach  = list × (1 − ach_discount_percent / 10000)
cash = list × (1 − cash_discount_percent / 10000)

card = list × (1 + card_markup_percent / 10000)
ach  = list
cash = list

All three knobs (card_markup_percent, ach_discount_percent, cash_discount_percent) are basis points — 100 = 1.00%. Stored on merchant_settings; settable via Settings → Pricing or PATCH /v1/settings; readable without auth via GET /api/pay/config?merchantId=… so a website widget can render the math client-side.

Public, no auth. Accepts a merchantId-only payload — Stripe-style "publishable identity," so a website widget never needs the merchant's secret key. CORS is wide-open on /api/pay/*.

POST https://tiyopay.vercel.app/api/pay/sessions
Content-Type: application/json

{
  "merchantId": "brz_mer_...",
  "amount":     2447,                         // cents — chosen-method total
  "reference":  "site-order-…",
  "line_items": [{ "name":"Box", "qty":1, "unit_price":599 }],
  "payment_methods": ["card","ach"],
  "pricing":    { "list":2497, "card":2497, "ach":2447, "achDiscount":50 },
  "metadata":   { "source":"woocommerce", "wc_order_id":"42" },
  "return_url": "https://merchant.com/order/thanks"
}

→  201
{
  "id":    "brz_chk_…",
  "url":   "https://tiyopay.vercel.app/pay/<merchantId>?session=brz_chk_…",
  "amount": 2447,
  ...
}

Whitelists forwarded fields, so the public surface can't smuggle dashboard-only knobs (save_card without a customer, skip_customer_info, etc).

POST <your webhook URL>
Tiyo-Signature: t=…,v1=…

{
  "type": "payment.completed",
  "data": {
    "id":         "brz_txn_…",
    "status":     "approved",
    "amount":     2447,
    "type":       "ach",
    "reference":  "site-order-…",
    "session_id": "brz_chk_…",
    "metadata":   { "source":"woocommerce", "wc_order_id":"42" }
  }
}

The metadata the website widget passed to /api/pay/sessions is round-tripped through the session, stamped onto the resulting transaction at sale time, and surfaced on payment.completed / .declined / .failed / .refunded events. Match on metadata.your_order_id and you don't need a follow-up GET.

• Cash-discount program is the legally distinct framing: list price IS the card price, ACH/cash get a discount off list. Use this everywhere — Visa/MC have no restrictions on it and no states prohibit it.
• Surcharge programs are illegal in CT, MA, ME, NY (varies) and tightly regulated in CA, FL, NJ, OK. Visa caps surcharges at 3% of the transaction. Don't toggle enable_cash_discount off for merchants in those states.
• Disclosure at point-of-entry, the receipt, and the cart is required. The hosted page renders a "Pay by eCheck and save X%" banner automatically when ach_discount_percent > 0.

• See and add saved cards.
• Cancel or pause subscriptions.
• Review past invoices and pay open ones.
• Update contact info.

Sessions expire in 1 hour by default (capped at 24h). After expiry the URL 401s — customer reaches the login page again.

customers.email is unique per (merchant_id, lower(email)). The same email is allowed across different merchants — that's how a person who rents at two storage facilities gets two separate sign-in links from the magic-link flow. Only collisions inside one merchant violate.

POST / PATCH /v1/customers normalize the email server-side (trim + lowercase) and return 409 email_in_use on collision instead of a generic 500.

• scope='global' — the ISV's creds are used for every merchant they onboard. Merchants don't see the integration on their settings page.
• scope='merchant' — each merchant brings their own creds via /v1/settings. The ISV row is ignored for that channel.

ISV manages credentials and scope at PATCH /v1/isv/settings; sensitive fields are redacted to last-4 on read, and a write whose value still starts with the redaction mask is treated as unchanged.

Stored on merchant_settings as:

• integration_email_enabled
• integration_twilio_enabled + integration_sinch_enabled (independent — Twilio and Sinch are separate providers)
• integration_quickbooks_enabled
• integration_sms_enabled — legacy combined flag, kept for back-compat

When a flag is off the corresponding send short-circuits with a 400, regardless of whether creds are configured. A merchant allowed on Twilio but not Sinch won't accidentally fall through to Sinch — the resolver zeroes out disabled-provider creds before they reach sendSms().

Resend hits /domains; Twilio hits /Accounts/<sid>.json; Sinch SMS hits /groups; Sinch Numbers/10DLC hits /projects/{id}/activeNumbers; QuickBooks does a refresh-token exchange. Response is one of:

• null — not configured
• { ok: true } — Connected (badge green)
• { ok: false, error } — Auth failed (badge red, error in tooltip)

The dashboard's Integration page badges read directly from this — they no longer go green just because a field has a value.

Sinch reports two statuses. sinch is the SMS-batches API check (needs sinch_api_token + sinch_service_plan_id). sinch_provisioning is the Numbers/10DLC API check, which additionally needs sinch_project_id. The /v1/messaging/* provisioning endpoints gate on sinch_provisioning: a merchant can have sinch.ok = true (SMS sends work) while sinch_provisioning.ok = false (10DLC / number purchase / brand registration won't). Branch UI off the right field for the surface you're rendering.