Developers
Merchant API v1
Create saved merchant orders and test your checkout handoff in the sandbox. Buyers submit ID/passport and selfie photos privately for human review, not automated identity or liveness checks. Funding, custody and transfers are unavailable. External production API access is not yet available.
Create a checkout session
Upload your own product first: POST /api/v1/media with Authorization: Bearer <merchant key> and multipart field file. New keys include media:upload; older keys must be replaced. A 201 response returns id and image: media:<uuid>. Use that image value in items[].image when creating checkout. Media ownership is checked against the API key tenant; unrelated media is rejected with 403.
// Merchant backend only; keep the key in your server secret store.
const form = new FormData();
form.set('file', new File([imageBytes], 'product.png', { type: 'image/png' }));
const upload = await fetch(APP_ORIGIN + '/api/v1/media', {
method: 'POST', headers: { Authorization: 'Bearer ' + MERCHANT_KEY }, body: form
});
if (!upload.ok) throw new Error('Upload rejected');
const media = await upload.json();
order.items[0].image = media.image;
// POST order to /api/v1/checkout-sessions using the same key and a unique Idempotency-Key.Uploads accept signature-matched JPEG/PNG/WebP up to 5 MiB, reject SVG/HTML and unsafe supplied names, and generate private random object names. Arbitrary remote fetching stays disabled. Order parties receive five-minute signed image reads; checkout-token previews reveal only product images, not evidence. No ID documents are allowed in the merchant media API; identity pictures use the separate buyer-only review upload flow. Existing fixed stock-image references remain compatible.
POST /api/v1/checkout-sessions
Authorization: Bearer <your newly issued pe_sandbox_... key>
Idempotency-Key: <unique per order>
Content-Type: application/json
{
"mode": "sandbox",
"merchant_reference": "TEST-1042",
"buyer": { "email": "buyer@example.invalid", "name": "Synthetic buyer" },
"items": [{ "title": "Sandbox watch", "quantity": 1,
"unit_price": "125.000001", "image": "/__l5e/assets-v1/23a7cc25-d992-409a-852a-1cea546df175/hero-watch-stock.jpg" }],
"shipping": "5.00",
"fees": { "amount": "1.25", "description": "Synthetic fee — no funds" },
"total": "131.250001", "currency": "USDT",
"inspection_days": 3,
"delivery_terms": "Synthetic tracked delivery within 7 days"
}Issue a key in your merchant workspace. Keys have checkout:create scope, belong to one organisation and mode, are shown once, hashed at rest and can be revoked. Requests must supply an Idempotency-Key of 1–128 printable non-space ASCII characters. Decimal strings support six places; arithmetic uses USDT base units. Positive item prices, 1–1000 quantity, 1–20 items, 1–30 inspection days and a maximum total of 1,000,000,000 USDT are enforced. Unknown fields and payment states are rejected.
201 Created
{ "id": "<order uuid>", "checkout_path": "/checkout/<opaque token>",
"expires_at": "<timestamp>", "mode": "sandbox", "funding": "blocked" }Same tenant/idempotency key and same normalized payload return the original checkout, without a second order or event. A changed payload returns 409. Tokens expire after 24 hours. Keep tokens and API credentials out of logs. Prices, items, merchant name and terms are immutable once accepted.
Buyer linking and private access
Checkout projects product information only, never buyer contact. Live orders require a signed-in email-verified account matching the intended buyer. Sandbox orders accept any verified account holding the link and use synthetic example.invalid contact details; no emails or funds are sent. Claims are atomic: the first eligible buyer owns the order, other users cannot reuse it. The owner can repeat a successful claim safely. Checkout continuation is stored in expiring same-origin session state through sign-in and signup, not an arbitrary return URL. Buyer email verification is not identity verification.
GET /checkout/:token is the private invitation page. Authenticated order views live at /orders/:id; database authorisation is required, not just an ID. Buyer confirmation creates an immutable event. Only owning merchants and linked buyers can read their orders/history. Dashboard search by merchant reference and state is paginated in 20-record pages with tenant-scoped queries. Shipment notes and sandbox dispute messages/evidence are private, immutable and expected-state checked.
Verification before payment
After intended-buyer verified-email claim, the buyer confirms immutable imported details and terms, then opens /orders/:id/verification. Optional billing and delivery objects include name, optional phone, and address (line1, optional line2, city, optional region, postal_code, two-letter uppercase country). These are private snapshot fields; corrections require a new merchant-authorised order/reference. Totals display exact six-decimal USDT.
Identity cases are buyer-private and server-owned. Private raw ID/passport and selfie capture and human administrator review are implemented through the dedicated identity workflow. No specialist adapter, callback or automated biometric/liveness verification is configured. Only visibly labelled sandbox cases can simulate verification; production verified status is prohibited. Manual approval is labelled as human review and never changes financial eligibility. Document photos accept JPEG/PNG up to 8 MiB, 4096 pixels per side and 12 megapixels. A shared server decision denies all live funding requests and financial eligibility, returning unavailable with no address, QR or payment intent. An email-confirmed account is not KYC approval.
Request limits
Both APIs authenticate the scoped key, then atomically consume one request against its key and merchant quotas before reading the body. Defaults per 60-second fixed window: checkout 60 per key / 120 per merchant; media 15 per key / 30 per merchant. Keys and modes share the merchant endpoint quota, so rotation cannot reset it. Invalid authenticated requests and idempotent retries consume capacity; rejected requests do not increase counters.
429 rate_limited returns Retry-After in seconds and X-RateLimit-Reset as a Unix timestamp, plus X-RateLimit-Tenant-Limit, X-RateLimit-Key-Limit, X-RateLimit-Remaining and X-RateLimit-Window. Remaining is the smaller key/tenant allowance. Reset and retry timing come from the database. Limiter failures return 503 limiter_unavailable without reading the body; Retry-After is 5 seconds. Wait before retrying, retaining your original idempotency key.
Quotas are privileged server configuration, not customer-editable settings. At most two counter rows per merchant and 128 distinct key counters per endpoint window are stored; further distinct keys receive 429 key_slots. Windows reset in place. Bounded cleanup removes at most 100 rows expired over a day during authenticated consumption; no permanent polling job exists. No raw token, address, IP or request body is stored in counters.
Errors and deployment boundary
400 invalid/missing idempotency key; 401 missing, invalid or revoked API key; 403 mode/scope mismatch; 409 idempotency conflict; 410 expired checkout; 413 JSON payload over 32,000 bytes (streamed, including chunked requests); 415 unsupported type/encoding; 422 invalid data/totals; 429 exhausted key/merchant capacity; 503 unavailable limiter/order/signing service. Media multipart bodies are streamed with a 5 MiB file cap plus 16 KiB framing cap. Declared lengths are validated but do not replace measured byte limits. API responses are no-store. No trusted anonymous caller signal has been established: forwarding headers are not trusted. Hosting/WAF global anonymous request-rate, connection and timeout limits remain deployment requirements. No cross-origin browser CORS is enabled: call from your server.
The requested /api/v1/checkout-sessions route is implemented. An unpublished or restricted Lovable deployment may also require site access before the API handler; externally reachable integration is not claimed until deployment access is verified. No /api/public alias or user-session-token sharing is provided.
Sandbox transitions and financial boundary
After buyer confirmation of imported details and a separately labelled sandbox identity simulation, merchants may simulate funding then delivery. Buyers may inspect, dispute or accept after the appropriate preceding state. Every synthetic event is tagged and stays in sandbox order records; no financial ledger exists. Live transitions reject without provider and verified funding evidence. Administrators have read-only operational counts and separately authorised manual document review; roles must be provisioned separately; no money-confirmation button exists.
Webhooks
Tenant-scoped event outbox and destination settings are implemented; remote delivery is disabled because secure DNS/IP-pinned egress cannot currently be guaranteed. Events are not marked sent. A stored HTTPS hostname is not proof it resolves publicly; no requests, redirects, remote image fetching or email sends occur. Private merchant uploads replace arbitrary external images. In-app notifications are deduplicated by event and recipient; email readiness is not configured and no email sender is invoked.
Future transport contract, not active delivery: HMAC-SHA256 over timestamp + "." + raw JSON body, header X-Payescrow-Signature: t=<unix seconds>,v1=<hex digest>. Verify with a constant-time comparison, reject timestamps outside five minutes, and deduplicate by event_id. Retries are bounded to five attempts (1 minute, 5 minutes, 30 minutes, 2 hours, 24 hours). Outbox event IDs are unique; no retry worker is active. A shared signing secret and secure egress must be configured before enabling this contract.