Sharet API docs

Quickstart

1. Create a sandbox key (sk_test_…) in Developers › API keys and give it the scopes you need.
2. Check it works:

3. Pay someone in the sandbox (no real money moves):

When you're ready, verify your business and create a live key (sk_live_…) with your servers' IP addresses.

Sharet IDs and @names

Every person and business has a Sharet ID, like SH-4K7Q2M. It never changes and is never reused, and every settlement, webhook and statement is tied to it. An @name (like @mwangihardware) is the alias people see and type; you can send it, and we always resolve it to the Sharet ID and return that. Renaming an @name never redirects money.

Names come back shortened (Akinyi W.) so lookups can't be used to collect people's full names. GET /accounts/me returns your own Sharet ID, @name, verification level, balance and the key's scopes.

Keys, scopes and IPs

Send your key as Authorization: Bearer sk_…. A business's keys act for the business's own Sharet wallet; we keep only a fingerprint, so copy a key when it's shown.

• Sandbox and live are separate. sk_test_ keys never move real money; sk_live_ keys need a verified business.
• Live payouts need an IP allow-list: list your servers' addresses or ranges on the key. Calls from anywhere else get ip_not_allowed.
• Large batches need a second person: live batches over KES 500,000 wait in Dashboard › API approvals for someone else from your business.

Requests and retries

• Idempotency: every call that moves money (and creating a payment request) takes an Idempotency-Key header, 8–80 characters, one per payment. Retrying with the same key returns the first answer (with Idempotent-Replay: true) and never pays twice. Refusals aren't remembered, so you can fix the problem and retry with the same key.
• Amounts are strings with two decimals and no separators, in whole shillings: "35000.00".
• Errors are application/problem+json with a stable type; see Errors.
• Sandbox and live data are separate: a key only sees objects from its own environment.
• Pauses: if Sharet pauses payments for safety, money calls answer 423; nothing moves and you can retry later.

Quotes

See the exact fee and total before paying. Nothing moves.

Destinations (to): {"sharet_id": "SH-…"} or {"handle": "@name"} (free and instant), {"type": "mpesa"|"airtel"|"tkash", "phone": "0722 000 904"}, {"type": "till", "till": "512334"}, {"type": "paybill", "paybill": "247247", "account": "…"}, {"type": "bank", "bank": "equity", "account": "…"} (PesaLink; banks: equity, kcb, ncba, imbank, coop, absa, stanbic, family).

Payments out

POST /payments (scope payout, Idempotency-Key) pays from your account's wallet. The response includes the fee, total and status: paid straight away for Sharet accounts, paying while M-PESA or the bank works, then paid, failed or refunded (a failed payout's money comes back to your wallet). Follow it with GET /payments/{id} or a webhook.

Payment requests

POST /payment-requests (scope collect, Idempotency-Key) asks someone to pay you and returns a pay link (pay_url). They pay from their Sharet wallet (signed in, with their PIN, free) or by an M-PESA prompt to any phone. The money lands in your wallet. No call can take money from someone's wallet without them approving it.

If you name a payer, only that Sharet account can pay from a wallet. GET /payment-requests/{id} shows the status (open, paid, expired, cancelled); POST /payment-requests/{id}/cancel closes it.

Split settlement

Add splits to a payment request and, once it's paid, every leg is paid from your wallet to the recipients' Sharet IDs together or not at all. Legs are percentages or fixed amounts in whole shillings; what isn't in a leg (your "self" share and rounding) stays with you.

Legs go to Sharet accounts only (up to 10, each account once). If a leg can't be paid, none are, the money stays in your wallet and settlement.failed says why; fix it and retry with POST /payment-requests/{id}/settle.

Batch settlements

POST /settlements (scope payout, Idempotency-Key) pays up to 500 items in one call. Every item is checked first: if any is wrong, nothing is paid and errors lists them by index. Each item is then paid like POST /payments; a refused item is recorded as failed without stopping the others.

Live batches over KES 500,000 return 202 awaiting_approval and run once a different person from your business approves them in Dashboard › API approvals.

Connected accounts

Platforms (like a property manager) can collect and settle for their users, in their users' own Sharet accounts, with their consent.

1. POST /connect/links (scope connect) with {"scopes": ["collect", "payout"], "reference": "landlord-17", "return_url": "https://…"} returns a link, valid 7 days.
2. The person opens it, signs in, reads exactly what you may do, and approves with their PIN (or declines). They come back to your return_url with ?connection=…&status=active.
3. Act for them by adding Sharet-Account: SH-… to your calls, only within what they approved; their own limits apply. Sharet ↔ Sharet is free; sending outside Sharet is charged.
4. List them with GET /connect/accounts; either side can disconnect at any time (POST /connect/accounts/{id}/disconnect, or Account › Connected apps).

Webhooks

Register an endpoint with POST /webhooks {"url": "https://…", "events": [...]}; the response includes a whsec_… secret, shown once. Events: payment.paid, payment.failed, payment.refunded, payment_request.paid, payment_request.expired, settlement.completed, settlement.failed, settlement.awaiting_approval, account.connected, account.disconnected.

Every delivery is signed. Check the signature before trusting it, ignore repeats by id, answer 2xx quickly, and confirm with a GET when it matters. We retry for 24 hours.

Errors

Errors are application/problem+json: {"type": "https://sharet.africa/docs/errors#…", "title": "…", "status": 422, "detail": "…"}, sometimes with errors by field. Use type in your code; show detail to people.

Sandbox

• Use sk_test_ keys: same endpoints, simulated money, nothing touches real balances.
• The M-PESA number 0700 000 002 always fails; every other destination succeeds.
• Sandbox pay links show Simulate paid and Simulate cancel buttons.
• Webhooks fire in the sandbox too, to endpoints registered with a test key.

Pricing

Sharet ↔ Sharet is always free, including splits and connected accounts. Outside payouts are priced from two tables: a fee by movement type and amount, then a discount by your outside payouts this month. Every quote and payment shows the fee, the tariff version and your discount before money moves. Sharet's own companies are priced one tier up.

Limits

• 60 requests a minute per key to start; batches up to 500 items; splits up to 10 legs.
• Payment limits follow the paying account's verification: verified businesses have business limits; connected people keep their own.
• Kenyan shillings only for now; Tanzania is next after the Kenya pilot.

Questions? Talk to us, or request sandbox access.