Merchant integration guide

1. Sandbox quick start

Every merchant starts in sandbox. Sandbox loans settle against a simulated chain (no real testnet funds required) so you can build and test your whole integration before certifying for go-live. Create a sandbox account to get your first API key.

curl -X POST https://api.stao.io/v1/loans \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "loanProductId": "...",
  "borrowerRef": "user-123",
  "borrowerWalletAddress": "0x...",
  "chain": "POLYGON_AMOY",
  "principalAmount": "250.00",
  "idempotencyKey": "order-9F21"
}'

Supported chains. Sandbox tenants always run on a testnet. Once a tenant completes go-live certification, requests may target a live network instead — pass the matching value in chain:

On TON the settlement asset is USDT (a TEP-74 jetton), not USDC, and collateral is not supported. Borrower addresses are accepted in either user-friendly (EQ… / UQ…) or raw (0:…) form. Live-chain access is enabled per tenant after go-live certification (section 12). Requests with a live chain value move real funds — there is no faucet and transactions are irreversible once confirmed on-chain.

2. Authentication

Two credential types, two audiences. Use the one that matches who is calling.

API keys are shown once on creation and stored hashed, copy it immediately. Revoking a key takes effect immediately on the next request.

3. Identifiers & idempotency

Every loan gets an immutable id (UUID) the moment POST /v1/loans or the embed /accept call succeeds. It never changes and is the join key across the API, dashboards, webhooks, and notifications, store it against your own order/application record.

Pass idempotencyKey on every loan-creation call (max 255 chars, your own order id works well). If a request is retried with the same key, you get back the original loan instead of a duplicate. Without it, a network retry on your side can create two loans for one purchase.

4. Loan lifecycle

A loan's status field moves through one path:

CREATED -> ACTIVE -> REPAID
            -> DEFAULTED   (past due date + grace period, unpaid)

Underwriting runs synchronously on creation and records a decision, APPROVED, DECLINED, or MANUAL_REVIEW. A declined loan never leaves CREATED; the dashboard and GET /v1/loans filters surface it as a synthetic DECLINED state derived from that decision, alongside the real LoanStatus values, so declined applications stay visible instead of disappearing.MANUAL_REVIEW loans wait for an ops reviewer; watch for loan.approved or loan.rejected.

5. Funding & repayment

Stao is non-custodial: we never hold your borrower's funds. On APPROVED, principal is drawn from your tenant's liquidity pool (your own LP, or the shared pool) and sent on-chain directly to borrowerWalletAddress. The loan moves to ACTIVE once that transaction confirms and loan.funded fires. If funding can't be completed (for example no LP wallet has enough headroom) the loan stays CREATED and loan.funding_failed or liquidity.unavailable fires instead.

To collect a repayment, call POST /v1/loans/:id/repay, it returns an unsigned transaction for the borrower's own wallet to sign, never a charge you initiate on their behalf. Once that transaction confirms on-chain, our settlement listener records it, the loan moves to REPAID, and loan.repaid fires. See GET /v1/settlements/:loanId for the full settlement history of a loan.

https://merchant.stao.io/embed/YOUR_EMBED_KEY/repay/LOAN_ID

GET https://api.stao.io/v1/embed/YOUR_EMBED_KEY/loans/LOAN_ID/repayment-instructions

{
  "chain": "TON",
  "supported": true,
  "to": "UQ...",                     // platform settlement wallet
  "asset": "USDT",
  "amount": "5.099986",              // total due today (6dp)
  "amountUnits": "5099986",          // jetton base units
  "comment": "stao:repay:LOAN_ID",   // REQUIRED transfer comment
  "jettonMaster": "EQ...",
  "links": {
    "ton": "ton://transfer/...",
    "tonkeeper": "https://app.tonkeeper.com/transfer/..."
  }
}

Loans unpaid past dueAt fire loan.overdue; if still unpaid after the grace period they're auto-marked DEFAULTED (loan.defaulted) and any pledged collateral is seized.

6. KYC responsibilities

Stao does not collect, store, or verify identity documents. You are the responsible party for knowing your borrower under your own AML/KYC program. Once you've verified a borrower, tell us the outcome:

curl -X PATCH https://api.stao.io/v1/borrowers/:id/kyc \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "status": "VERIFIED", "merchantUserId": "agent_482" }'

status is one of PENDING, VERIFIED, FAILED. merchantUserId is your own internal reference for who/what performed the check, we stamp verifiedAt and write an immutable audit record on every change. Your underwriting policy can require VERIFIED before a loan is approved (see GET/PUT /v1/policies).

curl -X POST https://api.stao.io/v1/loans/LOAN_ID/kyc-confirmation \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
  "verified": true,
  "merchantUserId": "BION_INTERNAL_REFERENCE",
  "reference": "KYC_CASE_2026_00482"
}'

curl -X POST https://api.stao.io/v1/loans/LOAN_ID/agreement \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
  "walletSignature": "0x8f2c...BORROWER_WALLET_SIGNATURE",
  "agreementChallengeId": "SERVER_ISSUED_SINGLE_USE_CHALLENGE_ID",
  "agreementText": "THE EXACT AGREEMENT TEXT SHOWN TO THE BORROWER"
}'

7. Widget / iframe embed

The fastest integration path: no backend loan-creation code at all. Create a widget program on the Credit page of the merchant dashboard. Each program has its own embed key, network, asset, loan product and allowed origins, so it can coexist with native integrations such as a Telegram Mini App. Polygon/USDC and Base/USDC use Reown AppKit for MetaMask, Trust, Coinbase, injected wallets and WalletConnect QR/deep-link connections. The same wallet session signs the revolving agreement, confirms Drawdowns and submits network-matched USDC repayments.

<iframe
  src="https://merchant.stao.io/embed/YOUR_EMBED_KEY"
  style="width:100%;height:640px;border:0"
></iframe>

Or use the responsive launcher for websites and mobile-app WebViews:

<script
  src="https://merchant.stao.io/widget.js"
  data-embed-key="YOUR_EMBED_KEY"
  data-channel="WEB"
></script>

Set data-channel to WEB, IOS, ANDROID orPARTNER_WEBVIEW. STAO records the program and channel on the loan and includes both in webhook envelopes. For MVP these programs keep exposure separate from native channels.

The embed page walks the borrower through wallet eligibility, reusable KYC, the revolving credit-line agreement, Drawdown selection and repayment. When KYC is required it posts astao:kyc-required message to the parent page; the merchant completes its own KYC and calls the borrower credit-line agreement endpoint from section 6. The widget then resumes without repeating wallet analysis, KYC or agreement acceptance. It is branded with your logo and primary color and always shows "Powered by Stao".

8. Branding & credit config

Configured on the Credit page of the merchant dashboard, changes apply immediately to both the widget and any loans you create via the API.

9. Webhooks

Register an endpoint from the Webhooks page (or POST /v1/webhooks) with a URL and the event types you want. Every delivery is a signed POST with a JSON body; verify it before trusting it:

x-stao-event: loan.funded
x-stao-signature: <hex hmac-sha256 of the raw body>

// verify (Node):
const expected = crypto.createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(rawRequestBody).digest('hex');
if (expected !== req.headers['x-stao-signature']) return res.status(401).end();

Failed deliveries retry up to 3 attempts with backoff. After the final attempt fails, a webhook.delivery_failed notification is raised so it doesn't fail silently, check delivery history any time under GET /v1/webhooks/deliveries or the Webhooks page.

Every event above also appears in the merchant dashboard's Notifications page and is emailed to the account owner, webhooks are for your systems, notifications are for your team.

10. Error handling

Errors are plain JSON: { "statusCode": 400, "message": "...", "error": "Bad Request" }.message is either a string or an array of field-level validation messages.

11. Test scenarios

Sandbox tenants run on a simulated chain, so funding and repayment settle instantly without real testnet tokens. Before requesting go-live, exercise at least these paths end to end:

12. Go-live checklist

Sandbox certification runs through a fixed 10-step checklist inside your merchant dashboard (Partner onboarding) before we flip you to production credentials, it covers, in order:

1. KYB documents approved
2. Commercial terms agreed
3. Active underwriting policy
4. Active loan product
5. Funding liquidity available (your own LP or the shared pool)
6. Webhook endpoint configured
7. API key issued
8. Owner user account exists
9. Branding configured (company name set)
10. At least one loan has completed a full sandbox cycle (funded and repaid)

Track progress and submit for review from the Partner onboarding page in your dashboard.