target=invoice_logo_url
```
```json
{
"url": "https://crwbtzryadlpmlupgcmz.supabase.co/storage/v1/object/public/brand-logos/merchant-4/logo-….png",
"path": "merchant-4/logo-….png",
"appliedTo": ["invoice_logo_url"],
"contentType": "image/png",
"size": 18432
}
```
`target` accepts: `logo_url` (hosted-pay page + portal), `invoice_logo_url` (invoices + receipts), `both`, or `none` (just upload, don't apply). Allowed types: PNG, JPEG, GIF, WebP, SVG. Max 5 MiB. Returns the public URL — store it on your side too if you need it.
**(c) Point at a URL you already host.** Plain `PATCH /v1/settings`:
```http
PATCH /v1/settings
{ "logo_url": "https://your-cdn/logo.png", "invoice_logo_url": "https://your-cdn/invoice-logo.png" }
```
Tiyo renders from your URL at request time. Outage on your end ⇒ logo doesn't render. Use (b) for resilience.
### 4.4 Save a card without charging (Setup Intent)
```http
POST /v1/setup-intents
{ "customer_id": "brz_cus_...", "return_url": "..." }
```
Returns a hosted URL. Customer tokenizes their card; no charge lands on
their statement. Saved card appears under
`GET /v1/customers/{id}/cards` on completion.
### 4.5 Send an invoice
```http
POST /v1/invoices
{
"customer_id": "brz_cus_...",
"due_date": "2026-05-15",
"auto_pay": true, // cron charges the default card on due_date
"allow_partial": false,
"items": [
{ "name": "Consulting — April", "quantity": 1, "unit_price": 10000 },
{ "name": "Expedited delivery", "quantity": 2, "unit_price": 1000 }
]
}
```
Then:
```http
POST /v1/invoices/{id}/send
{ "channels": { "email": true, "sms": false } }
```
We render a branded email (with a Pay button linking to the hosted form),
fire `invoice.sent`, and mark the invoice `sent`. When it settles (via the
hosted page OR auto-pay cron OR manual `POST /v1/invoices/{id}/pay`) we
fire **both** `payment.completed` (with `data.metadata.invoiceId` set so
you can correlate the charge back to the invoice) **and** `invoice.paid`
(with `data.transaction_id` set so you can correlate the invoice back to
the charge). Same envelope shape regardless of which path settled the
invoice — your consumer doesn't need to distinguish manual-pay vs
auto-pay vs hosted-pay.
### 4.6 Subscribe a customer to a plan
Create the plan once:
```http
POST /v1/membership-plans
{
"name": "Monthly Parking",
"price": 29500,
"billing_cycle": "monthly" // weekly|biweekly|monthly|quarterly|annual
}
```
Then attach a customer:
```http
POST /v1/customer-subscriptions
Idempotency-Key: sell-plan-jane-2026-04-23
{
"customer_id": "brz_cus_...",
"plan_id": "brz_plan_...",
"card_id": 42, // OR payment_token for a new card
"charge_now": true, // default: charge the first cycle immediately
"items": [ // OPTIONAL one-time add-ons on the first charge
{ "name": "Enrollment fee", "quantity": 1, "unit_price": 2500 }
]
}
```
Our cron handles every subsequent cycle. Failures retry in the same window
(1 h, 4 h, 1 d, 3 d); after 3 consecutive failures the subscription moves
to `past_due` and fires `subscription.payment_failed`.
### 4.7 DIY recurring (you own the cron)
If your ERP already drives the schedule, skip subscriptions and call
`POST /v1/payments` with `cardId` each cycle. No subscription row is
created — every charge stands alone.
### 4.8 Customer portal (self-serve)
Mint a signed URL; hand it to your customer:
```http
POST /v1/customers/{id}/portal-sessions
{ "return_url": "https://yoursite.com/account", "expires_in": 3600 }
```
Returns `{ id, url, token, expires_at }`. They land on a page where they
can cancel subscriptions, add / replace cards, view invoices.
### 4.9 Send an arbitrary email or SMS
For free-form messages (rent reminders, appointment confirmations, ad-hoc
customer notes) — anything that isn't a Tiyo receipt, invoice, or portal
link — call the messaging endpoints directly. They route through the
merchant's resolved Resend / Twilio / Sinch creds, honor the ISV-scope
flags, and gate on each merchant's `integration_*_enabled` toggle.
```http
POST /v1/messages/email
Authorization: Bearer brz_secret_...
{
"to": "tenant@example.com",
"subject": "Storage rent due in 3 days",
"html": "Hi Jane, your unit B-12 rent of $129 is due Friday.
",
"text": "Hi Jane, your unit B-12 rent of $129 is due Friday.",
"reply_to": "billing@yourstoragefacility.com"
}
```
```http
POST /v1/messages/sms
Authorization: Bearer brz_secret_...
{
"to": "+15551234567",
"body": "Hi Jane, your B-12 rent of $129 is due Friday. Reply STOP to opt out."
}
```
Both return `{ success, channel, provider, id }` on success; the `id` is
the upstream provider's message id (Resend/Twilio/Sinch) for cross-system
lookup. 400 if the integration is disabled for this merchant; 500 if the
upstream provider rejects the send.
For transactional sends — receipts and invoices — use the resource-bound
endpoints instead (`POST /v1/payments/{id}/receipt`,
`POST /v1/invoices/{id}/send`). They render the right HTML and include
the hosted-receipt or pay link automatically.
### 4.10 Messaging Provisioning (phone numbers, A2P 10DLC, toll-free, voice)
The endpoints in `/v1/messages/*` (above) get the SMS / email out the
door once the channel is set up. Setting up the channel — buying a
number, registering an A2P 10DLC brand and campaign, or submitting a
toll-free verification — is what `/v1/messaging/*` is for. Every
resource is per-merchant; the ISV's Twilio / Sinch credentials act as
the Communications Service Provider behind the scenes.
#### Zero-to-sending walkthrough (handoff for dashboard agents)
If you're building the dashboard UI for setting up SMS on a merchant
account, this is the canonical sequence. Every step is a single API
call against the gateway; the ISV's Twilio / Sinch credentials are
already on `isv_settings` (no per-merchant cred entry needed).
**1. Confirm the ISV has live messaging credentials.**
```http
GET /v1/integrations/status
```
Returns a per-provider live auth check. The response includes BOTH
`sinch` (SMS-batches API — needs `sinch_api_token` +
`sinch_service_plan_id`) and `sinch_provisioning` (Numbers/10DLC API
— additionally needs `sinch_project_id`). For this walkthrough you
need `twilio.ok = true` OR `sinch_provisioning.ok = true` — those
are what `/v1/messaging/*` actually gates on. If only `sinch.ok` is
true and `sinch_provisioning` is false, the ISV is missing
`sinch_project_id`; send them to `/isv/integrations` to set it
before continuing.
**2. Buy a number.** Search inventory, pick one, purchase.
```http
POST /v1/messaging/numbers/search { "areaCode": "415", "numberType": "local", "capabilities": ["sms"] }
POST /v1/messaging/numbers/buy { "e164": "+14155551234", "capabilities": ["sms"], "smsInboundWebhookUrl": "..." }
```
Resulting `messaging_numbers` row has `status: "active"`.
**3. Pick a path: 10DLC long-code OR toll-free.**
- 10DLC (default for local numbers): go to step 4a.
- Toll-free (skip campaigns, use TFV): go to step 4b.
**4a. 10DLC: register a brand → register a campaign → attach the
number.**
```http
POST /v1/messaging/brands { merchant identity, EIN, address, contact }
POST /v1/messaging/brands/{id}/refresh-status # poll until status='approved' (1–8 weeks live, ~5s in test_mode)
POST /v1/messaging/campaigns { brandId, useCase, messageSamples, optOutKeywords, ... }
POST /v1/messaging/campaigns/{id}/refresh-status # poll until status='approved'
POST /v1/messaging/campaigns/{id}/numbers { "messagingNumberIds": ["brz_msgnum_..."] }
```
Failure modes: `409 brand_not_approved` (campaign created before brand
approved), `failed` status with `failureReasons` array on the row
(brand or campaign), partial-success body on bulk number attach.
**4b. Toll-free: submit a verification, attach the number.**
```http
POST /v1/messaging/tollfree-verifications { messagingNumberId, businessName, useCaseSummary, optInImageUrls, ... }
POST /v1/messaging/tollfree-verifications/{id}/refresh-status # until 'approved'
```
The verification row carries the linked `messagingNumberId` so the SMS
gate finds it without an explicit attach call.
**5. (One-time, optional but recommended) Get the merchant on a
messaging plan.** If the ISV is in `subscription_tiers` mode, the
merchant must pick a tier before SMS can bill. Surface a tier picker;
on submit:
```http
PATCH /v1/messaging/settings { "messaging_tier_id": }
```
In `volume_bands` mode (default), no merchant action needed — the
band picks itself based on monthly volume.
**6. Send.**
```http
POST /v1/messages/sms { "to": "+14155551234", "body": "Hi Jane..." }
```
The gate will pick the merchant's first approved sender. Pass `from`
explicitly if you want to pin one. Errors you'll handle:
- `409 messaging_not_approved` — campaign not approved yet
- `409 tollfree_not_verified` — TFV not approved yet
- `402 quota_exceeded` — monthly cap hit (raise via PATCH /v1/messaging/settings)
- `402 not_supported_in_plan` — international destination (US only)
- `403 mms_disabled` — request had `mediaUrls` and ISV has MMS off
**Webhooks to listen for.** Drive UI status updates off these instead
of polling refresh-status more aggressively than 1/min:
- `messaging.brand.{submitted,approved,failed}`
- `messaging.campaign.{submitted,approved,failed,numbers_attached,number_detached}`
- `messaging.tfv.{submitted,approved,rejected}`
- `messaging.number.{purchased,released}`
- `messaging.cap_warning` / `messaging.cap_reached`
**Test mode.** Set `merchants.test_mode = true` and every provisioning
call routes through a mock provider that auto-approves brands +
campaigns in ~5s and TFVs in ~10s. Lets you exercise the entire
end-to-end UI flow in 30 seconds without a Twilio / Sinch account.
**Status state machines (for rendering in UI):**
- Brand: `draft → submitted → in_review → approved | failed | suspended`
- Campaign: same as brand
- TFV: `draft → submitted → in_review → approved | rejected | more_info_needed`
- Number: `active | suspended | released`
**Key ID prefixes (so you can format friendly displays):**
- `brz_msgnum_*` — phone number row
- `brz_brand_*` — 10DLC brand
- `brz_camp_*` — 10DLC campaign
- `brz_tfv_*` — toll-free verification
**ISV billing knobs (already wired — see 4.11 / 4.12).** When the ISV
configures their fee schedule at `/isv/messaging-billing`, brand /
campaign / TFV / number-activation approvals AUTOMATICALLY trigger
ledger entries; no extra calls needed from this flow.
**Why this exists.** US carriers require every long-code SMS sender to
register a brand (the legal entity sending) and a campaign (what kind
of messages, with which opt-in / opt-out language) before any traffic
is allowed. Toll-free numbers go through a separate verification
process. Without it, messages are filtered or charged at penalty
rates. The endpoints here automate the paperwork.
#### Phone numbers — search → buy → release
```http
POST /v1/messaging/numbers/search
{
"provider": "twilio", // optional; defaults to merchant_settings.defaultMessagingProvider
"countryCode": "US",
"numberType": "local", // local | toll_free | mobile
"areaCode": "415",
"capabilities": ["voice", "sms"],
"limit": 20
}
```
Returns `{ provider, results: [{ e164, friendlyName, monthlyPriceCents, capabilities, ... }] }`.
No charge until you call `/buy`.
```http
POST /v1/messaging/numbers/buy
{
"provider": "twilio",
"e164": "+14155551234",
"capabilities": ["voice", "sms"],
"smsInboundWebhookUrl": "https://yourapp.com/incoming-sms",
"voiceInboundWebhookUrl": "https://yourapp.com/incoming-voice"
}
```
Returns the full `messagingNumber` row with `status: "active"`. Errors:
`409 number_already_owned`, `402 provider_billing_failed`, `502` on
provider unreachable.
```http
DELETE /v1/messaging/numbers/{id} # release back to provider
PATCH /v1/messaging/numbers/{id} # update inbound webhook URLs
GET /v1/messaging/numbers # list (filter by ?status, ?campaignId, ?provider)
GET /v1/messaging/numbers/{id} # detail
```
#### A2P 10DLC: register a brand, then a campaign
The carriers want two separate registrations: the **brand** (legal
entity behind the messages) and the **campaign** (what the messages are
for). Brands take 1–8 weeks to vet at TCR; campaigns are usually
approved within hours of an approved brand.
```http
POST /v1/messaging/brands
{
"provider": "twilio",
"legalName": "Acme Self Storage LLC",
"brandName": "Acme Storage", // DBA — what tenants see
"taxId": "123456789", // EIN — encrypted server-side, only last-4 returned
"entityType": "PRIVATE_PROFIT", // PRIVATE_PROFIT | PUBLIC_PROFIT | NON_PROFIT | GOVERNMENT | SOLE_PROPRIETOR
"vertical": "REAL_ESTATE", // TCR vertical catalog
"website": "https://acmestorage.com",
"street": "123 Main St", "city": "Austin", "region": "TX", "postalCode": "78701",
"contactFirstName": "Jane", "contactLastName": "Doe",
"contactEmail": "jane@acmestorage.com", "contactPhone": "+15125550100",
"submit": true // default true — runs provider submission inline
}
```
Status path: `draft` → `submitted` → `in_review` → `approved` (or
`failed` with `failureReasons`). Poll with
`POST /v1/messaging/brands/{id}/refresh-status` (rate-limited to
1/min/brand). The background cron also polls every 15 minutes. When the
brand transitions, a `messaging.brand.approved` / `.failed` webhook
fires.
```http
POST /v1/messaging/campaigns
{
"brandId": "brz_brand_...", // must be APPROVED
"useCase": "account_notification", // see enum: customer_care, marketing, delivery_notification,
// account_notification, two_factor_authentication, polling_voting,
// low_volume, mixed
"description": "Send rent reminders, payment confirmations, and account alerts to storage tenants who opted in.",
"messageFlow": "Tenants opt in by checking a box on the lease agreement at acmestorage.com/lease.",
"messageSamples": [
"Hi {name}, your rent of ${amount} is due on {date}. Reply PAY to charge your card on file.",
"Payment of ${amount} received. Receipt: {url}"
],
"helpMessage": "Reply with questions to our office at +15125550100, or visit acmestorage.com/help.",
"optOutKeywords": ["STOP", "CANCEL"], // default ["STOP"]
"optOutMessage": "You are unsubscribed. Reply HELP for help.",
"submit": true
}
```
Returns `409 brand_not_approved` if the brand isn't approved yet.
Status path mirrors brands; refresh with
`POST /v1/messaging/campaigns/{id}/refresh-status`.
Once the campaign is `approved`, attach numbers:
```http
POST /v1/messaging/campaigns/{id}/numbers
{ "messagingNumberIds": ["brz_msgnum_aaa", "brz_msgnum_bbb"] }
```
Bulk attach, with per-id success/failure reporting. Errors include
`number_belongs_to_other_campaign`, `provider_mismatch`,
`number_not_active`. `DELETE /v1/messaging/campaigns/{id}/numbers/{numberId}`
detaches one.
#### Toll-free verification (alternative to 10DLC)
Toll-free numbers can skip the brand+campaign dance via the carriers'
TFV path. Faster but less throughput.
```http
POST /v1/messaging/tollfree-verifications
{
"messagingNumberId": "brz_msgnum_...", // must be number_type=toll_free
"businessName": "Acme Self Storage LLC",
"businessWebsite": "https://acmestorage.com",
"notificationEmail": "ops@acmestorage.com",
"useCaseCategories": ["TWO_FACTOR_AUTHENTICATION", "ACCOUNT_NOTIFICATION"],
"useCaseSummary": "Send 2FA login codes and rent-due reminders.",
"productionMessageSample": "Your Acme Storage code is 123456. Don't share it.",
"optInImageUrls": ["https://acmestorage.com/optin-screenshot.png"],
"optInType": "WEB_FORM", // VERBAL | WEB_FORM | PAPER_FORM | VIA_TEXT | MOBILE_QR_CODE
"estimatedMonthlyVolume": 5000,
"street": "123 Main St", "city": "Austin", "region": "TX", "postalCode": "78701",
"submit": true
}
```
Status path: `draft` → `submitted` → `in_review` → `approved` |
`rejected` | `more_info_needed`. The route also flips the linked
`messagingNumber.tollfreeVerificationId` on submit so the SMS gate
(below) finds it.
#### Voice — outbound + inbound
```http
POST /v1/messaging/voice/calls
{
"from": "brz_msgnum_...", // OR raw e164 owned by merchant
"to": "+14155551234",
"twimlUrl": "https://yourapp.com/twiml/call.xml"
// OR provide inline: { twiml: "..." }
// Sinch equivalents: svamlUrl, svaml
}
```
Inbound voice goes to whatever you set on the number's
`voiceInboundWebhookUrl` — the provider POSTs straight to your URL.
Tiyo doesn't host an IVR.
#### SMS sending — gated on approval
`POST /v1/messages/sms` is the same endpoint you use for arbitrary
sends, but it now enforces an approval gate when
`merchant_settings.enforceMessagingApproval = true` (default):
- Long-code (`number_type='local'`) `from` must be attached to an
APPROVED campaign — otherwise `409 messaging_not_approved` with
`campaignStatus` in the body.
- Toll-free `from` must have an APPROVED TFV — otherwise
`409 tollfree_not_verified` with `verificationStatus` in the body.
- Non-US mobile numbers skip the gate.
```http
POST /v1/messages/sms
{
"to": "+14155551234",
"body": "Hi Jane, your rent is due Friday. Reply STOP to opt out.",
"from": "brz_msgnum_..." // optional — defaults to first approved sender
}
```
Returns `{ success, channel: "sms", provider, id, from, messagingNumberId }`.
**To bypass the gate for testing**, an admin can
`PATCH /v1/settings { enforceMessagingApproval: false }`. Logged in
audit. Don't ship production traffic with the gate disabled — the
carriers will filter.
### 4.11 Messaging Billing & Caps
A separate concern from approval gating. The gateway *meters* every
dispatched and received SMS/MMS, *enforces* a per-merchant monthly
cap, and *bills* the merchant for usage on their next invoice.
#### Tiers
| Slug | Monthly base | Included SMS | Overage SMS | MMS |
|-----------|--------------|--------------|-------------|----------|
| `starter` | $0 | 100 | $0.05 | $0.10 |
| `growth` | $15 | 500 | $0.04 | $0.10 |
| `volume` | $40 | 2,000 | $0.03 | $0.08 |
Rates stored as millicents (1000 = 1¢) in `messaging_tiers` —
admins can adjust via `PATCH /v1/admin/messaging/tiers/{id}`.
#### Cap enforcement
Before `POST /v1/messages/sms` dispatches, the gateway checks the
merchant's month-to-date usage against `messaging_monthly_cap_messages`
(default 500) and `messaging_monthly_cap_dollars` (default $25). If
either is exhausted, the request rejects with **HTTP 402
`quota_exceeded`**:
```json
{
"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 with **HTTP 402 `not_supported_in_plan`**.
Metering happens *after* a successful dispatch so a failed send
doesn't burn quota.
#### Spend alerts
The gateway fires once-per-period at 80% and 100% of either cap:
- `messaging.cap_warning` webhook + email at 80%
- `messaging.cap_reached` webhook + email at 100% (cap_reached
coincides with the first 402)
Both events carry the same `{ reason, messages_used, messages_cap,
dollars_used_cents, dollars_cap_cents, period }` envelope. Email
goes to `messaging_alert_email` if set on settings, falls back to
the merchant's primary contact otherwise. `messaging_alert_state`
has a `UNIQUE (merchant_id, billing_period, threshold)` constraint
so each threshold fires exactly once even under concurrent writes.
#### Monthly invoice rollover
Wired into the existing recurring-billing 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, prefixed with
`[messaging-billing:YYYY-MM]` in the line `notes` field as the
dedupe key.
#### Inspection + admin
Merchants:
```http
GET /v1/messaging/usage
PATCH /v1/messaging/settings
{
"messaging_monthly_cap_messages": 1000,
"messaging_alert_email": "ops@acme.com"
}
```
`GET /v1/messaging/usage` returns the same `{ period, tier, cap,
summary }` shape the dashboard widget renders. Cap edits are
limited to ≤10,000 from the merchant scope; higher requires
admin/ISV via `/v1/admin/messaging/...`.
Admin/ISV:
| Method | Path | Purpose |
|--------|------|---------|
| GET | `/v1/admin/messaging/tiers` | List tiers |
| PATCH | `/v1/admin/messaging/tiers/{id}` | Adjust tier rates (admin only) |
| GET | `/v1/admin/messaging/usage?merchant_id=brz_mer_...` | Inspect any merchant |
| PATCH | `/v1/admin/messaging/merchants/{id}/messaging-tier` | Assign a tier (admin/ISV with access) |
### 4.12 ISV-scoped messaging fee schedule
The platform tier (4.11) 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. Sinch / Twilio bill the ISV; the ISV bills the
merchant via Tiyo Pay's invoice rollover.
#### What gets charged when
| Trigger | Fee | Where it lands |
|---------|-----|----------------|
| `messaging_brands.status` flips to `approved` | `brand_registration_fee_cents` | `messaging_fee_charges` (one-time) |
| `messaging_campaigns.status` flips to `approved` | `campaign_registration_fee_cents` | `messaging_fee_charges` (one-time) |
| `messaging_tollfree_verifications.status` flips to `approved` | `tollfree_verification_fee_cents` | `messaging_fee_charges` (one-time) |
| `messaging_numbers` purchased (status=`active`) | `number_activation_fee_cents` | `messaging_fee_charges` (one-time) |
| Day-1 rollover, every active number | `number_monthly_fee_cents` | `messaging_fee_charges` (period_ym) |
| Day-1 rollover, every approved campaign | `campaign_monthly_fee_cents` | `messaging_fee_charges` (period_ym) |
Idempotency: UNIQUE
`(merchant_id, fee_type, reference_type, reference_id, period_ym)`
on `messaging_fee_charges`. A duplicate webhook, retried refresh,
or re-run cron can't double-charge.
#### When fees become billable (timing toggles)
Two ISV-controlled flags on `isv_messaging_fees` decide WHEN a fee
turns into a real invoice:
- `setup_fee_billing_mode`:
- `next_invoice` (default) — brand / campaign / TFV / number-activation fees accumulate in `messaging_fee_charges` and roll into the merchant's monthly invoice on day 1.
- `immediate` — the moment a fee fires, open a one-line draft invoice for it. Better for cash-flow; merchant sees the bill within minutes of the approval.
- `subscription_billing_mode` (subscription_tiers mode only):
- `arrears` (default) — merchant picks a tier on day 5; tier flat fee shows up on the next monthly invoice.
- `prepay` — merchant picks a tier; immediately get an invoice for that period's flat fee. Subsequent periods bill on the normal monthly cadence — the UNIQUE on `(merchant_id, fee_type, reference_type, reference_id, period_ym)` ensures the day-1 rollover sees the already-invoiced row and skips.
Subscription tier flat fees live on `messaging_fee_charges` as
`fee_type='subscription_period'`, `reference_type='merchant'`,
`reference_id=merchant.id`, `period_ym='YYYY-MM'`. The rollover cron
calls `accrueSubscriptionPeriod(merchantId, prevYm)` alongside
`accrueRecurringFees` before sweeping.
#### Pricing modes
Each ISV picks one of two billing models via
`isv_messaging_fees.pricing_mode`:
**`volume_bands` (default)** — auto-picked tier. The merchant's
monthly SMS count picks the smallest tier whose ceiling >= count;
that flat fee + overage above the top tier. ISV captures revenue
based on actual usage. With tiers `1–300 = $0`, `301–500 = $5`,
`501–1000 = $10` and overage rate `$0.05/msg`: 800 SMS = $10. 1,200
SMS = $10 + 200 × $0.05 = $20.
**`subscription_tiers`** — merchant picks one tier upfront via
`PATCH /v1/messaging/settings { messaging_tier_id }`. They're
charged that tier's flat fee EVERY period, even at zero usage —
overage applies only above the tier's ceiling. ISV captures revenue
when merchants under-utilize their plan. Tiers should be named
("Basic", "Pro", "Enterprise") via the band row's `name` column —
the dashboard uses that as the plan label in the merchant's tier
picker.
Same `isv_messaging_volume_bands` rows serve both modes; only the
interpretation at rollover differs. In subscription mode, when the
ISV has set up tiers but the merchant hasn't picked one yet,
`MessagingUsageCard` on the merchant's home shows a tier picker and
SMS billing is suspended until they pick.
#### Resolution + cost computation
- `service-messaging-billing.resolveIsvPricing(merchantId)` returns `{ bands, smsOverageMillicents, mmsMillicents }`.
- `computeSmsBillCents(count, pricing)` returns `{ bandCents, overageCents, overageCount }`.
- SMS metering rows write `merchant_cost_cents=0`; SMS cost is computed at rollover time.
- MMS metering rows write `merchant_cost_cents = mms_millicents / 100` at send time.
- Cap enforcement projects the running cost in `checkMessagingCap` so the dollar cap kicks in correctly.
When the ISV hasn't configured any bands AND `sms_overage_millicents = 0`, every SMS is effectively free until they set up.
#### Endpoints
| Method | Path | Purpose |
|--------|------|---------|
| GET | `/v1/admin/messaging/fees` | ISV reads own provisioning fees; admin uses `?developer_id=` |
| PATCH | `/v1/admin/messaging/fees` | Upsert provisioning fees + SMS overage + MMS rate |
| GET | `/v1/admin/messaging/tiers` | List the ISV's volume bands |
| POST | `/v1/admin/messaging/tiers` | Add a band: `{ up_to_messages, price_cents }` |
| PATCH | `/v1/admin/messaging/tiers/{id}` | Update a band (owner-checked) |
| DELETE| `/v1/admin/messaging/tiers/{id}` | Drop a band |
| GET | `/v1/messaging/fees` | Merchant read-only view of the provisioning schedule |
| GET | `/v1/messaging/upcoming-charges` | Pending fee charges for next monthly invoice |
| PATCH | `/v1/admin/messaging/merchants/{id}/caps` | Raise a specific merchant's monthly cap above the 10k self-service ceiling |
#### Rollover order on day-1
```
runMessagingBilling()
for each merchant whose local time = day 1 + preferredBillingHour:
accrueRecurringFees(merchantId, ym)
→ walks active numbers + active campaigns
→ INSERTs pending rows into messaging_fee_charges (idem-skipped on dup)
monthlyMessagingRollover(merchantId)
→ finds/opens [messaging-billing:YYYY-MM] draft invoice
→ if SMS activity: appends metering line item
→ for each pending fee_charge: appends line item, flips status='invoiced'
→ updates invoice subtotal+total
```
When a merchant has no SMS activity but has pending fees (e.g.,
brand approved last month), the invoice is still opened and the
fees roll forward — they don't strand in the ledger.
#### Test mode
Merchants in `test_mode=true` route through a mock messaging provider:
brand and campaign approval auto-completes ~5–10s after submit (vs
1–8 weeks live), `searchNumbers` returns five fake `+15550000…`
e164s, `buyNumber` mints `mock_PN_`, `sendSms` returns
`mock_SM_` without firing real traffic. Lets you exercise the
full gated flow end-to-end in 30 seconds.
---
## 5. POS integration pattern
This is the recommended flow for a custom POS / register / kiosk.
### 5.1 Boot: two parallel calls
```http
GET /v1/catalog/all # one response, every catalog entity
GET /v1/products?pageSize=100&expand=department,category,group,modGroups
```
`GET /v1/catalog/all` returns:
```json
{
"departments": [ ... ],
"categories": [ ... ],
"productGroups": [ ... ],
"classifications": [ ... ],
"suppliers": [ ... ],
"modGroups": [ ... ],
"modifiers": [ ... ],
"now": "2026-04-23T14:05:12.031Z"
}
```
`GET /v1/products?expand=...` returns products with related resources
inlined. `expand` keys: `department`, `category`, `group`, `classification`,
`supplier`, `modGroups`. `modGroups` also inlines modifiers inside each
mod group. Response envelope carries `now`.
**Save both `now` values as your sync cursors.**
### 5.2 Incremental sync
Every N seconds (recommend 30 s–5 min depending on volume):
```http
GET /v1/catalog/all?updated_since=
GET /v1/products?updated_since=&expand=department,category,group,modGroups
```
Only rows whose `updated_at` is strictly after the cursor come back. The
`now` in the response is your next cursor — no clock-drift math.
### 5.3 Product shape with `expand`
```json
{
"id": "brz_prd_...",
"name": "Climate-Controlled Large (10x15)",
"product_code": "CCL-10x15",
"department_id": 3,
"category_id": 7,
"product_group_id": 2,
"classification_id": null,
"supplier_id": null,
"unit_cost": 0,
"cash_price": 20000, // cents
"card_price": 20800, // cents (merchant markup applied)
"stock_level": null, // null = not tracked
"reorder_point": null,
"enabled": true,
"has_variants": false,
"allow_discounts": true,
"open_price": false,
"price_editable": false,
"mod_group_ids": [6],
"createdAt": "...",
"updatedAt": "...",
"department_name": "Storage", // lightweight sidecar (always on)
"category_name": "Climate", // lightweight sidecar
"group_name": "Indoor", // lightweight sidecar
"department": { ... full row }, // present only when ?expand=department
"category": { ... full row }, // ?expand=category
"group": { ... full row }, // ?expand=group
"mod_groups": [ // ?expand=modGroups
{ "id": 6, "name": "Access Hours", "required": false, ..., "modifiers": [ ... ] }
]
}
```
### 5.4 Taking a sale at the POS
Two common patterns:
**(a)** Card-present (physical terminal). Call `POST /v1/payments` with
`mode: "cp"` and your computed total in cents. The server waits while the
customer taps; you get the final status back on the same request.
**(b)** Card-not-present (manual entry, customer-not-at-register). Mint a
checkout session with `skip_customer_info: true` (since your POS already
knows who the customer is) and display the hosted form inline or on a
second device.
### 5.5 Ancillary POS endpoints
- `GET /v1/customers?search=jane` — live customer lookup
- `POST /v1/customers` — create on the fly
- `GET /v1/customers/{id}/cards` — saved cards to offer
- `GET /v1/discounts` — preset discounts (auto-apply + schedule aware)
- `GET /v1/settings` — merchant-wide config: `card_markup_percent`,
`cash_discount_percent`, `tax_rate` (basis points × 100), timezone, etc.
- `POST /v1/batches/{id}/close` + `POST /v1/batches/{id}/settle` — daily
close-out
---
## 5a. Terminals (POS pairing + realtime)
A **terminal** is a POS software instance — a cash register, tablet, or
phone running your app. Distinct from the physical Dejavoo card reader
(which is already paired in the merchant's Dejavoo portal and unchanged
by any of this). Each terminal has its own long-lived device secret so
a merchant can revoke one register without taking the others offline,
and every transaction it rings is attributable via `transactions.terminal_id`.
### 5a.1 Pair a register (one-time setup)
**Step 1 — dashboard user mints a code:**
```http
POST /v1/terminals/pair-codes
Authorization: Bearer
{ "suggested_name": "Register 2", "expires_in": 600 }
```
Response: `{ "code": "K7MQ-3VRX", "expires_at": "...", "expires_in": 600 }`
Codes are 8 alphanumeric chars (ambiguous glyphs 0/O/1/I/L excluded),
displayed as `ABCD-EFGH`. TTL 60 s–3600 s (default 600 s).
> **UI shortcut:** dashboard users don't have to curl this. **Merchants → *(merchant)* → Integrate** → **Pair new terminal**. The code renders in a high-contrast card with copy button + expiry, the paired terminal list auto-loads below with last-seen timestamps, and each row has a Revoke action.
**Step 2 — POS redeems it (NO auth header):**
```http
POST /v1/terminals/pair
Content-Type: application/json
{
"code": "K7MQ-3VRX",
"name": "Register 2",
"device_info": { "platform": "iOS 19.2", "appVersion": "1.4.0" }
}
```
Response:
```json
{
"terminal": { "id": "brz_term_...", "merchantId": "brz_mer_...", ... },
"device_secret": "brz_term_sec_7f3a8b1c..."
}
```
**`/v1/terminals/pair` is the ONE endpoint in the entire API that takes
no bearer auth** — the pair code itself is the auth. Save the
`device_secret` immediately (OS keychain / secure storage). Returned
once, never retrievable again.
### 5a.2 Authenticate with the device secret
Every subsequent request:
```http
GET /v1/products
Authorization: Bearer brz_term_sec_7f3a8b1c...
```
No `/v1/auth/token` exchange needed. No JWT refresh loop. The secret is
long-lived until revoked.
The `Authorization: Bearer brz_term_sec_...` prefix is how the gateway
detects terminal auth. It auto-resolves the terminal → merchant, stamps
`terminalId` on the request context, and bumps `terminals.last_seen_at`.
### 5a.3 Bootstrap endpoint
One fat endpoint the POS hits on cold-start:
```http
GET /v1/terminal/bootstrap
Authorization: Bearer brz_term_sec_...
```
Response:
```json
{
"merchant": { "id": "brz_mer_...", "name": "...", "status": "active", "testMode": false },
"settings": { "cardMarkupPercent": 4, "taxRate": 625, "tippingEnabled": true, "tipPresets": [15,18,20], ... },
"catalog": {
"departments": [ ... ],
"categories": [ ... ],
"productGroups": [ ... ],
"classifications": [ ... ],
"suppliers": [ ... ],
"modGroups": [ ... ],
"modifiers": [ ... ]
},
"products": [ /* full catalog — names inlined via department_name/category_name/group_name */ ],
"discounts": [ ... ],
"customers": [ /* up to 500 most recent */ ],
"paymentProviders": {
"cardCnp": [
{ "id": 7, "name": null, "provider": "epx_north", "mode": "cnp",
"isActive": true, "dejavooTpn": null, "registerId": null }
],
"cardCp": [
{ "id": 42, "name": "Front Counter", "provider": "dejavoo", "mode": "cp",
"isActive": true, "dejavooTpn": "TPN111", "registerId": null },
{ "id": 43, "name": "Drive-Thru", "provider": "dejavoo", "mode": "cp",
"isActive": true, "dejavooTpn": "TPN222", "registerId": null }
],
"ach": [
{ "id": 51, "name": null, "provider": "linked2pay", "mode": "cnp",
"isActive": true, "dejavooTpn": null, "registerId": null }
]
},
"now": "2026-04-23T14:05:12.031Z",
"incremental": false
}
```
**Picking a physical terminal:** `paymentProviders.cardCp` is the
POS terminal picker source. Render the list, let the cashier select
one, then pass the row's `id` as `physical_terminal_id` on
`POST /v1/payments` (or pass the `dejavooTpn` as `dejavoo_tpn` —
either works). If a merchant only has one CP terminal, or the POS
was paired with a default `terminals.dejavoo_tpn`, the pin is
optional.
**Incremental sync** — poll every 30 s to 5 min:
```http
GET /v1/terminal/bootstrap?updated_since=
```
Only rows whose `updated_at` is strictly after the cursor come back.
`incremental: true`. **Customers are omitted from incremental
responses** (they change often, rebuilding a 10k-row list every minute
is wasteful). Save the new `now` as the next cursor.
Products are **unbounded** on full sync — the register needs the full
catalog to ring sales offline. If you ever hit merchants with >50k
SKUs we'll add pagination.
### 5a.4 Realtime push (optional)
Replace the 30 s poll with a WebSocket. Uses Supabase Realtime (already
running as part of the Supabase project — no custom WS server).
**Mint a realtime JWT:**
```http
POST /v1/terminals/realtime-token
Authorization: Bearer brz_term_sec_...
{ "expires_in": 3600 }
```
Response:
```json
{
"token": "eyJ...",
"expires_in": 3600,
"merchant_id": "brz_mer_...",
"realtime_url": "https://crwbtzryadlpmlupgcmz.supabase.co/realtime/v1",
"channel": "merchant:brz_mer_..."
}
```
**Subscribe** (Node / browser):
```ts
import { createClient } from "@supabase/supabase-js";
const sb = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
sb.realtime.setAuth(realtimeJwt);
sb.channel(`merchant:${merchantExternalId}`)
.on("postgres_changes", { event: "*", schema: "public", table: "products" },
(payload) => applyProductChange(payload))
.on("postgres_changes", { event: "*", schema: "public", table: "discounts" },
(payload) => applyDiscountChange(payload))
.on("postgres_changes", { event: "*", schema: "public", table: "merchant_settings" },
(payload) => applySettingsChange(payload))
.subscribe();
```
Tables enabled for Realtime: `products`, `discounts`, `merchant_settings`,
`departments`, `categories`, `product_groups`, `classifications`,
`suppliers`, `modifier_groups`, `modifiers`, `terminals`. Each payload
has `eventType` (INSERT/UPDATE/DELETE), `new`, `old`.
RLS policies on all those tables enforce `merchant_id = jwt_merchant_id()`
— a compromised terminal can't subscribe to another merchant's rows.
**Always keep the updated_since poll running at a slow cadence (e.g. 5 min)
as a safety net** — WebSocket connections drop during network blips and
can silently miss events. The poll catches anything the stream missed.
### 5a.5 Manage terminals
```http
GET /v1/terminals # List merchant's terminals
GET /v1/terminals/{id} # Retrieve
PATCH /v1/terminals/{id} # Rename, pin TPN, update config, deactivate
DELETE /v1/terminals/{id} # Revoke (device secret stops working)
```
### 5a.6 Sale attribution
Every `POST /v1/payments` made with a terminal device secret
automatically stamps `transactions.terminal_id`. Existing API-key /
dashboard traffic stays attributed to `terminal_id: null` — no
migration needed, zero breaking change.
---
## 6. Catalog resources
All merchant-scoped. All accept `?updated_since=` now.
```http
GET /v1/catalog?entity=departments # { data: [...], now }
GET /v1/catalog?entity=categories
GET /v1/catalog?entity=product-groups
GET /v1/catalog?entity=classifications
GET /v1/catalog?entity=suppliers
GET /v1/catalog?entity=mod-groups
GET /v1/catalog?entity=modifiers[&mod_group_id=N]
```
Write endpoints for each:
```http
POST /v1/catalog?entity= { name, ... }
PATCH /v1/catalog/{id}?entity= { ...partial }
DELETE /v1/catalog/{id}?entity=
```
Modifiers additionally require `mod_group_id` on create.
### POS-authoritative write pattern
If you're building a register that lets cashiers create items or modifiers
on the fly, **write to Tiyo first, then mirror to the local DB** — not the
other way around. Tiyo must own the row so:
* Every other paired terminal picks it up on the next `/v1/terminal/bootstrap`
poll automatically.
* Receipts, reports, refunds, and repeat charges can reference the real id.
* Re-syncing or onboarding a new terminal rebuilds state from Tiyo alone.
```js
async function createModifier({ modGroupId, name, priceAdjustmentCents }) {
// 1. Tiyo writes the authoritative row.
const res = await fetch(`${GATEWAY}/v1/catalog?entity=modifiers`, {
method: "POST",
headers: {
Authorization: `Bearer ${terminalSecret}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
mod_group_id: modGroupId,
name,
price_adjustment: priceAdjustmentCents,
enabled: true,
}),
});
if (!res.ok) throw new Error((await res.json()).message);
const saved = await res.json();
// 2. Mirror locally so the cashier's UI is immediate.
await localDb.modifiers.upsert({ tiyoId: saved.id, ...saved });
return saved;
}
```
Same pattern for products, departments, categories, modifier groups, etc.
Never let a local-only row exist — a terminal rebuild from bootstrap will
never see it, and any transaction that references it loses context the
moment the local DB is wiped.
If the register is offline when the cashier hits Save, queue the write
and retry on reconnect. Never accept a local-only create as "done."
---
## 7. Endpoint reference (exhaustive)
All require `Authorization: Bearer ` unless noted. List endpoints
default to `?page=1&pageSize=20` (max 100).
### Auth
| Method | Path | Purpose |
|---|---|---|
| POST | `/v1/auth/token` | Exchange API key or refresh token for a JWT (no auth) |
| POST | `/v1/auth/revoke` | Revoke a JWT or refresh token |
| GET | `/v1/me` | Caller identity + active merchant + branding |
| GET | `/v1/me/accessible-merchants` | List merchants caller can scope to |
| GET | `/v1/me/api-logs` | Paginated API request log for this merchant |
| GET | `/v1/me/branding` | ISV-only: own brand row |
| PUT | `/v1/me/branding` | ISV-only: update brand |
| POST | `/v1/me/branding/extract` | Best-effort brand autofill from a URL |
### Payments
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/payments` | List transactions (filter: `status`, `type`) |
| POST | `/v1/payments` | Charge a card (`mode`: `cnp` default or `cp`). **Idempotency-Key required.** |
| GET | `/v1/payments/{id}` | Retrieve. `?expand=customer` inlines customer. |
| GET | `/v1/payments/{id}/history` | Audit trail for this transaction |
| POST | `/v1/payments/{id}/void` | Void pre-settlement (host-side; never contacts the terminal). Failed voids return `voidStatus: "failed"` and leave the original sale `approved`. |
| POST | `/v1/payments/{id}/refund` | `{ amount? }` — omit for full refund. Host-side by RRN; never contacts the terminal. |
| POST | `/v1/payments/{id}/repeat` | Rerun a prior sale with its stored reusable token |
| POST | `/v1/payments/{id}/adjust-tip` | `{ tip: }` |
| POST | `/v1/payments/{id}/receipt` | Email / SMS a receipt |
| POST | `/v1/payments/tokenize` | Mint a reusable card token via $0 Auth-Only ($1 auth + reversal fallback). No funds held. Replaces the old $1 sale + auto-void path that was invalidating chdTokens on Dejavoo UAT. |
| POST | `/v1/admin/cards/revalidate` | `{ merchantId, limit? }` — sweep saved tokens through `tokenize()`, mark rejects with `invalidated_at`. Auto-pay skips invalidated cards and emits `payment_method.invalid`. |
| POST | `/v1/admin/cards/test-mint` | Admin/developer + `test_mode` merchants only. `{ customerId, merchantId?, brand, exp_month, exp_year, last4?, isDefault? }` — inserts a saved card row with a synthetic `BRZTEST_` chdToken. Skips the processor; subsequent charges in test_mode auto-approve via the synthetic-token shortcut in `createPayment`. |
| POST | `/v1/admin/cards/test-mint-bulk` | `{ merchantId, customerIds: [...], brand, exp_month, exp_year, isDefault? }` — batched mint. Returns `{ minted, failed, cards, failures }`. |
| POST | `/v1/customer-subscriptions` (`bundle_key`) | Optional `bundle_key` field. Subs with the same `(customer_id, bundle_key, card_id, next_billing_date)` charge as ONE transaction with a multi-line invoice. One `invoice.paid` event with `metadata.subscription_ids: [...]`. Solo subs (no bundle_key) keep firing independently. |
| POST | `/v1/payments/{id}/refund` (`subscription_id`) | For bundled subscription charges, pass `subscription_id` instead of `amount` to refund just that line's contribution. Looks up `invoice_items.total` for the matching sub on the bundled invoice. |
### Branding
| Method | Path | Purpose |
|---|---|---|
| POST | `/v1/logos` | Multipart upload of a merchant logo. Body: `file` (PNG/JPEG/GIF/WebP/SVG, ≤5 MiB) + optional `target` (`logo_url` / `invoice_logo_url` / `both` / `none`). Returns the hosted URL and applies it to merchant_settings when target is set. |
| POST | `/v1/logos/from-url` | `{ url, target? }` — fetch a logo from a public URL, rehost on Tiyo, and (optionally) apply. Use this after `/v1/me/branding/extract` so the persisted URL is permanent (extracted URLs from platform sites are often short-lived pre-signed S3 URLs). |
| POST | `/v1/me/branding/extract` | `{ url }` — scrape a public website for name / logoUrl / primaryColor. Read-only; chain into `/v1/logos/from-url` to persist a permanent copy. |
### Docs (public, no auth)
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/openapi.json` | OpenAPI 3.1 spec for the entire gateway. |
| GET | `/v1/llm.md` | This integration guide as `text/markdown`. |
| GET | `/v1/integration-guide.md` | Alias of `/v1/llm.md`. |
| GET | `/v1/llm.json` | Combined bundle: this guide + the OpenAPI spec + version metadata in one JSON envelope. |
### Setup Intents (save card without charging)
| Method | Path | Purpose |
|---|---|---|
| POST | `/v1/setup-intents` | Create. `{ customer_id, return_url?, expires_in? }` |
| GET | `/v1/setup-intents/{id}` | Retrieve |
### Customers
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/customers` | List. Filters: `status`, `search` |
| POST | `/v1/customers` | `{ first_name, last_name, email?, phone?, address*?, ... }` |
| GET | `/v1/customers/{id}` | Retrieve (adds `cards_count`, `total_spent`) |
| PATCH | `/v1/customers/{id}` | Partial update |
| DELETE | `/v1/customers/{id}` | Soft delete (cascades: pauses recurring, cancels subs) |
| GET | `/v1/customers/{id}/cards` | List saved cards |
| POST | `/v1/customers/{id}/cards` | Add a card manually. Dedups by token, then by fingerprint (`brand + last4 + exp_month + exp_year`). Returns `201` on a fresh insert and `200` on a dedup hit. |
| DELETE | `/v1/customers/{id}/cards/{cardId}` | Delete a card |
| GET | `/v1/customers/{id}/transactions` | List this customer's transactions |
| GET | `/v1/customers/{id}/subscriptions` | List this customer's subscriptions |
| POST | `/v1/customers/{id}/portal-sessions` | Mint a portal URL |
### Products
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/products` | List. `?expand=...`, `?updated_since=...`, filters: `department_id`, `enabled`, `search` |
| POST | `/v1/products` | Create |
| GET | `/v1/products/{id}` | Retrieve. `?expand=...` supported |
| PATCH | `/v1/products/{id}` | Update |
| DELETE | `/v1/products/{id}` | Delete |
| GET | `/v1/products/{id}/variants` | List variants |
| POST | `/v1/products/{id}/variants` | Create variant |
| PATCH | `/v1/products/{id}/variants/{variantId}` | Update variant |
| DELETE | `/v1/products/{id}/variants/{variantId}` | Delete variant |
### Catalog (auxiliary product data)
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/catalog/all` | All seven entities in one response. `?updated_since=` supported. |
| GET | `/v1/catalog?entity=` | List one type. `?updated_since=` supported. |
| POST | `/v1/catalog?entity=` | Create |
| PATCH | `/v1/catalog/{id}?entity=` | Update |
| DELETE | `/v1/catalog/{id}?entity=` | Delete |
Types: `departments`, `categories`, `product-groups`, `classifications`,
`suppliers`, `mod-groups`, `modifiers`.
### Discounts
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/discounts` | List. Filter: `enabled` |
| POST | `/v1/discounts` | Create |
| GET | `/v1/discounts/{id}` | Retrieve |
| PATCH | `/v1/discounts/{id}` | Update |
| DELETE | `/v1/discounts/{id}` | Delete |
Discount shape includes `type` (percentage/fixed), `value`, `applies_to`,
`applicable_ids`, `auto_apply`, `min_purchase`, `max_discount`, and
scheduling (`schedule`, `scheduleStart/End`, `scheduleDays`,
`scheduleStartTime/EndTime`). Merchant timezone applies at compare time.
### Membership plans
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/membership-plans` | List (with active-subscriber count) |
| POST | `/v1/membership-plans` | Create. `{ name, price, billing_cycle, items?, discount_percent?, duration_type?, duration_value? }` |
| GET | `/v1/membership-plans/{id}` | Retrieve with items |
| PATCH | `/v1/membership-plans/{id}` | Update |
| DELETE | `/v1/membership-plans/{id}` | Delete |
### Customer subscriptions
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/customer-subscriptions` | List. Filters: `customer_id`, `plan_id`, `status` |
| POST | `/v1/customer-subscriptions` | Sell a plan. Charges first cycle if `charge_now` ≠ false |
| GET | `/v1/customer-subscriptions/{id}` | Retrieve |
| PATCH | `/v1/customer-subscriptions/{id}` | Update status (`active`/`paused`/`cancelled`/`past_due`) |
| DELETE | `/v1/customer-subscriptions/{id}` | Cancel |
### Recurring billing (simple schedule, no plan)
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/recurring` | List |
| POST | `/v1/recurring` | `{ customer_id, card_id?, amount, frequency, next_billing_date, total_cycles? }` |
| GET | `/v1/recurring/{id}` | Retrieve |
| PATCH | `/v1/recurring/{id}` | Update |
| DELETE | `/v1/recurring/{id}` | Delete |
### Invoices
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/invoices` | List. Filters: `status`, `customer_id` |
| POST | `/v1/invoices` | Create. `{ customer_id, items[], due_date?, auto_pay?, allow_partial? }` |
| GET | `/v1/invoices/{id}` | Retrieve with items |
| PATCH | `/v1/invoices/{id}` | Update (drafts: everything. Sent: `status`, `auto_pay` only) |
| DELETE | `/v1/invoices/{id}` | Drafts only |
| POST | `/v1/invoices/{id}/send` | Email / SMS |
| POST | `/v1/invoices/{id}/pay` | Charge a linked card now. `{ card_id? }`. Emits `payment.completed` + `invoice.paid` on success. |
| POST | `/v1/invoices/test-email` | Preview current invoice branding via a sample |
### Checkout Sessions (hosted payment page)
| Method | Path | Purpose |
|---|---|---|
| POST | `/v1/checkout/sessions` | Mint a session. Optional fields: `line_items[]`, `payment_methods[]`, `pricing` (dual-pricing snapshot), `metadata` (caller tags). |
| GET | `/v1/checkout/sessions/{id}` | Status poll |
| POST | `/v1/checkout/sessions/{id}/complete` | Internal — called by the hosted page |
### Batches
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/batches` | List. Filter: `status` |
| GET | `/v1/batches/{id}` | Retrieve |
| POST | `/v1/batches` | Open a new batch |
| POST | `/v1/batches/{id}/close` | Close (computes totals from transactions) |
| POST | `/v1/batches/{id}/settle` | Mark settled |
| GET | `/v1/batches/processor` | **Dejavoo only.** Pull settlement data from iPOSpays directly. `?date=YYYY-MM-DD`, `?from=`, `?to=` |
### Webhooks
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/webhooks` | List (filter: `merchantId`) |
| POST | `/v1/webhooks` | Register. `{ url, events: [...] }`. Secret returned ONCE in the response |
| PATCH | `/v1/webhooks/{id}` | Update url / events / isActive |
| DELETE | `/v1/webhooks/{id}` | Delete |
| POST | `/v1/webhooks/{id}/test` | Fire a synthetic `webhook.test` event |
| POST | `/v1/webhooks/{id}/rotate-secret` | `{ overlap_hours? }`. Returns old + new secrets. Both valid during overlap |
| GET | `/v1/webhooks/{id}/deliveries` | Delivery history |
| POST | `/v1/webhooks/{id}/deliveries/{deliveryId}/retry` | Force-retry a failed/exhausted delivery |
### Events (backfill / replay)
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/events` | List. Filters: `type`, `resource_id`, `after`, `before`. Cursor-paginated (`starting_after`, `limit`, response: `has_more`, `next_cursor`) |
| GET | `/v1/events/{id}` | Retrieve one |
### Disputes
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/disputes` | List |
| GET | `/v1/disputes/{id}` | Retrieve |
| POST | `/v1/disputes/{id}/evidence` | Submit evidence (rejected for terminal statuses) |
### Reports
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/reports?from=YYYY-MM-DD&to=YYYY-MM-DD[&merchantId=...]` | Summary + daily breakdown |
Response includes `totalVolume`, `transactionCount`, `approvedCount`,
`declinedCount`, `failedCount`, `voidedCount`, `refundCount`,
`refundVolume`, `averageApproved`, `largestApproved`, `approvalRate`,
`activeCustomers`, and `daily: [{date, volume, count, approvedCount}]`.
### Settings (merchant-wide config)
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/settings` | Full merchant settings blob |
| PATCH | `/v1/settings` | Partial update. Also recalculates product `card_price` when `cardMarkupPercent` changes. |
### Merchants / Developers / Groups (admin + ISV)
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/merchants` | List (role-aware) |
| POST | `/v1/merchants` | Create (admin / ISV) |
| POST | `/v1/merchants/onboard-isv` | Admin only — create a new ISV (developer-role user, no merchant). |
| POST | `/v1/merchants/onboard` | Full merchant onboarding. ISV caller auto-owns. Admin caller MUST pass `owningDeveloperId` (ISV external id) — admins can't own merchants directly. |
| GET | `/v1/merchants/{id}` | Retrieve |
| PATCH | `/v1/merchants/{id}` | Update (admin / ISV) |
| GET | `/v1/developers` | List developers |
| POST | `/v1/developers` | Create (admin / ISV) |
| GET | `/v1/developers/{id}/access` | Groups + direct merchants |
| POST | `/v1/developers/{id}/merchants` | Grant direct merchant access |
| DELETE | `/v1/developers/{id}/merchants/{merchantId}` | Revoke |
| GET | `/v1/developers/{id}/keys` | List API keys |
| POST | `/v1/developers/{id}/keys` | Create API key — secret returned ONCE |
| POST | `/v1/developers/{id}/keys/{keyId}/revoke` | Revoke |
| POST | `/v1/developers/{id}/keys/{keyId}/rotate` | Rotate — same row, fresh secret returned ONCE. Reactivates a revoked key. |
| GET | `/v1/merchant-groups` | List (role-aware) |
| POST | `/v1/merchant-groups` | Create |
| GET | `/v1/merchant-groups/{id}` | Retrieve with members + developers |
| PATCH | `/v1/merchant-groups/{id}` | Update |
| DELETE | `/v1/merchant-groups/{id}` | Delete |
| POST | `/v1/merchant-groups/{id}/members` | Add merchant to group |
| DELETE | `/v1/merchant-groups/{id}/members/{merchantId}` | Remove |
| POST | `/v1/merchant-groups/{id}/developers` | Assign developer |
| DELETE | `/v1/merchant-groups/{id}/developers/{developerId}` | Unassign |
### Tokenization config
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/tokenization/config?type=card\|ach` | Returns the provider's tokenization URL + publishable key so you can build a custom hosted form |
### Audit log
| Method | Path | Purpose |
|---|---|---|
| GET | `/v1/audit-log` | Paginated. Filters: `merchantId` (admin), `eventType`, `limit`, `offset` |
| GET | `/v1/audit-log/event-types` | Distinct event_types for filter UIs |
### Jobs (admin-only, used by cron)
| Method | Path | Purpose |
|---|---|---|
| POST | `/v1/jobs/run-billing` | Runs recurring, subscriptions, and invoice auto-pay |
| POST | `/v1/jobs/run-webhook-deliveries` | Drains the webhook delivery queue |
### Terminals (POS pairing)
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/terminals/pair-codes` | dashboard JWT | Mint a short-lived pair code |
| POST | `/v1/terminals/pair` | **none** | Redeem a pair code → terminal + device_secret |
| POST | `/v1/terminals/realtime-token` | any | Mint a Supabase Realtime JWT scoped to the caller's merchant |
| GET | `/v1/terminals` | any | List terminals for the current merchant |
| GET | `/v1/terminals/{id}` | any | Retrieve |
| PATCH | `/v1/terminals/{id}` | dashboard JWT | Rename, pin Dejavoo TPN, update config, deactivate |
| DELETE | `/v1/terminals/{id}` | dashboard JWT | Revoke (device secret stops working immediately) |
| POST | `/v1/terminals/{id}/rotate` | dashboard JWT | Rotate — same terminal row, fresh device secret returned ONCE. Old device's secret stops working immediately. Reactivates a revoked terminal. |
| POST | `/v1/terminals/{id}/pair-code` | dashboard JWT | Re-issue an 8-digit pair code BOUND to this terminal. When the new device redeems it via `/v1/terminals/pair`, the gateway rotates the existing terminal's device_secret instead of creating a new row. Old device keeps working until the new one pairs. |
| GET | `/v1/terminal/bootstrap[?updated_since=ISO]` | any (usually terminal secret) | One-shot hydrate or incremental sync |
| POST | `/v1/terminals/square/pair-code` | dashboard JWT | Mint a Square device code via `POST /v2/devices/codes`. Merchant types the 8-char code into a physical Square Terminal; the `device.code.paired` webhook stamps `terminals.square_device_id` |
| GET | `/v1/terminals/square/{id}/status` | dashboard JWT | Poll pairing state (`paired`, `deviceId`, `status`) |
| POST | `/v1/terminals/square/{id}/repair` | dashboard JWT | Mint a fresh code bound to an existing terminal — same id + history, new physical device |
### Square OAuth onboarding + auto-board
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/onboarding/square/start` | merchant JWT | Mints OAuth URL — production routes through ISV's reseller referral link (residuals attributed); sandbox uses plain OAuth. Embedder pops the URL, merchant grants access |
| GET | `/v1/onboarding/square/callback` | **none** (state token is the auth) | Exchanges the OAuth code, runs 24h `created_at` age check in production, captures access_token + location_id into `merchant_providers.credentials` (or `test_credentials` in sandbox), fires `merchant.provider.connected` webhook, returns an HTML `postMessage` page back to the embedder |
| ISV setting | `isv_settings.square_auto_board` | ISV JWT | When true, every `POST /v1/merchants/onboard` returns `next_step.square_onboard_url` so the ISV's signup wizard can redirect the new merchant straight into Square OAuth |
### Messaging (phone numbers, A2P 10DLC, toll-free, voice)
See section 4.10 for end-to-end flow + sample bodies.
| Method | Path | Purpose |
|---|---|---|
| POST | `/v1/messaging/numbers/search` | Search provider inventory |
| POST | `/v1/messaging/numbers/buy` | Purchase a number (`409 number_already_owned`, `402 provider_billing_failed`) |
| GET | `/v1/messaging/numbers` | List (filters: `?status`, `?campaignId`, `?provider`) |
| GET | `/v1/messaging/numbers/{id}` | Detail (includes attached campaign + TFV ids) |
| PATCH | `/v1/messaging/numbers/{id}` | Update inbound webhook URLs (push to provider; rolls back on failure) |
| DELETE | `/v1/messaging/numbers/{id}` | Release back to provider |
| POST | `/v1/messaging/brands` | Register an A2P 10DLC brand. `submit:true` (default) runs upstream submission inline |
| GET | `/v1/messaging/brands` | List |
| GET | `/v1/messaging/brands/{id}` | Detail (with campaigns) |
| PATCH | `/v1/messaging/brands/{id}` | Edit (only when status = `draft` or `failed`); `submit:true` resubmits |
| POST | `/v1/messaging/brands/{id}/refresh-status` | Force-poll provider (1/min/brand) |
| POST | `/v1/messaging/campaigns` | Register a campaign. Parent brand must be `approved`. `409 brand_not_approved` otherwise |
| GET | `/v1/messaging/campaigns` | List |
| GET | `/v1/messaging/campaigns/{id}` | Detail (with attached numbers) |
| PATCH | `/v1/messaging/campaigns/{id}` | Edit (draft/failed only) |
| POST | `/v1/messaging/campaigns/{id}/refresh-status` | Force-poll provider (1/min/campaign) |
| POST | `/v1/messaging/campaigns/{id}/numbers` | Bulk attach numbers — campaign must be `approved`. Per-id success/failure list |
| DELETE | `/v1/messaging/campaigns/{id}/numbers/{numberId}` | Detach one |
| POST | `/v1/messaging/tollfree-verifications` | Submit a TFV (alternative to 10DLC, for toll-free numbers only) |
| GET | `/v1/messaging/tollfree-verifications` | List |
| GET | `/v1/messaging/tollfree-verifications/{id}` | Detail |
| PATCH | `/v1/messaging/tollfree-verifications/{id}` | Edit (draft/rejected/more_info_needed only) |
| POST | `/v1/messaging/tollfree-verifications/{id}/refresh-status` | Force-poll (1/min/TFV) |
| POST | `/v1/messaging/voice/calls` | Place an outbound call. Routes through whichever provider owns the `from` number |
| POST | `/v1/messages/sms` | Send SMS — approval-gated when `merchant_settings.enforceMessagingApproval=true`. **402 `quota_exceeded`** when the monthly cap is hit; **402 `not_supported_in_plan`** for international destinations |
| GET | `/v1/messaging/usage` | Current-month metering snapshot for the merchant |
| PATCH | `/v1/messaging/settings` | Update merchant `messaging_monthly_cap_messages` (≤10k) + `messaging_alert_email` |
| GET | `/v1/admin/messaging/tiers` | List messaging tiers (admin/ISV) |
| PATCH | `/v1/admin/messaging/tiers/{id}` | Adjust tier rates (admin only) |
| GET | `/v1/admin/messaging/usage?merchant_id=` | Inspect any merchant's usage (admin/ISV) |
| PATCH | `/v1/admin/messaging/merchants/{id}/messaging-tier` | Assign a tier to a merchant (admin/ISV with access) |
| GET | `/v1/admin/messaging/fees` | Read ISV provisioning fees + SMS overage + MMS rate (admin uses `?developer_id=`) |
| PATCH | `/v1/admin/messaging/fees` | Upsert provisioning fees, SMS overage, MMS rate |
| GET | `/v1/admin/messaging/tiers` | List the ISV's volume bands |
| POST | `/v1/admin/messaging/tiers` | Add a volume band |
| PATCH | `/v1/admin/messaging/tiers/{id}` | Update a band |
| DELETE | `/v1/admin/messaging/tiers/{id}` | Drop a band |
| PATCH | `/v1/admin/messaging/merchants/{id}/caps` | Raise a specific merchant's monthly cap |
| GET | `/v1/messaging/fees` | Merchant read-only view of ISV provisioning fee schedule. Now includes `tiers[]` + `current_tier_id` for the wizard's tier-picker step |
| GET | `/v1/messaging/tiers` | Merchant-scope list of the ISV's configured subscription tiers + current selection. Same data as `/fees.tiers`; standalone for tier-picker steps |
| GET | `/v1/messaging/upcoming-charges` | Pending fee charges that will land on the next monthly invoice |
| POST | `/v1/messaging/brands/{id}/sync` | Retry-submit a `draft` or `failed` brand without re-entering data. Calls the provider's `registerBrand` against the persisted row |
| POST | `/v1/messaging/brands` (`registrationTier`) | Sinch-only — `SIMPLIFIED` ($10, no vetting) vs `FULL` ($50, vetted, default). Twilio ignores |
| Field | Brand response: `tcrBrandId` | TCR brand id (e.g. `BU2GS70`) — minted post-approval, used by downstream TCR ops |
| Field | Brand response: `identityStatus` | TCR vetting state, separate from overall `status`. Display-only |
| Field | Campaign response: `tcrCampaignId` | TCR campaign id, minted post-approval |
| Field | Campaign response: `lastActionStatus` | Sinch's per-action sub-status (`CREATE_FAILED`, `RESUBMIT_FAILED`, etc.) |
| GET | `/v1/messaging/failure-resolution?code=` | Translates raw provider failure codes (TCR CR codes, Sinch operational, Twilio errors) to user-facing remediation copy with structured action steps. ISV wizards call this on the failed-state UI to render actionable fixes |
| GET | `/v1/messaging/failure-resolution` | Returns the full dictionary, sorted by code |
---
## 8. Webhooks
### 8.1 Registering
```http
POST /v1/webhooks
{
"url": "https://yoursite.com/hooks/tiyo",
"events": ["payment.completed", "payment.declined", "invoice.paid", "subscription.payment_failed"]
}
```
Response returns `secret` — save it NOW. Never exposed again.
### 8.2 Verifying signatures
Every delivery includes:
- `X-Tiyo-Signature: sha256=` — HMAC-SHA256 of the raw request body
with your signing secret. Multiple signatures (comma-separated) during a
rotation overlap window. Accept the delivery if the body verifies
against ANY signature in the list.
- `X-Tiyo-Event: ` — convenience header.
Node/TypeScript:
```ts
import crypto from "node:crypto";
function verify(rawBody: string, header: string, secret: string): boolean {
const computed = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const received = header.split(",").map(s => s.trim());
return received.some(sig =>
sig.length === computed.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(computed))
);
}
```
### 8.3 Retry policy
Failed deliveries retry on a fixed schedule:
```
instant → +5m → +30m → +2h → +12h → +24h → +48h → +72h
```
After 8 total attempts the delivery is `exhausted` and the webhook
endpoint is auto-disabled. Reactivate by PATCHing `isActive: true`.
### 8.4 Event catalogue
| Type | Meaning |
|---|---|
| `payment.completed` | Charge approved |
| `payment.declined` | Charge declined |
| `payment.failed` | Gateway / processor error |
| `payment.voided` | Void succeeded |
| `payment.refunded` | Full refund |
| `payment.partial_refunded` | Partial refund |
| `subscription.created` | Customer subscribed |
| `subscription.payment_succeeded` | Cycle charge approved |
| `subscription.payment_failed` | Cycle charge failed |
| `subscription.past_due` | Hit 3 consecutive failures |
| `subscription.renewed` | Cron advanced to next period |
| `subscription.canceled` | Status flipped to cancelled |
| `invoice.sent` | Send job completed (at least one channel) |
| `invoice.paid` | Invoice settled |
| `invoice.auto_pay_approved` | Cron auto-pay approved |
| `invoice.auto_pay_declined` | Cron auto-pay declined |
| `recurring.payment_approved` | Recurring cycle approved |
| `recurring.payment_failed` | Recurring cycle failed |
| `recurring.paused` | 3 consecutive failures → paused |
| `customer.created` | New customer row |
| `webhook.test` | Synthetic test fired from dashboard |
| `messaging.number.purchased` | Number bought from the provider |
| `messaging.number.released` | Number released back |
| `messaging.brand.submitted` | Brand POSTed to provider |
| `messaging.brand.approved` | Brand verified at TCR / Sinch |
| `messaging.brand.failed` | Brand rejected (`failureReasons` in payload) |
| `messaging.campaign.submitted` | Campaign POSTed to provider |
| `messaging.campaign.approved` | Campaign approved — numbers can be attached |
| `messaging.campaign.failed` | Campaign rejected; attached numbers auto-detached |
| `messaging.campaign.numbers_attached` | Bulk-attach completed (partial success possible) |
| `messaging.campaign.number_detached` | Single-number detach |
| `messaging.tfv.submitted` | Toll-free verification submitted |
| `messaging.tfv.approved` | TFV approved; toll-free SMS now allowed |
| `messaging.tfv.rejected` | TFV rejected (`rejectionReasons` in payload) |
| `messaging.sms.sent` | SMS sent through `/v1/messages/sms` |
| `messaging.cap_warning` | Merchant crossed 80% of either messaging cap (messages or dollars) |
| `messaging.cap_reached` | Merchant hit 100% of either cap; outbound SMS now refusing with 402 |
### 8.5 Backfill via the Events API
If your webhook consumer was down, pull everything you missed:
```http
GET /v1/events?type=payment.completed&after=2026-04-20T00:00:00Z&limit=100
```
Walk with `starting_after=&limit=100` until
`has_more: false`.
---
## 9. Idempotency deep dive
- `Idempotency-Key` is **required** on `POST /v1/payments`. Replaying with
the same key within 24 h returns the cached response verbatim.
- `POST /v1/customers`, `POST /v1/invoices`, `POST /v1/customer-subscriptions`,
`POST /v1/recurring`, `POST /v1/checkout/sessions`, `POST /v1/setup-intents`
accept optional idempotency — pass a key if you care about replay safety,
skip it if you don't.
- Duplicate in-flight with same key → `409 Duplicate request in progress`.
- Keep keys ≤255 chars. Use something unique: `order_{id}_{timestamp}`,
`sub_cycle_{subscription_id}_{yyyy_mm_dd}`, `user_signup_{user_id}`.
---
## 10. Sandbox / test mode
Merchants can flip `test_mode: true` (on `merchants`). Tokenization config
and provider credentials switch to sandbox. Transactions stamped
`metadata.testMode: true` so reports can exclude them if needed.
There's no separate test URL — same endpoints, just different creds
under the hood.
---
## 11. Multi-merchant scoping (admin / ISV)
If your JWT belongs to an `admin` or an ISV (role `developer`), you can
scope any request to a specific merchant:
```http
GET /v1/products
Authorization: Bearer
X-Merchant-Id: brz_mer_5e35...
```
Rules:
- Value accepted as either the external id (`brz_mer_...`) or the internal
numeric id.
- If the target is not in the caller's `accessibleMerchantIds`, the
request **403s** with `authorization_error` — the gateway never
silently falls back to the caller's primary merchant, since that
used to mask write-to-wrong-row bugs on per-merchant settings PATCHes.
- API keys (`brz_key_...`) are permanently bound to their merchant unless
the owning developer is `admin`.
`GET /v1/me/accessible-merchants` tells you what the caller can scope to.
**Terminal device secrets** (`brz_term_sec_...`) are hard-bound to the
merchant they were paired under — `X-Merchant-Id` is IGNORED for terminal
callers. If a POS needs to switch merchants, re-pair.
### Auth header cheat sheet
| Caller | Header | Credential type |
|---|---|---|
| Dashboard user (browser session) | `Authorization: Bearer ` | Supabase Auth — managed by the dashboard |
| SDK / server integrator | `Authorization: Bearer ` | 15-min JWT from `POST /v1/auth/token` (client_credentials) |
| Paired POS terminal | `Authorization: Bearer brz_term_sec_...` | Long-lived device secret from `POST /v1/terminals/pair` |
| Admin / ISV acting on behalf | JWT + `X-Merchant-Id: brz_mer_...` | Switches merchant context per-request |
---
## 12. SDKs (all open-source, all follow the same shape)
- Node/TS: `npm install tiyo-sdk`
- Python: `pip install tiyo`
- PHP: `composer require tiyopay/tiyo`
- Go: `go get github.com/goodcodeworks/tiyo-gateway/sdks/go`
- Ruby: `gem install tiyo`
- Java: `com.tiyopay:tiyo:1.0.0` (Maven)
- .NET: `dotnet add package Tiyo Pay`
Every SDK is generated from the same OpenAPI spec — behavior is identical.
For languages without an official SDK, point `openapi-generator` or
Microsoft Kiota at `GET /v1/openapi.json`.
### Messaging on the Node/TS SDK
```ts
import { TiyoClient } from "tiyo-sdk";
const tiyo = new TiyoClient({ clientId, clientSecret });
// 1. Find a number to buy.
const { results } = await tiyo.messaging.numbers.search({
numberType: "local",
areaCode: "415",
capabilities: ["voice", "sms"],
});
// 2. Buy it.
const num = await tiyo.messaging.numbers.buy({
e164: results[0].e164,
capabilities: ["voice", "sms"],
smsInboundWebhookUrl: "https://yourapp.com/incoming-sms",
});
// 3. Register the brand (the merchant's legal entity).
const brand = await tiyo.messaging.brands.create({
provider: "twilio",
legalName: "Acme Self Storage LLC",
brandName: "Acme Storage",
taxId: "123456789",
entityType: "PRIVATE_PROFIT",
vertical: "REAL_ESTATE",
street: "123 Main St", city: "Austin", region: "TX", postalCode: "78701",
contactFirstName: "Jane", contactLastName: "Doe",
contactEmail: "jane@acmestorage.com", contactPhone: "+15125550100",
});
// 4. Wait for approval, then register a campaign.
// (Poll tiyo.messaging.brands.refreshStatus(brand.id) or wait for the
// messaging.brand.approved webhook.)
const campaign = await tiyo.messaging.campaigns.create({
brandId: brand.id,
useCase: "account_notification",
description: "Rent reminders + payment confirmations to opted-in tenants.",
messageFlow: "Tenants opt in via the lease form on acmestorage.com/lease.",
messageSamples: ["Hi {name}, rent of ${amount} is due {date}."],
helpMessage: "Reply with questions or call +15125550100.",
});
// 5. Once the campaign is approved, attach the number.
await tiyo.messaging.campaigns.attachNumbers(campaign.id, [num.id]);
// 6. Send away.
const sent = await tiyo.messaging.sms.send({
to: "+14155551234",
body: "Hi Jane, your rent of $129 is due Friday. Reply STOP to opt out.",
from: num.id,
});
console.log(sent.id, sent.from);
// Voice works the same way — `tiyo.messaging.voice.call({ from: num.id, to, twimlUrl })`.
```
---
## 13. Minimal end-to-end example (Node/TS)
```ts
import { Tiyo } from "tiyo-sdk";
const tiyo = new Tiyo({
apiKey: process.env.TIYO_API_KEY!,
apiSecret: process.env.TIYO_API_SECRET!,
});
// 1. Create a customer.
const cust = await tiyo.customers.create({
first_name: "Jane",
last_name: "Doe",
email: "jane@example.com",
});
// 2. Mint a checkout session and redirect.
const session = await tiyo.checkout.sessions.create({
amount: 5000,
reference: "order-1234",
customer_id: cust.id,
save_card: true,
return_url: "https://yoursite.com/thanks",
}, { idempotencyKey: "checkout-order-1234" });
console.log(session.url);
// 3. Register a webhook to hear about it.
const hook = await tiyo.webhooks.create({
url: "https://yoursite.com/hooks/tiyo",
events: ["payment.completed", "payment.declined"],
});
console.log("SAVE THIS NOW:", hook.secret);
// 4. Your /hooks/tiyo handler:
// - raw-parse the body
// - verify X-Tiyo-Signature (see §8.2)
// - switch on req.body.type
```
---
## 14. Things that commonly trip integrators up
1. **Amounts are cents.** Sending `5.00` instead of `500` is almost
certainly wrong. The gateway never does float math.
2. **Idempotency-Key is required on `POST /v1/payments`.** Missing → 400.
3. **`X-Merchant-Id` is silently ignored if invalid.** The API falls back
to your primary merchant. If your list looks wrong, check the cookie /
header.
4. **Card-present charges hold the connection open.** Don't set a tight
HTTP timeout; SPIn terminals can take up to 180 s.
5. **`status` on a 201 is not necessarily "approved".** Check
`response.status` — it can be `approved`, `declined`, `failed`, or
`canceled` (CP only).
6. **Webhook secrets appear only once.** On create and on rotate.
Persist immediately; can't retrieve later.
7. **Catalog / product `updated_at` was added recently.** If you've been
using the gateway pre-2026-04-23, rows created before that date will
have a synthetic `updated_at = NOW()` from the migration — a single
full fetch is recommended before your first incremental sync.
8. **Deleting a customer is soft.** Status flips to `inactive`; active
subscriptions cancel and active recurring billings pause. Cards stay
on file (but idle).
---
## 15. Where to look in the source code (the gateway is open source)
- Edge function root: `supabase/functions/api/`
- `app.ts` — Hono route mounts
- `auth-middleware.ts` — JWT verify + role / access resolution
- `access.ts` — which merchants can this developer see
- `providers.ts` — EPX North, Paya, Vericheck, Dejavoo iPOSpays, SPIn,
Linked2Pay adapters
- `service-payment.ts` — the actual charge pipeline
- `service-webhook.ts` — signature + retry schedule
- `routes-*.ts` — one file per resource family
- `schema.ts` — Drizzle ORM tables; same field names you see on the wire
(camelCase in the DB, snake_case on the wire via formatters)
---
## 16. When in doubt
- Every response has `Tiyo-Request-Id`. Save it.
- Every list endpoint mentions its filters in its route file.
- Check `GET /v1/openapi.json` for the machine-readable source of truth.
End of document.