Webview Integration API Specification

1. Overview

Artham's investment marketplace runs inside a webview hosted in your app. Your app renders a row of scheme cards from data Artham serves; when the user taps one, your app asks Artham for a URL and opens it in a webview. Everything after that point — scheme detail, onboarding, consent, mandate and investing — happens inside Artham's web application. Your app hosts the frame and nothing else.

How It Works

1. Sign each request — every call carries an API key and an HMAC signature. There is no login step and no token to manage (Section 2).
2. Fetch the schemes — one call returns every scheme available to your brokerage, with the summary fields your cards need (Section 4).
3. Render cards in your app — your UI, your styling. Artham supplies the data, not the layout.
4. Hand off on tap — the user taps a card, or your Artham header entry point. Your app calls Artham for a client-specific, pre-signed URL and opens it in a webview (Section 5).
5. The journey continues in the webview — Artham handles the rest and signals back when the user exits (Section 6).

API Summary

Base URLs

Production:  https://api.artham.co
Sandbox:     https://distributor-api.artham.co

2. Authentication

Every request carries two headers: an API key that identifies your brokerage, and an HMAC signature that proves the request is yours and has not been altered. There is no login call, no token and no session to refresh.

Signature Computation

message = "{HTTP_METHOD}\n{path}\n{body}"

signature = HMAC-SHA256(key: SHARED_SECRET, message: message)
            → output as lowercase hex string

Worked Examples

Both examples use the demo secret below, so you can verify your implementation before your credentials arrive — the same inputs must produce the same digests.

secret = "artham_demo_secret_9f2b7c41e8d3"

# ─── API 1 — GET, no body ───────────────────────────────────
message   = "GET\n/api/v1/partner/schemes\n"
signature = 40f682d026b436293288648b8553927c398689f336b65f23136a081fe491c61d

# ─── API 2 — POST, body included ────────────────────────────
body      = {"clientCode":"PL889900","schemeCode":"ARTHAM-EQ-001"}
message   = "POST\n/api/v1/partner/webview/link\n" + body
signature = 065d4730e9fe6ed227f4902869d0415c2851b10cef40252339eb0fe9921a9db1

The API 1 call, against Sandbox:

curl -X GET "https://distributor-api.artham.co/api/v1/partner/schemes" \
  -H "X-Api-Key: <your API key>" \
  -H "X-Signature: <64-char lowercase hex>"

Credential Handling

Authentication Errors

3. Error Handling

Every endpoint in this document answers with the same envelope.

Success

{
  "success": true,
  "data": { ... },
  "error": null
}

Error

{
  "success": false,
  "data": null,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "No client found with code PL889900."
  }
}

HTTP Status Codes

4. API 1 — Scheme List Required

Returns every scheme your brokerage is permitted to distribute, with the summary fields needed to render cards. Call it when your discovery screen loads, or cache it and refresh a few times a day.

{
  "success": true,
  "error": null,
  "data": {
    "count": 2,
    "returnsAsOf": "2026-08-31",
    "schemes": [
      {
        "schemeCode": "ARTHAM-EQ-001",
        "schemeName": "Quality Compounders",
        "advisorCode": "MRC",
        "advisorName": "Marcellus Investment Managers",
        "logoUrl": "https://artham-assets.s3.eu-north-1.amazonaws.com/advisors/mrc.png",
        "category": "Large Cap",
        "riskLevel": "Moderate",
        "shortDescription": "Twelve clean-accounting compounders, held through cycles.",
        "benchmark": "NIFTY 50 TRI",
        "minInvestment": 500000,
        "feePercent": 2.5,
        "aum": "1284500000.00",
        "inceptionDate": "2021-04-01",
        "constituentCount": 12,
        "returns": {
          "1m": "1.8400",
          "6m": "9.2100",
          "1y": "18.4200",
          "3y": "21.0500",
          "5y": null,
          "sinceInception": "19.7700"
        },
        "navSeries": [100.0, 102.4, 101.8, 106.2, 109.7, 108.3,
                      112.9, 116.4, 115.1, 119.8, 123.5, 126.1]
      }
    ]
  }
}

5. API 2 — Webview Link Required

Call this the moment the user taps a card or your Artham entry point, and open the returned URL in a webview. The URL is pre-signed and specific to one client — it carries the session, so the user is never asked to sign in to Artham.

{
  "clientCode": "PL889900",
  "schemeCode": "ARTHAM-EQ-001"
}

{
  "success": true,
  "error": null,
  "data": {
    "url": "https://invest.artham.co/discover/quality-compounders?t=eyJhbGciOi...",
    "target": "SCHEME",
    "expiresAt": "2026-09-01T10:35:00+05:30",
    "ttlSeconds": 300
  }
}

6. Inside the Webview

Once the URL is open, the journey is Artham's: scheme detail, risk profiling, KYC, advisory consent, mandate setup and order placement. Your app does not need to implement, mirror or track any of these steps. What it does need is a webview configured to let them work.

Webview Requirements

Exiting

Artham signals completion or a user-initiated exit by posting a message to the webview host:

{ "source": "artham", "event": "EXIT", "reason": "COMPLETED" | "USER_CLOSED" }

Close the webview when you receive it. reason is informational — both cases mean the same thing for your app. Also give the user your own way out, such as a close button in your chrome, so a network failure inside the webview cannot trap them.

7. Sandbox & Testing

Integration Steps

1. Artham shares credentials — an API Key and Shared Secret for Sandbox, sent over a secure channel.
2. You wire up the two calls — scheme list and webview link, both signed, both from your backend.
3. You build the cards — using the API 1 fields, in your own design.
4. End-to-end test — you launch the webview for a test client against Sandbox, and we walk one full journey together, from card tap through to a placed order.
5. Go live — we issue production credentials. No code change beyond the base URL and the credentials.

Test Checklist

Authentication

API 1 — Scheme List

API 2 — Webview Link

Webview

Support

For integration questions, contact the Artham engineering team:

• Email: rahul@artham.co
• We are available for joint debugging calls during integration.