# Getting started — integrate Sika

For **banks, marketplaces, hotels, restaurants**, and other businesses in Ghana that want to accept or request payments without taking custody of user keys.

Sika is **non-custodial**: your customer always signs in their own wallet. You never receive private keys.

## What you can build

| Pattern | Best for | How it works |
|---------|----------|--------------|
| **Accept payments** | Hotels, restaurants, markets | Show a QR / pay link / account; customer opens Sika and pays |
| **Request via API** | Marketplaces, delivery, chat bots | Your backend mints a short-lived pay intent; customer opens `/app/send?intent=…` and signs |
| **Open wallet to sign** | Banks / advanced apps | Deep-link or WharfKit session so the user signs a prepared action |

## Fee schedule (summary)

- **P2P:** 0% platform fee  
- **Commerce list:** **1.5%** (merchant-absorbed)  
- Volume / banks: negotiated after access review  

Full table: [FEES.md](./FEES.md).

## Request access {#request-access}

Onboarding is **apply → review → approve** (not open self-serve signup). After approval you get a mint secret and can use the **merchant portal**.

1. Open [Request access](/developers/access) on the marketing site (or email the team).  
2. Tell us business type, country, expected monthly volume, and contact.  
3. After review we issue:
   - `merchantId`
   - mint secret (server-side only; rotate anytime in the portal)
   - sandbox vs production base URL
   - contracted `feeBps` if not list rate  
4. Sign in at [/partners/login](/partners/login) with your approved email (magic link) to manage keys, preview fees (platform vs rail), and see recent intents.

Until credentials arrive, use the public docs and fee quote helpers only — do not ship a shared global secret in a client app.

## Path A — Accept payments (no mint API)

1. Create or connect a Sika / Antelope account for the business.  
2. Share **receive** QR or pay link from `/app/receive` (or encode your account + amount).  
3. Customer pays from Sika; you reconcile on-chain / Hyperion.  
4. Commerce fee applies when the payment is treated as a merchant checkout (see FEES).

Good first step for restaurants and hotels.

## Path B — Request payment via API

1. Obtain mint credentials (Request access).  
2. From **your server only**, `POST /api/v0/pay/intent` with Bearer secret:

```http
POST /api/v0/pay/intent
Authorization: Bearer <merchant_mint_secret>
Content-Type: application/json

{
  "to": "hotel.acc",
  "amount": "100.00",
  "memo": "Room 214",
  "ttlSec": 900
}
```

3. Send `href` to the customer (WhatsApp, SMS, email, QR).  
4. Customer opens Sika, reviews amount + fee breakdown, signs.  
5. You verify settlement via explorer / Hyperion (never ask the user for keys).

Mint rejects amounts so small that the platform fee rounds to zero at the token
precision (see [FEES.md](./FEES.md)). Prefer face amounts that clear that floor.

Details: [API.md](./API.md).

## Path C — Open wallet / embed sign

1. Deep-link to Sika (`/app/send?…` or Capacitor `sika://…`).  
2. Or use WharfKit `session.transact` in a first-party web surface the user trusts.  
3. User signs; you never host seed phrases.

This is for advanced partners (banks, custom POS). Prefer Path A/B unless you have a security review.

## Sandbox checklist

- [ ] Staging base URL from the access letter  
- [ ] Mint secret only in server env  
- [ ] Test intent → open `/app/send?intent=` → confirm fee lines  
- [ ] Expired token returns a clear error  
- [ ] No secrets in mobile apps or frontend bundles  

## Security

Read [SECURITY.md](./SECURITY.md). Short version: HTTPS only, secrets server-side, user always signs, no custody.

## What we do not document publicly

Internal identity org keys, settlement workers, mock KYC, faucet internals, and unreleased product IP. On-chain contracts and the public pay-intent shape are enough to integrate.